Installing the Greenplum Client Tools
A newer version of this documentation is available. Use the version menu above to view the most up-to-date release of the Greenplum 5.x documentation.
Installing the Greenplum Client Tools
This section contains information for installing the various client programs on your Windows machine and for enabling Greenplum Database to accept remote client connections:
- Running the Client Tools Installer
- Configuring the Client Tools
- Enabling Greenplum Database for Remote Client Connections
- Configuring a Client System for Kerberos Authentication
See the Greenplum Database Release Notes for the list of currently supported platforms for the Client Tools.
Running the Client Tools Installer
The Greenplum Database client tools installer installs psql.exe, the interactive command-line client interface to Greenplum Database.
To install the Greenplum Database client tools
- Download the greenplum-clients-<version>-WinXP-x86_32.msi package from Pivotal Network.
- Double-click on the greenplum-clients-<version>-WinXP-x86_32.msi package to launch the installer.
- Click Next on the Welcome screen.
- Click I Agree on the License Agreement screen.
- By default, the Greenplum Database client tools will be installed into greenplum-db-<version>. Click Browse if you want to choose another location.
- Click Next when you have chosen the install path you want.
- Click Install to begin the installation.
- Click Finish to exit the installer.
About Your Installation
Your Greenplum Database client tools installation contains the following files and directories:
- bin — client tools programs
- greenplum_clients_path.bat — sets environment variables
- lib — client tools library files
Configuring the Client Tools
Greenplum provides a batch program (greenplum_clients_path.bat) to set the required environment settings for Greenplum loader (located in greenplum-db-<version> by default).
To set the required environment settings
- Open a Windows command prompt (Start > Run and type cmd).
- At the command prompt, go to the directory where you installed Greenplum loader.
cd \"Program Files"\Greenplum\greenplum-clients-<version> dir
- Execute the greenplum_loaders_path.bat
The PostgreSQL command-line tools also require several connection parameters in order to be able to connect to a Greenplum database. In order to save some typing on the command-line, you can optionally create the following environment variables in your Windows Control Panel.
- PGDATABASE — The name of the default Greenplum database to connect to.
- PGHOST — The Greenplum Database master host name or IP address.
- PGPORT — The port number that the Greenplum master instance (postmaster process) is running on.
- PGUSER — The default database role name to use for login.
To add a new user environment variable on Windows XP
- In Windows Explorer, go to C:\\Control Panel.
- Double-click the System icon.
- On the Advanced tab, click Environment Variables (bottom).
- Click New.
- Define the new environment variable. For example:
- Click OK.
Enabling Greenplum Database for Remote Client Connections
In order for Greenplum Database to be able to accept remote client connections, you must configure your Greenplum Database master so that connections are allowed from the client hosts and database users that will be connecting to Greenplum Database.
To enable remote client connections
- Make sure that the pg_hba.conf file of the Greenplum Database
master is correctly configured to allow connections from the users to the database(s)
using the authentication method you want. For details, see "Editing the pg_hba.conf
File" in the Greenplum Database Administration Guide, and also see the
Greenplum Database Security Configuration Guide.
Make sure the authentication method you choose is supported by the client tool you are using.
- If you edited pg_hba.conf file, the change requires a server reload (using the gpstop -u command) to take effect.
- Make sure that the databases and roles you are using to connect exist in the system and that the roles have the correct privileges to the database objects.
Configuring a Client System for Kerberos Authentication
If you use Kerberos authentication to connect to your Greenplum Database with the psql utility, your client system must be configured to use Kerberos authentication. If you are not using Kerberos authentication to connect to a Greenplum Database, Kerberos is not needed on your client system.
- Setting Up a Client System with Kerberos Authentication
- Accessing Greenplum Database with psql
For information about enabling Kerberos authentication with Greenplum Database, see the chapter "Kerberos Authentication" in the Greenplum Database Administrator Guide.
The following are requirements to connect to a Greenplum Database that is enabled with Kerberos authentication from a client system with Greenplum Database client software.
- Kerberos must be installed and configured on the Greenplum Database master host. See "Enabling Greenplum Database for Remote Client Connections."
- The client systems require the Kerberos configuration file krb5.conf from the Greenplum Database master.
- The client systems require a Kerberos keytab file that contains the authentication credentials for the Greenplum Database user that is used to log into the database.
- The client machines must be able to connect to Greenplum Database master host.
If necessary, add the Greenplum Database master host name and IP address to the system hosts file. On Windows 7 systems, the hosts file is located in C:\Windows\System32\drivers\etc\.
Required Software on the Client Machine
- The Kerberos kinit utility. The kinit.exe
utility is available with Kerberos for Windows. Greenplum Database supports Kerberos
for Windows version 3.2.2. Kerberos for Windows is available from the Kerberos web
site http://web.mit.edu/kerberos/. Note: When you install the Kerberos software, you can use other Kerberos utilities such as klist to display Kerberos ticket information.
Setting Up a Client System with Kerberos Authentication
To connect to Greenplum Database with Kerberos authentication requires a Kerberos ticket. On client systems, tickets are generated from Kerberos keytab files with the kinit utility and are stored in a cache file.
- Install a copy of the Kerberos configuration file krb5.conf from
the Greenplum Database master. The file is used by the Greenplum Database client
software and the Kerberos utilities.
Rename krb5.conf to krb5.ini and move it to the Windows directory. On Windows 7, the Windows directory is C:\Windows.
If needed, add the parameter default_ccache_name to the [libdefaults] section of the krb5.ini file and specify the location of the Kerberos ticket cache file on the client system.
- Obtain a Kerberos keytab file that contains the authentication credentials for the Greenplum Database user.
- Run kinit specifying the keytab file to create a ticket on the
client machine. For the following example, the keytab file
gpdb-kerberos.keytab is in the current directory. The ticket cache
file is in the gpadmin user home directory.
> kinit -k -t gpdb-kerberos.keytab -c C:\Users\gpadmin\cache.txt gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
Accessing Greenplum Database with psql
From a remote system, you can access a Greenplum Database that has Kerberos authentication enabled.
- As the gpadmin user, open a command window.
- Run the client tool batch file from command window
Change the current directory to the bin directory of the Kerberos for Windows installation. For example:
> cd C:\test\MIT\Kerberos\bin
- Start psql from the command window and specify a connection to
the Greenplum Database specifying the user that is configured with Kerberos
The following example logs into the Greenplum Database on the machine keberos-gpdb as the gpadmin user with the Kerberos credentials gpadmin/kerberos-gpdb:
> psql -U "gpadmin/kerberos-gpdb" -h kerberos-gpdb template1
For information about running psql, see "Running the Greenplum Client Tools."