Upgrading Greenplum Database
Upgrading Greenplum Database
The upgrade path supported for this release is Greenplum Database 6.x to a newer Greenplum Database 6.x release. Direct upgrade from Greenplum Database 4 or 5 to Greenplum 6 is not supported.
Before starting the upgrade process, Pivotal recommends performing the following checks.
- Verify the health of the Greenplum Database host hardware, and verify that the hosts
meet the requirements for running Greenplum Database. The Greenplum Database
gpcheckperf utility can assist you in confirming the host requirements.
Note: If you need to run the gpcheckcat utility, Pivotal recommends running it a few weeks before the upgrade and that you run gpcheckcat during a maintenance period. If necessary, you can resolve any issues found by the utility before the scheduled upgrade.
The utility is in $GPHOME/bin. Pivotal recommends that Greenplum Database be in restricted mode when you run the gpcheckcat utility. See the Greenplum Database Utility Guide for information about the gpcheckcat utility.
If gpcheckcat reports catalog inconsistencies, you can run gpcheckcat with the -g option to generate SQL scripts to fix the inconsistencies.
After you run the SQL scripts, run gpcheckcat again. You might need to repeat the process of running gpcheckcat and creating SQL scripts to ensure that there are no inconsistencies. Pivotal recommends that the SQL scripts generated by gpcheckcat be run on a quiescent system. The utility might report false alerts if there is activity on the system.Important: If the gpcheckcat utility reports errors, but does not generate a SQL script to fix the errors, contact Pivotal Support. Information for contacting Pivotal Support is at https://support.pivotal.io.
- During the migration process from Greenplum Database 5, a backup is made of some files and directories in $MASTER_DATA_DIRECTORY. Pivotal recommends that files and directories that are not used by Greenplum Database be backed up, if necessary, and removed from the $MASTER_DATA_DIRECTORY before migration. For information about the Greenplum Database migration utilities, see the Release Notes.
If you are utilizing Data Domain Boost, you have to re-enter your DD Boost credentials after upgrading to Greenplum Database as follows:
gpcrondump --ddboost-host ddboost_hostname --ddboost-user ddboost_user --ddboost-backupdir backup_directory
If you have configured the Greenplum Platform Extension Framework (PXF) in your previous Greenplum Database installation, you must stop the PXF service, and you might need to back up PXF configuration files before upgrading to a new version of Greenplum Database. Refer to PXF Pre-Upgrade Actions for instructions.
If you do not plan to use PXF, or you have not yet configured PXF, no action is necessary.
Upgrading from 6.x to a Newer 6.x Release
An upgrade from Greenplum Database 6.x to a newer 6.x release involves stopping Greenplum Database, updating the Greenplum Database software binaries, upgrading, and restarting Greenplum Database. If you are using Greenplum Database extension packages there are additional requirements. See Prerequisites in the previous section.
- Log in to your Greenplum Database master host as the Greenplum
$ su - gpadmin
- Perform a smart shutdown of your Greenplum Database 6.x system
(there can be no active connections to the database). This example uses the
-a option to disable confirmation
$ gpstop -a
- Copy the new Greenplum Database software installation package to the gpadmin user's home directory on each master, standby, and segment host.
- As root, install the new Greenplum Database
software release on each
$ sudo yum install greenplum-db-<version>_<platform>.rpm
- Update the permissions for the new installation. For example, run this command as
root to change the user and group of the installed files to
$ sudo chown -R gpadmin:gpadmin /usr/local/greenplum*
- If needed, update the greenplum_path.sh file on the master and standby
master hosts for use with your specific installation. These are some examples.
Note: When comparing the previous and new greenplum_path.sh files, be aware that installing some Greenplum Database extensions also updates the greenplum_path.sh file. The greenplum_path.sh from the previous release might contain updates that were the result of those extensions.
- If Greenplum Database uses LDAP authentication, edit the
greenplum_path.sh file to add the
- If Greenplum Database uses PL/Java, you might need to set or update the environment variables JAVA_HOME and LD_LIBRARY_PATH in greenplum_path.sh.
- If Greenplum Database uses LDAP authentication, edit the greenplum_path.sh file to add the line:
- Edit the environment of the Greenplum Database superuser
(gpadmin) and make sure you are sourcing the greenplum_path.sh file for the new
installation. For example change the following line in the .bashrc or your chosen profile
Or if you are sourcing a symbolic link (/usr/local/greenplum-db) in your profile files, update the link to point to the newly installed version. For example:
$ rm /usr/local/greenplum-db $ ln -s /usr/local/greenplum-db-<new_version> /usr/local/greenplum-db
- Source the environment file you just edited. For
$ source ~/.bashrc
- Use the Greenplum Database gppkg utility to install
Greenplum Database extensions. If you were previously using any Greenplum Database
extensions such as pgcrypto, PL/R, PL/Java, PL/Perl, and PostGIS, download the
corresponding packages from Pivotal Network, and install
using this utility. See the Greenplum Database Documentation for
gppkg usage details.
Also copy any additional files that are used by the extensions (such as JAR files, shared object files, and libraries) from the previous version installation directory to the new version installation directory on the master and segment host systems.
- After all segment hosts have been upgraded, log in as the
gpadmin user and restart your Greenplum Database
# su - gpadmin $ gpstart
- If you are using Data Domain Boost, you must re-enter your DD Boost credentials after
gpcrondump --ddboost-host ddboost_hostname --ddboost-user ddboost_user --ddboost-backupdir backup_directoryNote: If you do not reenter your login credentials after an upgrade, your backup will never start because the Greenplum Database cannot connect to the Data Domain system. You will receive an error advising you to check your login credentials.
- If you configured PXF in your previous Greenplum Database installation, you must re-initialize the PXF service after you upgrade Greenplum Database. Refer to Upgrading PXF for instructions.
After upgrading Greenplum Database, ensure features work as expected. For example, you should test that backup and restore perform as expected, and Greenplum Database features such as user-defined functions, and extensions such as MADlib and PostGIS perform as expected.
Troubleshooting a Failed Upgrade
If you experience issues during the migration process and have active entitlements for Greenplum Database that were purchased through Pivotal, contact Pivotal Support. Information for contacting Pivotal Support is at https://support.pivotal.io.
Be prepared to provide the following information:
- A completed Upgrade Procedure.
- Log output from gpcheckcat (located in ~/gpAdminLogs)