This topic describes how to use the upgrade script to upgrade OceanBase Database.
Prerequisites
Python 2.7 and the following modules have been installed on the OBServer node:
datetimesysosmysql.connectorlogginggetopttime
Procedure
Notice
When you perform the following steps to execute the upgrade script, the value of the -u parameter must be a user that has the read/write and SUPER privileges in the sys tenant.
Step 1: Back up the cluster parameters
Before the upgrade, back up the values of the following parameters, which are used for restoration after the upgrade.
server_permanent_offline_timeenable_rebalanceenable_rereplication
Execute the following statement to obtain cluster-level parameters:
obclient [(none)]> SELECT SVR_IP,ZONE,NAME,VALUE FROM OCEANBASE.GV$OB_PARAMETERS WHERE NAME IN ("server_permanent_offline_time", "enable_rebalance", "enable_rereplication");
+------------+-------+-------------------------------+-------+
| SVR_IP | ZONE | NAME | VALUE |
+------------+-------+-------------------------------+-------+
| 10.10.10.2 | zone1 | enable_rebalance | True |
| 10.10.10.2 | zone1 | enable_rereplication | True |
| 10.10.10.2 | zone1 | server_permanent_offline_time | 3600s |
| 10.10.10.1 | zone2 | enable_rebalance | True |
| 10.10.10.1 | zone2 | enable_rereplication | True |
| 10.10.10.1 | zone2 | server_permanent_offline_time | 3600s |
| 10.10.10.3 | zone3 | enable_rebalance | True |
| 10.10.10.3 | zone3 | enable_rereplication | True |
| 10.10.10.3 | zone3 | server_permanent_offline_time | 3600s |
+------------+-------+-------------------------------+-------+
9 rows in set
Step 2: Upload and decompress the RPM package
Run the
scpcommand to decompress the RPM package of the target version to the OBServer node.In the command,
$rpm_namespecifies the name of the RPM package,observer_ipspecifies the IP address of the OBServer node, and$rpm_dirspecifies the directory where the RPM package is located.[root@xxx /]# scp $rpm_name admin@observer_ip:/$rpm_dirNote
Contact OceanBase Technical Support to obtain the OceanBase Database installation package of the target version.
Decompress the RPM package to the current directory.
$rpm_namespecifies the name of the RPM package.[root@xxx $rpm_dir]# rpm2cpio $rpm_name | cpio -divNote
After the RPM package is decompressed, the
homeandusedirectories are generated in the directory where the RPM package is located. The upgrade script and theoceanbase_upgrade_dep.ymlfile are stored in thehome/admin/oceanbase/etcdirectory.
Step 3: View the upgrade dependencies of different versions
View the upgrade dependencies in the oceanbase_upgrade_dep.yml file in the /rpm_dir/home/admin/oceanbase/etc directory.
For example:
[root@xxx /rpm_dir]# cd home/admin/oceanbase/etc
[root@xxx /rpm_dir/home/admin/oceanbase/etc]# cat oceanbase_upgrade_dep.yml
# Describe the upgrade dependencies of different OceanBase Database versions.
# For each officially released OceanBase Database version, a record with the following attributes is added to the .yaml file:
# * version: the source version or a transition version during the upgrade. The value is a version number in the A.B.C format. If the value is in the A.B.C-D format, the build number must be greater than or equal to D.
# * can_be_upgraded_to: the target versions that the current version can be *directly* upgraded to. The value is a list of versions that are determined through compatibility tests by the QA of OceanBase Database.
# * deprecated: indicates whether the current version has been deprecated. The default value is False. The value True indicates that the current version has been deprecated and can serve as the source version or a transition version of the upgrade, but cannot be the target version of the upgrade.
# * require_from_binary: The default value is False. The value True indicates that if the current version acts as a transition version of the upgrade, you must run the upgrade script and upgrade the OBServer node to this version.
#
# The OceanBase Database upgrade module of OceanBase Cloud Platform (OCP) will read this file. Given the source and target versions of the upgrade, the upgrade module will automatically
# determine the shortest upgrade path if the preceding requirements are met. Algorithm:
# The upgrade module builds a diagram based on the following descriptions. Each version is represented by a node and the value of can_be_upgraded_to is represented by a
# side. The upgrade module will find the shortest path between the source and target versions. Except the start node, other nodes in an upgrade path
# must not represent a version that has been deprecated. If two version formats A.B.C and A.B.C-D are matched, the latter is preferred.
#
#
- version: 4.0.0.0
can_be_upgraded_to:
- 4.1.0.0
require_from_binary:
value: True
when_come_from: [4.0.0.0]
- version: 4.1.0.0
require_from_binary:
value: True
when_come_from: [4.0.0.0, 4.1.0.0]
Step 4: Execute the upgrade_checker.py script
Specify the logon information for directly connecting to the OBServer node from the sys tenant. Run the upgrade_checker.py script to perform a precheck. If the script is successfully executed, you can continue with the upgrade.
For example:
[root@xxx /rpm_dir]# cd home/admin/oceanbase/etc
[root@xxx /rpm_dir/home/admin/oceanbase/etc]# python upgrade_checker.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p******
Step 5: Run the upgrade_pre.py script
Specify the logon information for directly connecting to the OBServer node from the sys tenant. Run the upgrade_pre.py script. If the script is successfully executed, you can continue with the upgrade.
For example:
[root@xxx /rpm_dir/home/admin/oceanbase/etc]# python upgrade_pre.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p******
The upgrade_pre.py script will execute the following commands and actions:
alter system begin upgradealter system begin rolling upgradespecial pre action: to disable and adjust parameters.health check: to perform a cluster-level health check.
Complete capabilities of the upgrade_pre.py script:
./upgrade_pre.py [OPTIONS]
-I, --help Display this help and exit.
-V, --version Output version information and exit.
-h, --host=name Connect to host.
-P, --port=name Port number to use for connection.
-u, --user=name User for logon.
-p, --password=name Password to use when connecting to server. If password is
not given it's empty string "".
-t, --timeout=name Cmd/Query execute timeout(s).
-m, --module=name Modules to run. Modules should be a string combined by some of
the following strings:
1. begin_upgrade
2. begin_rolling_upgrade
3. special_action
4. health_check
5. all: "all" represents that all modules should be run.
They are splitted by ",".
For example: -m all, or --module=begin_upgrade,begin_rolling_upgrade,special_action
-l, --log-file=name Log file path. If log file path is not given it's ./upgrade_pre.log
Maybe you want to run cmd like that:
./upgrade_pre.py -h 127.0.0.1 -P 2881 -u ****** -p ******
Step 6: Upgrade the cluster
The cluster is upgraded zone by zone. Therefore, you must perform the following steps for each zone. The following describes the upgrade procedure by taking zone1 as an example.
Perform a cluster-level health check.
[root@xxx /rpm_dir/home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p******Execute the
STOP ZONEstatement to stop the zone.obclient [(none)]> ALTER SYSTEM STOP ZONE 'zone1';The
STOP ZONEstatement will return a success only after all leaders are migrated out of the zone.Stop the observer processes on the OBServer nodes in the zone. Replace the binary files with those of the new database version and then restart the processes.
Perform a zone-level health check.
[root@xxx /rpm_dir/home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p****** -z 'zone1'The logic of the zone-level health check is the same as that of the cluster-level health check and aims to verify the status of all OBServer nodes in the zone.
Start the zone.
obclient [(none)]> ALTER SYSTEM START ZONE 'zone1';Repeat steps 1 to 5 until the cluster is upgraded in all zones.
Step 7: Execute the upgrade_post.py script
Specify the logon information for directly connecting to the OBServer node from the sys tenant. Execute the upgrade_post.py script to complete the major upgrade operations and related checks.
For example:
[root@xxx /rpm_dir/home/admin/oceanbase/etc]# python upgrade_post.py -h 127.0.0.1 -P 2881 -u xxxx@sys -p******
This script completes the following major upgrade operations and related checks:
- Perform a cluster-level health check.
alter system end rolling upgrade.- Perform the BEGIN UPGRADE operation.
- Correct system variables by tenant.
- Correct system tables by tenant.
- Correct virtual tables and views by tenant.
- Perform related upgrade operations by tenant.
- Perform a self-check on internal tables by tenant.
- Perform the END UPGRADE operation.
- End the upgrade state of the cluster by using the ALTER SYSTEM END UPGRADE statement.
- Enable the parameters disabled during the upgrade and perform a check.
Skip Step 3 to 5, Step 7, and Step 9 in the following scenarios:
- Intra-version upgrade
- Cross-version upgrade in which the source and target versions have the same version of data
Complete capabilities of the upgrade_post.py script:
./upgrade_post.py [OPTIONS]
-I, --help Display this help and exit.
-V, --version Output version information and exit.
-h, --host=name Connect to host.
-P, --port=name Port number to use for connection.
-u, --user=name User for logon.
-p, --password=name Password to use when connecting to server. If password is
not given it's empty string "".
-t, --timeout=name Cmd/Query execute timeout(s).
-m, --module=name Modules to run. Modules should be a string combined by some of
the following strings:
1. health_check
2. end_rolling_upgrade
3. tenant_upgrade
4. end_upgrade
5. post_check
6. all: "all" represents that all modules should be run.
They are splitted by ",".
For example: -m all, or --module=health_check,begin_rolling_upgrade
-l, --log-file=name Log file path. If log file path is not given it's ./upgrade_pre.log
Maybe you want to run cmd like that:
./upgrade_post.py -h 127.0.0.1 -P 2881 -u *** -p ******
Step 8: Restore the cluster parameters
Restore the parameters backed up in Step 1 to the original values.
For example:
ALTER SYSTEM SET server_permanent_offline_time = xxx;
ALTER SYSTEM SET enable_rebalance = xxx;
ALTER SYSTEM SET enable_rereplication = xxx;
What to do next
Verify whether the upgrade is completed. For more information, see Check upgrade results.