gpupgrade Initialize Phase
During this phase you run the
gpupgrade initialize command. This phase prepares the source cluster for the upgrade and initializes the target cluster. Before proceeding, ensure you have reviewed and completed the pre-upgrade phase tasks.
Perform the initialize phase during a scheduled downtime. Users should receive sufficient notice that the Greenplum Database cluster will be off-line for an extended period. Send a maintenance notice a week or more before you plan to start the execute phase, and then a reminder notice before you begin.
The following table summarises the cluster state before and after
|Before Initialize||After Initialize|
|Master||UP||Non Existent||UP||Initialized but DOWN|
|Standby||UP||Non Existent||UP||Non Existent|
|Primaries||UP||Non Existent||UP||Initialized but DOWN|
|Mirrors||UP||Non Existent||UP||Non Existent|
**IMPORTANT** The minimum supported 5.x Greenplum Database major version is 5.28. Upgrade the source cluster to 5.28 or the latest 5.x version.
gpupgrade initializehas been run in the past by checking if the
$HOME/.gpupgradedirectory already exists on all Greenplum hosts. If it exists, clean up the environment by running
gpupgrade reverton the master host; the command will remove all previously created directories from all source Greenplum hosts.
Ensure that the source Greenplum cluster is in a healthy state, with standby host and mirrors in their preferred roles. If they are not,
gpupgrade initializewill fail during the consistency checks. For further details, see gpstate. Verify the cluster state:
$ gpstate -e
For incremental recovery, run:
$ gprecoverseg -a
For full recovery:
$ gprecoverseg -F
$ gprecoverseg -r
Review and generate the
gpupgrademigration scripts. The
gpupgradeutility package includes SQL migration scripts to help resolve potential migration issues from Greenplum 5.x to 6.x.
gpupgrade initialize maintenance window, run the
gpupgrade-migration-sql-executor.bash pre-initialize script before proceeding with the
gpupgrade initialize command. For more details on the migration scripts, see gpupgrade Migration Scripts.
Edit the gpupgrade configuration file
gpupgrade initialize command requires a configuration file as an input. Review an example
gpupgrade_config file in the directory where you extracted the downloaded
Copy the example file to the
/home/gpadmin/ location and make edits according to your environment:
$ cp /usr/local/bin/greenplum/gpupgrade/gpupgrade_config /home/gpadmin/
The following table summarizes the file parameters.
source_master_port are blank and must be filled with your environment’s values. The remaining parameters are commented-out and have default values. Change these values as necessary for your upgrade scenario.
|source_gphome||Path to the
|target_gphome||Path to the
|disk_free_ratio||Ratio of free space needed to run
|use_hba_hostnames||Whether to use host names or IP addresses in
|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
|hub_port||Master node port, that gpupgrade uses; set to
|agent_port||Segment nodes port, that the agent process uses; set to
See the gpupgrade_config file reference page for further details.
WARNING: If using
link mode, and the source Greenplum cluster does not have a standby host and mirrors,
gpupgrade generates a warning:
The source cluster does not have standby and/or mirror segments.
After "gpupgrade execute" has been run, there will be no way to
return the cluster to its original state using "gpupgrade revert".
gpupgrade initialize --file | -f PATH/TO/gpupgade_config [--verbose | -v] [--automatic | -a]
--file | -fspecifies the configuration file location
--verbose | -vis the flag for verbose output
--automatic | -asuppress summary and confirmation dialog
$ gpupgrade initialize --file /home/gpdamin/gpupgrade/gpupgrade_configuration_file --verbose
The utility displays a summary message and waits for user confirmation before proceeding:
You are about to initialize a major-version upgrade of Greenplum. This should be done only during a downtime window. ... Before proceeding, ensure the following have occurred: - Take a backup of the source Greenplum cluster - [Generate] and [execute] the data migration "start" scripts - Run gpcheckcat to ensure the source catalog has no inconsistencies - Run gpstate -e to ensure the source cluster's segments are up and in preferred roles To skip this summary, use the --automatic | -a flag. Continue with gpupgrade initialize? Yy|Nn:
The utility proceeds through various background steps, and displays its progress on the screen:
Initialize in progress. Starting gpupgrade hub process... [COMPLETE] Saving source cluster configuration... [COMPLETE] Starting gpupgrade agent processes... [COMPLETE] Checking disk space... [COMPLETE] Generating target cluster configuration... [COMPLETE] Creating target cluster... [COMPLETE] Stopping target cluster... [COMPLETE] Backing up target master... [COMPLETE] Running pg_upgrade checks... [COMPLETE] Initialize completed successfully. NEXT ACTIONS ------------ To proceed with the upgrade, run "gpupgrade execute" followed by "gpupgrade finalize". To return the cluster to its original state, run "gpupgrade revert".
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.
These steps are further described below:
- Creating directories: Creates
gpupgradestate directories, used only by the
gpupgradeutility. They reside under
$HOME/.gpupgrade/. The log files for the individual
gpupgradecommands are created in the
$HOME/gpAdminLogs/gpupgradedirectory, for example
- Generating upgrade configuration: Collects the source cluster configuration details and generates
gpupgradestate files to hold the source configuration.
- Starting gpupgrade hub process: Starts up the
gpupgradehub process on the master node.
- Retrieving source cluster configuration: Populates the
gpupgradestate files with the source cluster details.
- Starting gpupgrade agent processes: Starts up agents on the standby master and segment hosts.
- Checking disk space: Checks for available disk space. The default requirement is 60% free disk space. If
‑‑linkis specified, the requirement is 20%. Can be altered by providing a different ratio with
- Generating target cluster configuration: Populates the
gpupgradestate files with the target cluster details.
- Backing up target master: Creates a backup copy of target master, to be used during
executeif any issues occur.
- Creating target cluster: Initializes the target master and segment hosts, in order to run
pg_upgradeon the postgres instances. See Creating Target Cluster Directories for a description of the target cluster data directories.
- Stopping target cluster: Shuts down the target cluster.
pg_upgradechecks: Runs a thorough list of Greenplum Database checks, see Initialize Phase pg_upgrade Checks.
gpupgrade initialize command will create the
$HOME/.gpupgrade directory on each host.
To resolve any
[FAILED] steps, review the screen error comments and recommendations, the server log files in the
$HOME/gpAdminLogs directory, including the
gpupgrade initialize log file in the
gpAdminLogs/gpupgrade/ directory, and discuss with the VMware Greenplum team that’s supporting you during the upgrade.
gpupgrade initialize command creates the target Greenplum cluster, it creates data directories for the target master segment instance and primary segment instances on the master and segment hosts, alongside the source cluster data directories. This applies both to
The target cluster data directory names have this format:
<segment-prefix>is the segment prefix string specified when the source Greenplum Database system was initialized. This is typically
<hash-code>is a 10-character string generated by
gpupgrade. The hash code is the same for all segment data directories belonging to the new target Greenplum cluster. In addition to distinguishing target directories from the source data directories, the unique hash code tags all data directories belonging to the current
<content-id>is the database content id for the segment. The master segment instance content id is always −1. The primary segment content ids are numbered consecutively from 0 to the number of primary segments.
For example, if the
$MASTER_DATA_DIRECTORY environment variable value is
/data/master/gpseg-1/, the data directory for the target master is
AAAAAAAAAA is the hash code
gpupgrade generated for this target cluster. Primary segment data directories for the target cluster are located on the same host and at the same path as their source cluster counterparts. If the first primary segment for the source cluster is on host
sdw1 in the directory
/data/primary/gpseg0, the target cluster segment directory is on the same host at
gpugprade finalize command has completed, source cluster data directory names are renamed as:
and the target cluster data directory names are renamed to the original source directory names:
gpupgrade hub process runs on the Greenplum Database master host and logs messages to the
gpAdminLogs/gpupgrade/initialize.log file, in the
gpadmin user’s home directory.
gpadminand that all files in the
.gpupgradedirectories are owned by gpadmin and are writable by gpadmin.
gpupgrade initializechecks will fail until you reinstall the missing extensions on the target Greenplum Database.