Initializing PXF

The PXF server is a Java application. You must explicitly initialize the PXF Java service instance. This one-time initialization copies PXF extension files to the Greenplum Database installation, creates the PXF service web application, and generates PXF configuration files and templates.

PXF provides two management commands that you can use for initialization:

  • pxf cluster init - initialize all PXF service instances in the Greenplum Database cluster
  • pxf init - initialize the PXF service instance on the current Greenplum Database host

PXF also provides similar reset commands that you can use to reset your PXF configuration.

The procedures in this topic assume that you have added the $PXF_HOME/bin directory to your $PATH.

Configuration Properties

PXF supports both internal and user-customizable configuration properties.

PXF internal configuration files are located in your PXF installation in the $PXF_HOME/conf directory.

You identify the PXF user configuration directory at PXF initialization time via an environment variable named $PXF_CONF. If you do not set $PXF_CONF prior to initializing PXF, PXF may prompt you to accept or decline the default user configuration directory, $HOME/pxf, during the initialization process.

Note: Choose a $PXF_CONF directory location that you can back up, and ensure that it resides outside of your Greenplum Database installation directory.

Refer to PXF User Configuration Directories for a list of $PXF_CONF subdirectories and their contents.

Initialization Overview

The PXF server runs on Java 8 or 11. You identify the PXF $JAVA_HOME and $PXF_CONF settings at PXF initialization time.

Initializing PXF:

  • Copies PXF extension files from $PXF_HOME/gpextable to the Greenplum Database install directory when the $GPHOME environment variable is set. Specify the --skip-register option to the init command to instruct PXF to skip this initialization step.
  • Creates the PXF Java web application.
  • Generates PXF internal configuration files, setting default properties specific to your configuration.

Initializing PXF also creates the $PXF_CONF user configuration directory if it does not already exist, and then populates conf and templates subdirectories with the following:

  • conf/ - user-customizable files for PXF runtime and logging configuration settings
  • templates/ - template configuration files

PXF remembers the JAVA_HOME setting that you specified during initialization by updating the property of the same name in the $PXF_CONF/conf/pxf-env.sh user configuration file. PXF sources this environment file on startup, allowing it to run with a Java installation that is different than the system default Java.

If the $PXF_CONF directory that you specify during initialization already exists, PXF updates only the templates subdirectory and the $PXF_CONF/conf/pxf-env.sh environment configuration file.

Prerequisites

Before initializing PXF in your Greenplum Database cluster, ensure that:

  • Your Greenplum Database cluster is up and running.
  • You have identified the PXF user configuration directory filesystem location, $PXF_CONF, and that the gpadmin user has the necessary permissions to create, or write to, this directory.
  • You can identify the Java 8 or 11 $JAVA_HOME setting for PXF.

Procedure

Perform the following procedure to initialize PXF on each segment host in your Greenplum Database cluster.

  1. Log in to the Greenplum Database master node:

    $ ssh gpadmin@<gpmaster>

  2. Export the PXF JAVA_HOME setting in your shell. For example:

    gpadmin@gpmaster$ export JAVA_HOME=/usr/lib/jvm/jre

  3. Run the pxf cluster init command to initialize the PXF service on the master, standby master, and on each segment host. For example, the following command specifies /usr/local/greenplum-pxf as the PXF user configuration directory for initialization:

    gpadmin@gpmaster$ PXF_CONF=/usr/local/greenplum-pxf pxf cluster init

    Note: The PXF service runs only on the segment hosts. However,pxf cluster init also sets up the PXF user configuration directories on the Greenplum Database master and standby master hosts.

Resetting PXF

Should you need to, you can reset PXF to its uninitialized state. You might choose to reset PXF if you specified an incorrect PXF_CONF directory, or if you want to start the initialization procedure from scratch.

When you reset PXF, PXF prompts you to confirm the operation. If you confirm, PXF removes the following runtime files and directories:

  • $PXF_HOME/conf/pxf-private.classpath
  • $PXF_HOME/pxf-service
  • $PXF_HOME/run

PXF does not remove the $PXF_CONF directory during a reset operation, nor does PXF remove any PXF extension files that may have been copied to your Greenplum Database installation.

You must stop the PXF service instance on a segment host before you can reset PXF on the host.

Procedure

Perform the following procedure to reset PXF on each segment host in your Greenplum Database cluster.

  1. Log in to the Greenplum Database master node:

    $ ssh gpadmin@<gpmaster>

  2. Stop the PXF service instances on each segment host:

    gpadmin@gpmaster$ pxf cluster stop

  3. Reset the PXF service instances on all Greenplum hosts:

    gpadmin@gpmaster$ pxf cluster reset

Note: After you reset PXF, you must initialize and start PXF to use the service again.