In-place Upgrade

In-place upgrade means upgrading all nodes in the cluster at once and stopping the business during the upgrade.

The most convenient and commonly used upgrade method is to use MogDB deployment and operation maintenance tool PTK. The process is simple and easy to operate, just put the new version of the package in the specified directory, and then execute the corresponding PTK commands, PTK will automatically complete all the checks (including the system, disk, and database status, etc.), perform backup operations, and then carry out upgrades or rollbacks.

Supported Upgrade Version

MogDB supports upgrading V3.0.0-V3.0.X and V5.0.0-V5.0.X versions of databases to V5.0.X via PTK. Upgrading from a higher version to a lower version is not supported.

Backup Data

In the upgrade process, to avoid the implementation of errors in the upgrade exception, resulting in the original version of the database files or data being accidentally modified, and can not be performed to roll back the operation of the situation, the upgrade must be done before the data backup and integrity protection, to facilitate the use of the upgraded data backed up when the upgrade error occurs restored to the state before the upgrade, to avoid operational errors resulting in the business can not be recovered.

In the process of upgrading with PTK, the tool will automatically complete the backup of the original version of the database software, If you need to back up all the data files, you can use gs_basebackup for the base physical backup, an example is as follows:

Create a backup directory using the database user (e.g. omm)
```
mkdir /home/omm/mogdb_data_bak
```
Backup via gs_basebackup
```
gs_basebackup -D /home/omm/mogdb_data_bak -h 127.0.0.1 -p 26000
```
The host name and port number need to be replaced according to the actual situation.

Upgrade Steps

Before upgrading the database cluster, you need to check if the plug-in has been created for the current database cluster with the following command:

ptk cluster -n <CLUSTER_NAME> list-plugins

After execution, two tables will be output, the first table represents the list of installed plugins, installed does not mean used in the database.

The second table represents the specific plugins that have been created in each database, if no plugins have been created, the Extension(s) field will be empty.

We need to make sure that there is a value under the Extension(s) field in the second table, the upgrade command is different in different cases.

No Plugin Created

If no plug-ins have been created in the database prior to the upgrade, you can directly specify the new version of the installation package for the upgrade:

ptk cluster -n <CLUSTER_NAME> upgrade [-y] -p <PACKAGE_PATH>

Plugin Created

If a plugin is used in the database, it may cause the plugin to be unavailable after the upgrade or the upgrade to fail because the database metadata will change after the upgrade.

--plugin-dir: The local directory, which holds the pre-downloaded new version of the plugin package (! Please do not change the file name of the downloaded plugin package)
--plugin-upgrade-patch: SQL patch package required for plugin upgrade (this parameter does not need to be specified when the target version is MogDB 5.0.2 or later)

The upgrade command is as follows:

ptk cluster -n <CLUSTER_NAME> upgrade [-y] -p <PACKAGE_PATH> --plugin-dir <PLUGIN_DIR>

Note: The plug-in version must match with the database version. If a plugin is included, when the database is upgraded, the plugin must be upgraded as well.

Upgrade Commit

After executing the above commands, PTK will complete the complete operation of the upgrade. After the upgrade, the cluster runs with the new version, at this time, you can verify the operation of the database. When you check the cluster status is normal after the upgrade, you can submit the upgrade by using the following commands to enable the cluster read/write features and delete the backup files of the old version. Note that the cluster cannot be rolled back after the commit, so please make sure it is correct before committing.

ptk cluster -n <cluster_name> upgrade-commit

After commit, you can check the cluster status with the following command:

ptk cluster -n <cluster_name> status

Upgrade Rollback & Data Recovery

If there is an error interruption during the upgrade process, you can solve the problem by human intervention. When the problem is solved, you can continue to complete the upgrade by re-executing the upgrade command.

If you find a problem after upgrading, you can roll back the cluster by using the upgrade-rollback command, and PTK will roll back the cluster to the old version of the state.

ptk cluster -n <cluster_name> upgrade-rollback

If an exception occurs during the upgrade process and you need to restore from backup data, you can perform the following operations:

Stop the database
```
gs_ctl stop -D $PGDATA
```
Clean up all or part of the data files in the original database
```
rm -rf $PGDATA/*
```
Restore the required database files from a backup as database system user
```
cp -r /home/omm/mogdb_data_bak/* $PGDATA/
```
If there is a linked file in the database, it needs to be modified so that it links to the correct file
Restart the database server and check the database contents to ensure that the database has been restored to normal state
```
gs_ctl start -D $PGDATA
```

Notes

If you find that the above upgrade operation does not work as expected, for example, the status information is abnormal when displaying the cluster status, you need to contact our engineers to solve the problem.

Please verify that all database statuses are correct after the upgrade before performing the upgrade commit operation. If the statuses are incorrect, you need to roll back the operation to ensure that the database is restored to the correct status before the upgrade, and then contact our engineers to confirm the problems encountered during the upgrade.