Upgrade an OceanBase cluster

This topic describes how to upgrade an OceanBase cluster.

Scenarios

Upgrade a business OceanBase cluster.

Prerequisites

• The OceanBase cluster to be upgraded must be in Running state.

• The OceanBase cluster to be upgraded is not undergoing a cluster-level major compaction if its version is earlier than V4.0 or a tenant-level major compaction if its version is V4.0 or later.

• The sys tenant must be configured with the primary zone if the OceanBase cluster to be upgraded is of a version earlier than V4.0. User tenants must be configured with the primary zone if an OceanBase cluster is upgraded from a minor version to another within V4.0 or from V4.0 to V4.1.

• Only one top-priority primary zone can be specified for the sys tenant if the OceanBase cluster to be upgraded is of a version earlier than V4.0. Otherwise, system tables will be distributed during the upgrade, which may throw an exception.

• An OceanBase cluster of a version earlier than V4.0 can be upgraded only to another version earlier than V4.0.

Technical mechanism

OceanBase Cloud Platform (OCP) obtains the shortest path from the upgrade path file based on the source and target versions. A part of the upgrade path file is as follows:

- version: 2.2.74
  can_be_upgraded_to:
      - 2.2.75
- version: 2.2.75
  can_be_upgraded_to:
      - 2.2.76
- version: 2.2.76
  can_be_upgraded_to:
      - 2.2.77
- version: 2.2.77
  can_be_upgraded_to:
      - 2.2.78
  can_be_direct_upgraded_to:
      - 3.1.2
- version: 3.1.0
  can_be_upgraded_to:
      - 3.1.1
- version: 3.1.1
  can_be_upgraded_to:
      - 3.1.2
- version: 3.1.2
  can_be_upgraded_to:
      - 3.1.3
# ...

OCP stores upgrade path files at three locations.

1. The MetaDB. When you upload the OceanBase RPM package, OCP parses the upgrade path file in the package and saves the file to the MetaDB.

2. The ./ocp-server/etc path under the working directory of OCP.

3. The JAR package of OCP.

Before the upgrade starts, OCP visits the preceding locations 1, 2, and 3 in sequence until it obtains the upgrade path from the source version to the target version.

Considerations

• OceanBase Database V4.0 involves major changes. Therefore, you cannot skip V4.0 and upgrade from a version earlier than V4.0 to a version later than V4.0.

• OCP V4.0.0 to V4.0.2 support only the upgrade from a minor version to another within OceanBase Database V4.0. OCP V4.0.3 and later support the upgrade from OceanBase Database V4.0 to V4.x.

• When you perform a zone-by-zone rotating upgrade, make sure that the available replicas of all tenants in the cluster are in the majority when any zone is stopped, otherwise the upgrade precheck will fail.

• When you perform a zone-by-zone rotating upgrade, OCP first upgrades the zone where the RootService node is located.

• In a forced upgrade, all zones in the cluster are concurrently upgraded, which results in business interruptions.

The following table describes the version compatibility between OCP and OCP-controlled OceanBase clusters.

Procedure

For information about the upgrade procedure, see Upgrade an OceanBase cluster.

FAQ

What can I do if an error message prompts that the upgrade path from version a to version b is not found?

Contact OceanBase Technical Support to check whether the upgrade from version a to version b is supported. It is possible that version b is later than version a, but is released earlier than version a. In this case, you cannot upgrade from version a to version b.

If the upgrade is supported, you can try the following two methods in sequence to solve the issue:

1. Delete the RPM package of version b in the OCP console and upload it again.
2. View the upgrade path file oceanbase_upgrade_dep.yml in ./ocp-server/etc/ under the working directory of OCP and check whether the upgrade path from version a to version b exists. If not, decompress the RPM package of version b, open the oceanbase_upgrade_dep.yml file in the etc directory, copy the upgrade path from version a to version b, and paste it to the upgrade path file in the working directory of OCP.

What can I do if an error message prompts that the primary zone of tenant xx cannot be RANDOM?

Take note of the following requirements for specifying the primary zone when you upgrade an OceanBase cluster:

1. You must specify the primary zone for the sys tenant if the OceanBase cluster to be upgraded is of a version earlier than V4.0.
2. You must specify the primary zone for user tenants if an OceanBase cluster is upgraded from a minor version to another within V4.0 or from V4.0 to V4.1.
3. There are no requirements for specifying the primary zone when the OceanBase cluster to be upgraded is of a version later than V4.1.

What can I do if the following error message is reported: "current standby cluster not syncronizing!!!" ?

The primary and standby clusters to be upgraded must contain business tenants. The upgrade script of OceanBase Database requires that the value of current_scn of the standby cluster must always be 0 if no business tenants exist in the primary and standby clusters. However, when the upgrade starts, the upgrade script checks the value of current_scn of the standby cluster and requires a non-zero value, otherwise the upgrade script determines that the primary and standby clusters are not synchronized.

A temporary solution is described as follows:

1. Execute the alter system end upgrade statement in the sys tenant of both the primary and standby clusters to disable the upgrade mode.
2. Create a temporary tenant.
3. Query the v$ob_cluster view in the standby cluster, until the value of current_scn approximately equals the current timestamp.
4. Execute the alter system begin upgrade statement in the sys tenant of both the primary and standby clusters to enable the upgrade mode.
5. Retry the task.

OCP V3.3.5 introduces a precheck item for you to check whether a business tenant exists in a cluster before you start an upgrade.