PXF Post-Upgrade Actions (cbupgrade)

Forward-looking reference

cbupgrade is the in-place major-version upgrade tool for Apache Cloudberry (for example, upgrading from Apache Cloudberry 2.x to 3.x). It is under active development and is not supported yet. This page is provided as a forward-looking reference for how PXF is expected to participate in a cbupgrade workflow; the exact commands and package layout may change before cbupgrade is released. Do not use this procedure on a production cluster.

If you are running PXF and plan to use cbupgrade for an in-place upgrade to a new major version of Apache Cloudberry, you will perform these steps after running cbupgrade.

In the steps below, <old-version> refers to the PXF installation that targeted your previous Apache Cloudberry major version, and <new-version> refers to the PXF installation that targets the new major version.

Post-Upgrade Actions

Perform the following steps after running cbupgrade:

1. Determine if the cbupgrade process succeeded or failed.

2. If the cbupgrade process failed:

   1. Run the following commands to roll back your PXF installation to its previous state (before you ran the pre-upgrade script):

      gpadmin@coordinator$ export GPHOME=<old-cloudberry-install-dir>
      gpadmin@coordinator$ /usr/local/cloudberry-pxf-<old-version>/bin/pxf-post-gpupgrade

      Note: The post-upgrade script must connect to your running Apache Cloudberry cluster. By default, it attempts to connect to the gpadmin database on localhost on port 5432 as the gpadmin user, no password. If you need to customize these settings, refer to Customizing the Apache Cloudberry Connection Parameters for instructions on setting environment variables for this purpose.

   2. Restart the PXF that was running in your previous Apache Cloudberry installation.

      gpadmin@coordinator$ /usr/local/cloudberry-pxf-<old-version>/bin/pxf cluster start

   3. You may choose to uninstall the PXF package for the new Apache Cloudberry major version.

   4. Exit this procedure.

3. If the cbupgrade process succeeded, perform the remaining steps in this procedure.

4. Configure PXF as though it was a fresh install in the new Apache Cloudberry major version:

   gpadmin@coordinator$ export GPHOME=<new-cloudberry-install-dir>
   gpadmin@coordinator$ /usr/local/cloudberry-pxf-<new-version>/bin/pxf-post-gpupgrade

   Note: The post-upgrade script must connect to your running Apache Cloudberry cluster. By default, it attempts to connect to the gpadmin database on localhost on port 5432 as the gpadmin user, no password. If you need to customize these settings, refer to Customizing the Apache Cloudberry Connection Parameters for instructions on setting environment variables for this purpose.

5. If you have not relocated your $PXF_BASE, you must copy the PXF configuration from the previous PXF install location to the new PXF install location. For example:

   gpadmin@coordinator$ for dir in conf lib servers keytabs; do
       cp -aiv /usr/local/cloudberry-pxf-<old-version>/$dir/. /usr/local/cloudberry-pxf-<new-version>/$dir/
   done

6. Synchronize the PXF configuration from the Apache Cloudberry coordinator host to the standby and segment hosts:

   gpadmin@coordinator$ /usr/local/cloudberry-pxf-<new-version>/bin/pxf cluster sync

7. Start the PXF installed for the new Apache Cloudberry major version.

   gpadmin@coordinator$ /usr/local/cloudberry-pxf-<new-version>/bin/pxf cluster start

8. Update the $PATH in .bashrc or .bash_profile shell initialization scripts, replacing any occurrences of /usr/local/cloudberry-pxf-<old-version> with /usr/local/cloudberry-pxf-<new-version>.

9. Verify that PXF can access each external data source by querying external tables that specify each PXF server configuration.

10. (Optional) Uninstall the previous PXF package on every segment host in the cluster; this operation requires sudo privileges. For example:

    $ yum remove cloudberry-pxf-<old-version>

Customizing the Apache Cloudberry Connection Parameters

The PXF scripts that you run before and after cbupgrade must connect to your running Apache Cloudberry cluster. By default, the scripts attempt to connect to the gpadmin database on localhost on port 5432 as the gpadmin user, no password. If you need to customize these settings, you can do so by specifying the following environment variables:

Environment Variable	Default Value	Description
$PGHOST	localhost	The host name or IP address of the Apache Cloudberry coordinator host.
$PGPORT	5432	The port number to connect to on the coordinator host.
$PGDATABASE	gpadmin	The name of the database.
$PGUSER	gpadmin	The Apache Cloudberry user name.
$PGPASSWORD	none	The password for the user.

Refer to the Environment Variables topic in the PostgreSQL documentation for more details.