gpupgrade Process

The gpupgrade command supports initialize, execute, finalize, and revert. The overall upgrade process includes five phases: pre-upgrade, initialize, execute, finalize, and post-upgrade. The pre-upgrade and post-upgrade phases are user tasks that need to be completed before and after you use the gpupgrade utility. This topic summarizes each phase and directs you to the detailed pages for further explanations.

The downtime window required for the entire process is shown in the following diagram:

NOTE In this documentation, your existing Greenplum Database 5 cluster is the source and your new Greenplum Database 6 cluster is the target.


Follow these preparatory steps a few weeks before the upgrade date. For detailed information about 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 5 (if required) and download the target Greenplum Database 6 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 Migration Scripts. Generate the scripts before you begin the upgrade. These scripts check for catalog inconsistencies between source and target cluster, and generate SQL scripts to fix the issues.


In this phase, you prepare 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.

  • Review the pg_upgrade checks in advance.
  • Execute the migration scripts that were 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.