When the gpupgrade execute command has completed successfully, it has finished all the upgrade tasks it is able to perform on the master and primary segment. The source Greenplum Database cluster is stopped, the target cluster is running with upgraded master and primary segments, and the source standby master and mirror segments are unchanged. During finalize phase, the upgrade process completes the master standby and mirrors updates.

The following table summarises the cluster state before and after gpupgrade finalize:

Before Finalize After Finalize
Source Target Source Target
Master DOWN UP and populated DOWN UP
Standby DOWN Non Existent DOWN UP
Primaries DOWN UP and populated DOWN UP
Mirrors DOWN Non Existent DOWN UP

Finalize Workflow Summary

The gpupgrade finalize command performs the following steps:

  1. Removes source cluster data directories and tablespaces.
  2. Upgrades the mirror segments.
  3. Upgrades the standby master node.
  4. Stops the target cluster.
  5. Updates the target master catalog.
  6. Updates the data directories.
  7. Updates the target master configuration files.
  8. Starts the target cluster.
  9. Archives the log directories.
  10. Deletes the state directories on the segments.
  11. Stops the hub and agents.
  12. Deletes the master state directory.
  13. Stops the target cluster.

Verifying the Cluster Upgrade

Here are some steps you can follow to verify the target Greenplum Database cluster before you make the decision to finalize the upgrade. As always, be sure to document all changes you make to the system so that you have a record you can refer to later, if needed.

  1. Set up your environment to access the target cluster. See Connecting to the Target Cluster. You may also need to set up the environment in scripts or configuration files that you run while testing the target cluster.

  2. Run gpstate to see the status of the cluster. The master instance and primary segment instances should be up. The standby master and mirror segments are not added to the cluster until you run gpupgrade finalize.

  3. Run gpcheckcat to verify the system catalog.

  4. Merge needed entries from the pg_hba.conf authentication file in the source cluster master directory into the pg_hba.conf file in the target cluster master directory.

  5. The upgrade has installed the default postgresql.conf file and updated the master port. Review the postgresql.conf file in the source master directory for any server configuration parameters you need to apply to the target cluster. See System Configuration Parameter Changes for parameters that have been added, removed, or modified between Greenplum Database 5 and Greenplum Database 6.

  6. Run any test scripts you have available to verify the upgraded database. Make sure to test all of your standard transactions against the target database and to verify the results.

  7. Test user applications against the upgraded databases.

  8. Check for any open connections to the target Greenplum database and close any applications that might be trying to access the cluster. gpupgrade finalize will check for open connections and output an error if it finds any.

Running the gpupgrade finalize Command

  1. Run the gpupgrade finalize command.

    $ gpupgrade finalize

    The utility displays a summary message and waits for user confirmation before proceeding:

    You are about to finalize a major-version upgrade of Greenplum.
    This should be done only during a downtime window.
    WARNING: Do not perform operations on the source and target clusters until gpupgrade is
    finalized or reverted.
    Continue with gpupgrade finalize?  Yy|Nn:

    gpupgrade displays progress as it executes the upgrade tasks:

    Finalize in progress.
    Upgrading standby master...                [COMPLETE]
    Upgrading mirror segments...               [IN PROGRESS]

    The status of each step can be COMPLETE, FAILED, SKIPPED, or IN PROGRESS. SKIPPED indicates that the command has been run before and the step has already been executed.

    When the finalize process has completed, gpupgrade reports the master listen port and master data directory for the source and target cluster:

    Finalize in progress.
    Upgrading mirror segments...                                       [COMPLETE]   
    Upgrading standby master...                                        [COMPLETE]   
    Waiting for cluster to be ready...                                 [COMPLETE]   
    Stopping target cluster...                                         [COMPLETE]   
    Updating target master catalog...                                  [COMPLETE]   
    Updating data directories...                                       [COMPLETE]   
    Updating target master configuration files...                      [COMPLETE]   
    Starting target cluster...                                         [COMPLETE]   
    Waiting for cluster to be ready...                                 [COMPLETE]   
    Stopping target cluster...                                         [COMPLETE]   
    Archiving log directories...                                       [COMPLETE]   
    Deleting state directories on the segments...                      [COMPLETE]   
    Stopping hub and agents...                                         [COMPLETE]   
    Deleting master state directory...                                 [COMPLETE]  
    Finalize completed successfully.
    The target cluster has been upgraded to Greenplum 6.21.0
    The source cluster is not running. If copy mode was used you may start the source cluster, but not at the same time as the target cluster. To do so configure different ports to avoid conflicts. 
    You may delete the source cluster to recover space from all hosts. 
    All source cluster data directories end in "68wVro6SnHs.<contentID>.old".
    The gpupgrade logs can be found on the master and segment hosts in
    To use the upgraded cluster:
    1. Update any scripts to source /usr/local/greenplum-db-target/greenplum_path.sh
    2. If applicable, update the greenplum-db symlink to point to the target 
       install location: /usr/local/greenplum-db -> /usr/local/greenplum-db-target
    3. In a new shell start the upgraded cluster.
       source /usr/local/greenplum-db-target/greenplum_path.sh
       gpstart -a
       Execute the “post-finalize” data migration scripts, and recreate any 
       additional tables, indexes, and roles that were dropped or altered 
       to resolve migration issues.
  2. Reset your environment to access the cluster using the same master data directory and master port number you used for the source cluster.

  3. Source the greenplum_path.sh file in the target Greenplum Database installation directory.

  4. Review any remaining actions from the pg_upgrade checks during the initialize phase. For example, Tsvector user columns.

Running gpstate now should show that the master, standby master, primary segments, and mirror segments are all running.

Troubleshooting the Finalize Phase

Host Key Verification Problem

In link mode, when upgrading the mirror segments, the following error may occur:

Error: Finalize: rpc error: code = Unknown desc = substep "UPGRADE_MIRRORS": 4 errors occurred:
        * rpc error: code = Unknown desc = 2 errors occurred:
        * Host key verification failed.
rsync: connection unexpectedly closed (0 bytes received so far) [sender]
rsync error: unexplained error (code 255) at io.c(226) [sender=3.1.2]

        * Host key verification failed.
rsync: connection unexpectedly closed (0 bytes received so far) [sender]
rsync error: unexplained error (code 255) at io.c(226) [sender=3.1.2]

To resolve this, run the following commands in a separate shell:

$ source /usr/local/greenplum-db-6*/greenplum_path.sh
$ gpssh-exkeys -f all_hosts
$ gpstart -a -d $(gpupgrade config show --target-datadir)

Next Steps

Once the gpupgrade finalize command has completed successfully and the new Greenplum Database cluster is up and running, run the optional gpupgrade-migration-sql-executor.bash post-finalize script. For more details on the migration scripts, see gpupgrade Migration Scripts.

gpupgrade does not restore source cluster statistics to the target cluster. Run analyze after successful completion of gpupgrade finalize, to restore statistics. Be sure to account for the additional downtime required to recreate statistics on the target cluster.

You can now proceed with the gpupgrade Post-upgrade Phase.

check-circle-line exclamation-circle-line close-line
Scroll to top icon