Performs an in-place upgrade of a Greenplum Database system to a new major version.
gpupgrade [initialize | execute | finalize | revert] <flags>
The gpupgrade process is managed with the subcommands initialize, execute, and finalize. initialize is used twice, in the pre-upgrade phase and during the initialize phase.
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.
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 dialogSee the gpupgrade Configuration File reference page for information about the configuration file parameters.
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:
gpupgrade hub process on the master host.gpupgrade agents on the master and segment hosts, one agent process on each host.disk_free_ratio parameter to 0.0 to disable the disk space check.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.
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:
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.
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.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.
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:
postgresql.conf file.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.
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:
gpupgrade state directories on the segments.gpupgrade hub and agents.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
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.
gpupgrade Pre-Upgrade Phase, gpupgrade Initialize Phase, gpupgrade Execute Phase, gpupgrade Finalize Phase, PostgresSQL 9.4 pg_upgrade
