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 is referred to as the target cluster.

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

Greenplum Upgrade process, phases, and downtime window diagram. It depicts a box for each phase, five boxes in total. There are arrows pointing from the first leftmost box, to the last rightmost box. Arrows depict the downtime window which starts at the second box, labelled initialize, upto the fourth box, labelled finalize.

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. For supported versions see Release Notes.
  • 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.


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 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 the pre-initialize migration script that was generated by the gpupgrade-migration-sql-generator.bash script.
  • Run gpupgrade initialize.
  • Perform any tasks relating to existing source cluster extensions.
  • 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