gpupgrade

Performs an in-place upgrade of a Greenplum Database system to a new major version.

Synopsis

gpupgrade [initialize | execute | finalize | revert] <flags>

Subcommands

The gpupgrade process is managed with the subcommands initialize, execute, and finalize, executed in sequence.

The revert subcommand can be executed after the initialize subcommand or after the execute subcommand, to return the cluster to its original state. The revert subcommand cannot be run after the finalize subcommand has started.

Initialize

gpupgrade initialize runs pre-upgrade checks, prepares the source cluster for upgrade, and initializes the target cluster.

gpupgrade initialize --file | -f <path/to/gpupgade_config> [--verbose | -v] [--help | -h] [-a | -automatic]

Optional Flags:

  • -v or --verbose outputs more detailed log messages for the initialize subcommand.
  • -h or --help displays help output for the initialize subcommand.
  • -a or --automatic suppress summary and confirmation dialog

The following table summarizes the configuration file parameters. See the gpupgrade_config file reference page for further details.

Parameter  Description
source_gphome Path to the $GPHOME directory of the source Greenplum installation.
target_gphome Path to the $GPHOME directory of the target Greenplum installation.
mode copy or link, copy is used by default. Uncomment to use link mode.
disk_free_ratio Ratio of free space needed to run gpupgrade, based on the mode. Ranges from 0.0 to 1.0. Default is 0.6 (60%) free space for copy mode; 0.2 (20%) for link mode.
use_hba_hostnames Whether to use host names or IP addresses in gpinitsystem and other utilities. Should match the HBA_HOSTNAMES configuration parameter configured in the gpinitsystem_config file, used during the Greenplum Database initialization. By default set to false. For more information about HBA_HOSTNAMES, see gpinitsystem.
source_master_port The master port of the source Greenplum cluster, provide your source cluster value.
temp_port_range Set of ports to use when initializing the target cluster. Default is 50432-65535 and allocation starts from 50432 onwards.
hub_port Master node port, that gpupgrade uses; set to 7527 by default.
agent_port Segment nodes port, that the agent process uses; set to 6416 by default.

Notes

The parent directories of the master and segment data directories must be writeable by the gpadmin user.

The gpupgrade initialize command performs the following steps:

  • Creates the upgrade state directory $HOME/.gpupgrade.
  • Generates the upgrade configuration.
  • Starts the gpupgrade hub process on the master host.
  • Checks the source cluster configuration.
  • Retrieves the source cluster configuration.
  • Starts the gpupgrade agents on the master and segment hosts, one agent process on each host.
  • Checks that sufficient disk space is available on every host to complete the upgrade. Set the disk_free_ratio parameter to 0.0 to disable the disk space check.
  • Generates the target cluster configuration.
  • Creates the target cluster.
  • Stops the target cluster.
  • Backs up the target master directory.
  • Runs pg_upgrade --check to check for known migration issues between the source and target Greenplum Database versions. No data is changed by this step. For details, see the pg_upgrade checks page.

gpupgrade initialize logs messages in the $HOME/gpAdminLogs/gpupgrade/initialize_YYYYMMDD.log file.

When gpupgrade initialize is complete, the source cluster remains up. The target cluster is created and initialized, but is not yet running.

You can continue to access the source cluster with the same MASTER_DATA_DIRECTORY and master port number.

You can run gpupgrade initialize repeatedly and modify the source Greenplum cluster until the command runs cleanly. When you are ready to apply the upgrade, run the gpupgrade execute command.

See gpupgrade Pre-Upgrade Phase for information about preparing to run the gpupgrade initialize command. See gpupgrade Initialize Phase for more information about running gpupgrade initialize.

Execute

After you have successfully run gpupgrade initialize, run gpupgrade execute to upgrade the master instance and primary segments.

gpupgrade execute <flags>

Optional Flags:

  • -h or --help displays help output for the execute subcommand.
  • -v or --verbose outputs more detailed log messages for the initialize subcommand.

The gpupgrade execute command performs the following steps:

  • Stops the source Greenplum cluster.
  • Upgrades the master instance on the target cluster.
  • Copies the upgraded master catalog to all primary segments of the target cluster.
  • Upgrades the primary segments.
  • Starts the target Greenplum Database cluster.

When gpupgrade execute is finished the target Greenplum Database cluster is running.

The gpupgrade command displays the MASTER_DATA_DIRECTORY and master port number to access the target cluster.

  • The MASTER_DATA_DIRECTORY for the target cluster is in the same location as the MASTER_DATA_DIRECTORY for the source cluster. The target MASTER_DATA_DIRECTORY directory name is in the format <segment-prefix>.<hash-code>.-1. The <hash-code> is a unique hash string gpupgrade uses to tag the master and primary segment data directories it creates for the target Greenplum cluster. See Target Data Directories for more about the target cluster directory naming scheme.
  • The master port (PGPORT) for the target cluster is the first port in the range you set with the temp_port_range parameter in the gpupgrade initialize configuration file, or 50432 by default.

