gpupgrade Finalize Phase

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

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.

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.
    
    Stopping target cluster...                                         [COMPLETE]
    Updating target master catalog...                                  [COMPLETE]
    Updating data directories...                                       [COMPLETE]
    Updating target master configuration files...                      [COMPLETE]
    Starting target cluster...                                         [COMPLETE]
    Upgrading standby master...                                        [COMPLETE]
    Upgrading mirror segments...                                       [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 is now ready to use, running Greenplum <target-version>.
    PGPORT: <target-port>
    MASTER_DATA_DIRECTORY: <target-master-dir>
    
    The source cluster is not running. You may delete the source cluster to recover space from all hosts.
    All source cluster data directories end in "0jkFHIk0rnA.<contentID>.old".
    MASTER_DATA_DIRECTORY: <target-master-dir>
    
    The gpupgrade logs can be found on the master and segment hosts in
    /home/gpadmin/gpAdminLogs/gpupgrade-<timestamp-ID>
    
    NEXT ACTIONS
    ------------
    Run 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

The gpupgrade finalize hub process runs on the Greenplum Database master host and logs messages to the gpAdminLogs/gpupgrade/finalize.log file in the gpadmin user’s home directory.

Could not create the $HOME/gpAdminLogs/gpupgrade/finalize.log file
Make sure you are logged in as gpadmin and that all files in the .gpupgrade and gpAdminLogs directory are owned by gpadmin and are writable by gpadmin.

Next Steps

When 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.

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