Upgrading from an Earlier LightDB-A 6 Release

Prerequisites
Upgrading from 6.x to a Newer 6.x Release
Troubleshooting a Failed Upgrade

The upgrade path supported for this release is LightDB-A Database 6.x to a newer LightDB-A Database 6.x release.

Important Set the LightDB-A Database timezone to a value that is compatible with your host systems. Setting the LightDB-A Database timezone prevents LightDB-A Database from selecting a timezone each time the cluster is restarted and sets the timezone for the LightDB-A Database coordinator and segment instances. After you upgrade to this release and if you have not set a LightDB-A Database timezone value, verify that the selected LightDB-A Database timezone is acceptable for your deployment. See Configuring Timezone and Localization Settings for more information.

Prerequisites

Before starting the upgrade process, perform the following checks.

Verify the health of the LightDB-A Database host hardware, and verify that the hosts meet the requirements for running LightDB-A Database. The LightDB-A Database gpcheckperf utility can assist you in confirming the host requirements.

Note If you need to run the gpcheckcat utility, run it a few weeks before the upgrade 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. Place LightDB-A Database in restricted mode when you run the gpcheckcat utility. See the LightDB-A 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. Run the SQL scripts generated by gpcheckcat on a quiescent system. The utility might report false alerts if there is activity on the system.

Important VMware customers should ontact VMware Support if the gpcheckcat utility reports errors but does not generate a SQL script to fix the errors. Information for contacting VMware Support is at https://tanzu.vmware.com/support.
If you have configured and used the VMware LightDB-A Streaming Server (GPSS) in your previous VMware LightDB-A Database installation, you must stop any running GPSS jobs and service instances before you upgrade to a new version of LightDB-A Database. Refer to GPSS Pre-Upgrade Actions for instructions.

If you do not plan to use GPSS, or you have not yet configured GPSS, no action is necessary.

Parent topic: Upgrading to LightDB-A 6

Upgrading from 6.x to a Newer 6.x Release

An upgrade from LightDB-A Database 6.x to a newer 6.x release involves stopping LightDB-A Database, updating the LightDB-A Database software binaries, and restarting LightDB-A Database. If you are using LightDB-A Database extension packages there are additional requirements. See Prerequisites in the previous section.

Log in to your LightDB-A Database coordinator host as the LightDB-A administrative user:
```
$ su - gpadmin
```
Perform a smart shutdown of your LightDB-A Database 6.x system (there can be no active connections to the database). This example uses the -a option to deactivate confirmation prompts:
```
$ gpstop -a
```
Copy the new LightDB-A Database software installation package to the gpadmin user’s home directory on each coordinator, standby, and segment host.
If you used yum or apt to install LightDB-A Database to the default location, run these commands on each host to upgrade to the new software release.

For RHEL/CentOS systems:
```
$ sudo yum upgrade ./greenplum-db-<version>-<platform>.rpm
```
For Ubuntu systems:
```
# apt install ./greenplum-db-<version>-<platform>.deb
```
The yum or apt command installs the new LightDB-A Database software files into a version-specific directory under /usr/local and updates the symbolic link /usr/local/greenplum-db to point to the new installation directory.
If you used rpm to install LightDB-A Database to a non-default location on RHEL/CentOS systems, run rpm on each host to upgrade to the new software release and specify the same custom installation directory with the --prefix option. For example:
```
$ sudo rpm -U ./greenplum-db-<version>-<platform>.rpm --prefix=<directory>
```
The rpm command installs the new LightDB-A Database software files into a version-specific directory under the <directory> you specify, and updates the symbolic link <directory>/greenplum-db to point to the new installation directory.
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 gpadmin.
```
$ sudo chown -R gpadmin:gpadmin /usr/local/greenplum*
```
If needed, update the lightdb_a_path.sh file on the coordinator and standby coordinator hosts for use with your specific installation. These are some examples.
- If LightDB-A Database uses LDAP authentication, edit the lightdb_a_path.sh file to add the line:
```
export LDAPCONF=/etc/openldap/ldap.conf
```
- If LightDB-A Database uses PL/Java, you might need to set or update the environment variables JAVA_HOME and LD_LIBRARY_PATH in lightdb_a_path.sh.
  
  Note When comparing the previous and new lightdb_a_path.sh files, be aware that installing some LightDB-A Database extensions also updates the lightdb_a_path.sh file. The lightdb_a_path.sh from the previous release might contain updates that were the result of installing those extensions.
Edit the environment of the LightDB-A Database superuser (gpadmin) and make sure you are sourcing the lightdb_a_path.sh file for the new installation. For example change the following line in the .bashrc or your chosen profile file:
```
source /usr/local/greenplum-db-<current_version>/lightdb_a_path.sh
```
to:
```
source /usr/local/greenplum-db-<new_version>/lightdb_a_path.sh
```
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:
```
$ sudo rm /usr/local/greenplum-db
$ sudo ln -s /usr/local/greenplum-db-<new_version> /usr/local/greenplum-db
```
Source the environment file you just edited. For example:
```
$ source ~/.bashrc
```
After all segment hosts have been upgraded, log in as the gpadmin user and restart your LightDB-A Database system:
```
# su - gpadmin
$ gpstart
```
For VMware LightDB-A Database, use the gppkg utility to re-install VMware LightDB-A Database extensions. If you were previously using any VMware LightDB-A Database extensions such as pgcrypto, PL/R, PL/Java, or PostGIS, download the corresponding packages from VMware Tanzu Network, and install using this utility. See the extension documentation for details.

Also copy any 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 coordinator and segment host systems.
For VMware LightDB-A Database, if you configured GPSS in your previous installation, you may be required to perform some upgrade actions, and you must re-restart the GPSS service instances and jobs. Refer to Step 2 of the GPSS upgrade procedure for instructions.

After upgrading LightDB-A Database, ensure that all features work as expected. For example, test that backup and restore perform as expected, and LightDB-A 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 LightDB-A Database or VMware LightDB-A Database that were purchased through VMware, contact VMware Support. Information for contacting VMware Support is at https://tanzu.vmware.com/support.

Be prepared to provide the following information:

A completed Upgrade Procedure
Log output from gpcheckcat (located in ~/ltaAdminLogs)