The gpupgrade command supports initialize, execute, finalize, and revert. The overall upgrade process includes five phases: pre-upgrade, initialize, execute, finalize, and post-upgrade. This topic summarizes each phase and directs you to the detailed pages for further explanations.

The pre-upgrade and post-upgrade phases are user tasks that need to be completed before and after you use the gpupgrade utility.

To quickly try the gpupgrade process, see the Quick Start Guide.

NOTE: In this documentation, the existing Greenplum Database cluster is referred to as the source cluster, and the new Greenplum Database cluster as the target cluster.

The following diagram shows the upgrade flow for the entire process.

Downtime Window

WARNING The upgrade window requires planned downtime. The source cluster will be stopped during the upgrade process.


Follow the pre-upgrade preparatory steps a few weeks before the upgrade date. For detailed steps in this phase, see gpupgrade pre-upgrade.

  • Review the gpupgrade documentation.
  • Review the changes from Greenplum 5.x to 6.x documentation.
  • Upgrade the source Greenplum Database to the minimum supported (if required), and download the latest target Greenplum Database software.
  • Download and install the latest gpupgrade utility software.
  • Confirm you have gpadmin access to all Greenplum Database hosts.
  • Review the two gpupgrade modes, copy or link.
  • Review the pg_upgrade checks which identify any issues between source and target clusters.
  • Run the gpupgrade-migration-sql-generator.bash script before you begin the upgrade. The script checks for catalog inconsistencies between source and target cluster, and generates SQL scripts to fix certain issues.
  • Run gpupgrade initialize as a pre-upgrade step. The initialize command will check and log any possible upgrade issues that can be fixed before the planned upgrade downtime.


In this phase, you continue preparing the source cluster, and initialize the target cluster. For information about this phase, see gpupgrade initialize. During this phase, ensure that you are in a scheduled maintenance window, that can accommodate cluster downtime.

  • Run the pre-initialize migration script that was generated in the pre-upgrade phase.
  • Run gpupgrade initialize.
  • Monitor progress.
  • If initialize completes successfully, continue with gpupgrade execute.
  • If you want to revert out of the process, run gpupgrade revert which removes the artifacts the initialize command created.


This step stops the source Greenplum cluster. Ensure that you are within your downtime window. For information about this phase, see gpupgrade execute.

  • Run gpupgrade execute.
  • Review gpupgrade execute logs for any issues.
  • Check that the target cluster is live.
  • Run your pre-prepared queries to confirm they are running as expected.
  • You can run gpupgrade revert to abandon the upgrade if you choose not to finalize. Once you begin the finalize phase, gpupgrade cannot restore the original Greenplum Cluster.


For information about this phase, see gpupgrade finalize.

  • Run gpupgrade finalize to upgrade standby master and mirror segments.
  • Test the usability of any new Greenplum Database features you are planning to use.


For information about this phase, see gpupgrade post-upgrade.

  • Review post-upgrade tasks to redirect gpadmin to the target Greenplum cluster.
  • Edit configuration files and finalize cleanup tasks.
check-circle-line exclamation-circle-line close-line
Scroll to top icon