Use commands like the following to connect to the target cluster, substituting the directory name and port number shown in the output of the gpupgrade initialize command:

$ export MASTER_DATA_DIRECTORY=/data/master/gpseg.eq1g0kFIyws.-1
$ export PGPORT=50432
$ psql template1

The gpupgrade execute command writes log messages in the $HOME/gpAdminLogs/gpupgrade/execute_YYYYMMDD.log file.

See gpupgrade Execute Phase for more information about running the gpupgrade execute command.

Finalize

gpupgrade finalize upgrades the Greenplum Database mirror segments and the standby master to the target Greenplum Database version. Once you execute gpupgrade finalize the cluster cannot be reverted.

gpupgrade finalize <flags>

Optional Flags:

  • -h or --help displays help output for the finalize subcommand.
  • -v or --verbose outputs more detailed log messages for the finalize subcommand.

The gpupgrade finalize command performs the following steps:

  • Upgrades the standby master.
  • Upgrades the mirror segments.
  • Stops the target cluster.
  • Starts the target cluster in master-only mode.
  • Updates the target master port.
  • Stops the target master.
  • Updates the master port number in the master postgresql.conf file.
  • Starts the target cluster.

The gpupgrade finalize command writes log messages in the $HOME/gpAdminLogs/gpupgrade/finalize_YYYYMMDD.log file.

The gpupgrade finalize command renames the original source data directories to:

<segment-prefix>.<hash-code>.<content-id>.old

Where:

  • <segment-prefix> is the segment prefix string specified when the source Greenplum Database system was initialized. This is typically gpseg.
  • <hash-code> is the 10-character string generated by gpupgrade for this gpupgrade instance.
  • <content-id> is the database content id for the segment. The master segment instance content id is always −1.
  • .old is appended to indicate that the directory is no longer the currently active data directory.

The target directory names are renamed to the original names of their corresponding source directories.

Revert

gpupgrade revert returns the Greenplum Database cluster to its state when the most recent gpupgrade initialize command was run. It can be run at any time before the gpupgrade finalize command is run.

gpupgrade revert <flags>

Optional Flags:

  • -h or --help displays help output for the revert subcommand.
  • -v or --verbose outputs more detailed log messages for the revert subcommand.

The gpupgrade revert command performs the following steps, as needed to restore the cluster to its original state:

  • Deletes the target cluster primary segment data directories.
  • Deletes the target cluster master data directory.
  • Deletes gpupgrade state directories on the segments.
  • Stops the gpupgrade hub and agents.
  • Deletes the target cluster master state directory.
  • Archives log files from the reverted gpupgrade instance to the gpAdminLogs/gpupgrade directory.

The gpupgrade revert command writes log messages to the $HOME/gpAdminLogs/gpupgrade/revert_YYYYMMDD.log file. The $HOME/gpAdminLogs/gpupgrade directory is archived by appending a timestamp to the directory.

When the revert has finished, you must manually kill the gpupgrade processes on the master and segment hosts:

$ pkill gpupgrade
$ gpssh -f <hostname_list> pkill gpupgrade

After a successful revert, the source Greenplum Database cluster is up, but the mirror segments are down. Run gprecoverseg to bring up the mirror segments:

$ gprecoverseg

Run gpinitstandby to bring up the standby master:

$ gpinitstandby -n

Description

The gpupgrade utility upgrades a Greenplum Database cluster to a new Greenplum Database major version, for example from Greenplum Database 5.x to Greenplum Database 6.x. You cannot use gpupgrade to upgrade Greenplum Database versions within the same major version.

The existing Greeplum Database cluster you are upgrading from is called the “source” cluster. The new version of Greenplum Database you are upgrading to is called the “target” cluster.

The gpupgrade subcommands must be executed as the gpadmin user on the master host of the source Greenplum Database cluster.

Both the source and target versions of the Greenplum Database software must be installed on all hosts in the Greenplum system. Do not initialize the target Greenplum Database cluster; the target cluster is configured and intialized as part of the gpupgrade process.

The initialize, execute, and finalize subcommands each begin a step in the upgrade process. The initialize step must complete before the execute step can start, and the execute step must complete before the finalize step starts.

After running the initialize or execute subcommand, you can choose to revert the upgrade process, restoring the cluster to its original state. The gpupgrade revert command undoes any steps that were completed during the initialize or execute phases. It archives the gpupgrade log files by renaming the gpAdminLogs/gpupgrade directory with a timestamp.

See Also

gpupgrade Pre-Upgrade Phase, gpupgrade Initialize Phase, gpupgrade Execute Phase, gpupgrade Finalize Phase, PostgresSQL 9.4 pg_upgrade