Using the Client and Loader Tools
Using the Client and Loader Tools
This section provides the information required to set up your Greenplum Database client runtime environment and use the client and loader tools. Topics include:
Prerequisites
Before using the client and loader tools, ensure that:
- Your Greenplum Database cluster is up and running, and you can identify the master host and port number, if the master server process is not running on the default port (5432).
- Network connectivity exists between the client machine and the Greenplum Database master host. If you are using the gpfdist, gpload, or gpss utility programs, network connectivity must also exist between the client machine and all Greenplum Database segment hosts.
- You have installed and configured the tools and any dependent components on your client machine as described in Installing the Client and Loader Tools Package.
- You can identify your Greenplum Database user/role name and password.
- You have created or can identify the Greenplum database, schema, and table objects of interest.
Contact your Greenplum Database administrator if you do not meet the prerequisites mentioned above.
Setting Up Your Greenplum Database Clients Runtime Environment
The client and loader tools package installs a file that you use to set up your Greenplum Database client and loader environment. This script or batch file, named greenplum_clients_path.<ext> (where the file extension <ext> is operating system- or shell-dependent) is located in the client tools root install directory.
greenplum_clients_path.<ext>:
- Sets the runtime environment variables that are required by the utilities.
- Sets the $GPHOME_CLIENTS environment variable to point to the root directory of the client and loader tools installation.
- Updates your $PATH to include $GPHOME_CLIENTS/bin.
You must source or run greenplum_clients_path.<ext> before you invoke any of the client or loader programs. For example, run the following command on a CentOS or Ubuntu system to source the file:
user@clientsys$ . /usr/local/greenplum-db-clients/greenplum_clients_path.sh
Running the Client and Loader Programs
Clients always connect to Greenplum Database through the master host. In order for the client or loader program to establish a connection to the master host, you provide the following connection parameters to the program via options, a configuration file, or environment variables:
Connection Parameter | Description | Environment Variable Name |
---|---|---|
Database name | The name of the database to which you want to connect. | PGDATABASE |
Host name | The host name of the Greenplum Database master. The default host is the local host. | PGHOST |
Port | The port number on which the Greenplum Database master server instance is running. The default port is 5432. | PGPORT |
User name | The Greenplum Database user (role) name. This name may not necessarily be the same as your operating system user name. | PGUSER |
Greenplum Database Documentation References
The following Greenplum Database documentation topics provide additional information about using selected client and loader tools:
- gpfdist - Using the Greenplum Parallel File Server (gpfdist)
- gpkafka - VMware Tanzu Greenplum Streaming Server Loading from a Kafka data source documentation
- gpload - Loading Data with gpload
- gpss, gpsscli - VMware Tanzu Greenplum Streaming Server documentation
- psql - Connecting with psql
Windows Considerations
Keep in mind these additional considerations when you use the Windows client and load programs:
- You must ensure that any ports that you identify in a gpload control file are unblocked by any firewall running on the Windows client system.
- By default, gpload.bat attempts to create a directory named gpAdminLog in the directory from which you execute the program, and writes its log files there. This operation will fail if you do not have write permission to the current working directory. Run gpload.bat with the -l option to direct the log output to a different location.
- Review the Greenplum Character Encoding and Formatting Rows documentation for Windows-specific considerations for the tools.