Upgrade Using gpupgrade

gpupgrade is an in-place upgrade tool for SynxDB clusters. It runs pg_upgrade across all segments to upgrade a cluster to a newer major version, without requiring a full data export and reimport.

Before you begin

  • Obtain the gpupgrade binary from Synx Data Labs technical support and install it on all cluster hosts. Verify the installation by running gpupgrade --version.

  • Install the target version of SynxDB on all cluster hosts.

  • Ensure the current user can connect to all cluster hosts via SSH without a password prompt.

  • Ensure sufficient disk space is available:

    • Copy mode: approximately 60% free disk space required.

    • Link mode: approximately 20% free disk space required.

Supported versions

Contact Synx Data Labs technical support to confirm the supported upgrade version combinations for your environment.

Configure gpupgrade

Create a configuration file named gpupgrade_config with the following parameters:

# Port of the source cluster coordinator
source_master_port =

# Installation directory of the source cluster binaries
source_gphome =

# Installation directory of the target cluster binaries
target_gphome =

Perform the upgrade

The upgrade runs in three sequential stages.

  1. Initialize - Run pre-upgrade checks and create the target cluster.

    gpupgrade initialize --file gpupgrade_config --verbose

    Enter y when prompted. This stage verifies version compatibility, checks disk space, and prepares the target cluster. The source cluster remains available during this stage.

  2. Execute — Perform the actual upgrade.

    gpupgrade execute --verbose

    This stage stops the source cluster and runs pg_upgrade on the coordinator and all segment nodes. Downtime begins at this stage.

  3. Finalize — Complete the upgrade.

    gpupgrade finalize --verbose

    This stage sets up mirror nodes, updates gp_segment_configuration, and removes intermediate files.

    Caution

    After finalization, the upgrade cannot be reverted.

Revert the upgrade

If a problem occurs, you can roll back the upgrade after initialize or execute by running:

gpupgrade revert

Caution

Reverting is not supported after finalize.

Other operations

To restart the gpupgrade hub and agent services:

gpupgrade restart-services

Known limitations

  • PAX tables and directory tables are not supported in the current release of gpupgrade.

  • Some SQL statements that were valid in the source version might not execute in the target version. Review your application workloads before performing an upgrade.