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
Note: Consider adding the command to source or run greenplum_clients_path.<ext> to your shell or equivalent initialization file.

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:

Table 1. Connection Parameters
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
Note: Refer to the Client and Loader Utility Reference for the client or load command to determine tool support for specifying these connection parameters via options, configuration property names, and/or environment variables.

Greenplum Database Documentation References

The following Greenplum Database documentation topics provide additional information about using selected client and loader tools:

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.