Upgrading a Cluster

Cluster upgrade refers to that the database binary package and metadata are upgraded to a higher version without data export on the basis of the current cluster.

PTK defines a complete upgrade process meanwhile the upgrade also depends on the upgrade_sql package in the database installation package. If the upgrade becomes abnormal, it needs to be processed manually.

MogDB Versions Supported for Upgrade

Note: For early versions, a cluster of 2.0.x needs to be upgraded to 2.1, and then to 3.0.0/3.0.1. Because PTK does not support upgrade to the preview version, it does not support upgrade from 2.0.x to 3.0.0/3.0.1.

Upgrade Constraints

• A cluster that has CM enabled cannot be upgraded, but you can uninstall CM via PTK version 1.4.0 or above, and then upgrade the cluster.
• A cluster earlier than 2.0 does not support upgrade.
• A cluster of a higher version cannot be upgraded to a lower version.
• PTK does not support upgrade to the preview version (the preview version means that the second number in a version is 1, such as 3.1.0).
• The cluster stream replication parameter enable_stream_replication needs to be set to on.
• The cluster status must be normal before upgrade.

In-place Upgrade

The in-place upgrade consists of two phases:

• Upgrade (can be rolled back after the upgrade fails, can be repeated to execute the upgrade command, support for continuous transmission at breakpoints)
• Commit (commit only after the first step of the upgrade is successful, and cannot be rolled back after the commit)

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.

So for clusters that used plugins, you need to additionally specify the following parameters to 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)

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

After executing the above commands, PTK will complete the upgrade operation. After the upgrade, the cluster is already running with the new version, at this point, you can verify the new features on the database, and if you encounter any problems, you can roll back the cluster by upgrade-rollback command, and PTK will roll back the cluster to the state of the old version.

ptk cluster -n <cluster_name> upgrade-rollback

If there is an interruption in the upgrade process that reports an error, you can resolve it by human intervention, and when the problem is resolved, you can continue to complete the upgrade by re-executing the upgrade command.

upgrade-commit

Commit an upgrade, enable the cluster write/read status, and delete the backup file of the old version. After that, the cluster cannot be rolled back.

ptk cluster -n <cluster_name> upgrade-commit

Rolling Upgrade

PTK 1.4.0 and above support rolling upgrade, but since the rolling upgrade process always upgrades the standby node and does not directly upgrade the primary node, you cannot submit any SQL during the upgrade process, so there are the following two constrains for rolling upgrade:

1. The kernel version of the database before and after the upgrade should be consistent, if not, you need to execute the upgrade SQL, so it can not be supported for the time being;

   The output of Number field by running ptk candidate db is the kernel version number (requires PTK 1.4.0 or later).

2. There are no plugins that need to be upgraded;

Process of rolling upgrade

Procedures of rolling upgrade

Take one primary and one standby as an example, assume that the primary IP is IP1 and the standby IP is IP2 in the initial state.

1. Check if the machine status is Normal.

   ptk cluster -n <cluster_name> status

2. Upgrade standby node in the cluster.

   Perform a single-node upgrade of a standby node in the cluster with the -H parameter, and the node should be able to temporarily switchover to the primary node to provide services.

   ptk cluster -n <cluster_name> upgrade -p <new version package> -H <IP2>

3. Perform primary/standby nodes switchover.

   Switch the upgraded standby node to the primary node and demote the original primary node to the standby node.

   ptk cluster -n <cluster_name> switchover -H <IP2>

4. Upgrade the original primary node.

   ptk cluster -n <cluster_name> upgrade -p <new version package> -H <IP1>

5. (Optional) Re-switch the primary node to the original primary machine.

   ptk cluster -n <cluster_name> switchover -H <IP1>

6. Upgrade commit.

   ptk cluster -n <cluster_name upgrade-commit