OceanBase数据库集群升级手册

注意事项

1. OceanBase过渡版本不可以直接升级，需要参考oceanbase_upgrade_dep.yml文件中的升级版本序列。

2. 升级过程中可能会涉及下列参数的变化，升级前需要对这些参数进行备份：

• server_permanent_offline_time
• enable_rebalance
• enable_rereplication

3. OceanBase数据库自以下版本开始对AVX指令集的强制依赖策略已调整：对于V4.3.5版本，从V4.3.5 BP4版本开始不再强制要求AVX指令集支持。

4. OceanBase集群升级时，有如下限制：

• 禁止DDL：升级过程中的部分阶段需要禁止DDL，升级完成后会自动打开。
• 禁止MAJOR FREEZE：部分版本之间的升级会禁止合并，升级完成后会自动打开。
• 禁止迁移复制和负载均衡：部分版本之间的升级会禁止迁移复制和负载均衡。
• 禁止物理备份恢复：集群升级过程中不会发起物理基线备份（日志归档不断）、物理恢复。
• 禁止新建租户。

5. 如果OceanBase集群关联了仲裁服务，那么在进行OceanBase集群版本升级时，需要确保先升级仲裁服务版本，然后再升级OceanBase集群版本。

--查询是否关联了仲裁服务
SELECT * FROM oceanbase.DBA_OB_ARBITRATION_SERVICE;

升级仲裁服务

略（不涉及）。

升级OB集群

⚠️升级OB集群前，确保已在所有的OBServer节点中安装Python 2环境，并且安装适配Python 2的mysql.connector模块。

#检查Python版本
python -V#检查是否安装了mysql.connector模块
python -c "import mysql.connector; print('已安装')"#安装mysql.connector模块
yum install python2-pip
pip install mysql-connector-python
python -c "import mysql.connector; print('已安装')"#安装指定版本的mysql.connector模块
pip uninstall mysql-connector-python
pip install mysql-connector-python==8.0.15
python -c "import mysql.connector; print('已安装')"

分析升级拓扑文件

解压目标版本的OceanBase RPM包后，可以获取oceanbase_upgrade_dep.yml文件，该文件记录了OceanBase集群的版本升级拓扑图。

解压OceanBase RPM包至当前目录：

sudo rpm2cpio oceanbase-standalone-4.3.5.4-104000062025090915.rpm | cpio -div

解压RPM包完成后，会在存放RPM包的目录下生成home和use两个目录。升级相关脚本和oceanbase_upgrade_dep.yml文件存放home/admin/oceanbase/etc目录下。

oceanbase_upgrade_dep.yml文件中OceanBase集群各个版本升级依赖关系大致如下：

- version: 4.0.0.0can_be_upgraded_to:- 4.1.0.0- version: 4.1.0.0-100000982023031415can_be_upgraded_to:- 4.1.0.0deprecated: True- version: 4.1.0.0can_be_upgraded_to:- 4.1.0.1- version: 4.1.0.1can_be_upgraded_to:- 4.2.0.0require_from_binary:value: Truewhen_come_from: [4.0.0.0, 4.1.0.0-100000982023031415]- version: 4.3.0.0can_be_upgraded_to:- 4.3.0.1- version: 4.3.0.1can_be_upgraded_to:- 4.3.1.0

oceanbase_upgrade_dep.yml文件中相关属性含义：

• version：当前版本。
• can_be_upgraded_to：当前OceanBase数据库版本可以升级到的目标版本。
• deprecated：当前版本是否可以作为升级的目标版本。若为true，表示不能作为升级的目标版本。
• require_from_binary：升级序列包含当前版本时是否需要先升级到当前版本，即当前版本是否是升级序列中的barrier版本。
  • value：当值为true时，和when_come_from属性联合使用。
  • when_come_from：是一个列表，当when_come_from未定义时，表示任何版本升级到目标版本时，都要先升级到当前barrier版本；当when_come_from已定义，表示列表中的版本号升级到目标版本时，需要先升级到当前barrier版本。

例如：示例中的4.0.0.0和4.1.0.0-100000982023031415版本的OceanBase集群在升级到V4.2.0.0版本时，都要先升级到V4.1.0.1(barrier)版本。

确认升级流程

通过分析示例文件oceanbase_upgrade_dep.yml，可以得到以下升级序列：

• V4.0.0.0 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0
• V4.1.0.0-100000982023031415 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0
• V4.1.0.0 > V4.1.0.1 > V4.2.0.0
• V4.3.0.0 > V4.3.0.1 > V4.3.1.0

以下将以三副本的OceanBase集群为例介绍升级流程。

• 升级路径中有barrier版本。如果当前OceanBase集群版本是V4.0.0.0版本，升级流程如下：

  • 需要先将Zone1从V4.0.0.0版本升级到V4.1.0.1(barrier)版本，再将Zone2从V4.0.0.0版本升级到V4.1.0.1（barrier）版本，然后将Zone3从V4.0.0.0版本升级到V4.1.0.1(barrier)版本；此时，整个集群已经从V4.0.0.0版本升级到了V4.1.0.1（barrier）版本。
  • 需再次按照Zone顺序依次将Zone1、Zone2、Zone3从V4.1.0.1（barrier）版本升级到V4.2.0.0，等到所有Zone均升级到V4.2.0.0，集群升级就完成了。

• 升级路径中没有barrier版本。如果当前OceanBase集群版本是V4.3.0.0版本，升级流程如下：

  • 您只需要先将Zone1从V4.3.0.0版本升级到V4.3.1.0版本，再将Zone2从V4.3.0.0版本升级到V4.3.1.0版本，然后将Zone3从V4.3.0.0版本升级到V4.3.1.0版本，等到所有Zone均升级到V4.3.1.0，集群升级就完成了。

备份集群配置项

升级流程开始前需要备份下列配置项旧值，用于执行升级流程后还原：

• server_permanent_offline_time
• enable_rebalance
• enable_rereplication

在SYS租户中执行以下SQL语句：

select svr_ip,zone,scope,tenant_id,name,data_type,value,default_value,section,edit_level 
from gv$ob_parameters where name in
(
'server_permanent_offline_time',
'enable_rebalance',
'enable_rereplication'
);

安装目标RPM包

在所有OBServer节点，使用以下命令安装OceanBase RPM包。

rpm -Uvh oceanbase-4.2.0.0-100010022023081911.el7.x86_64.rpm

升级相关脚本和oceanbase_upgrade_dep.yml文件存放/home/admin/oceanbase/etc目录下。目录/home/admin/oceanbase/etc为OceanBase数据库的默认安装目录。

执行升级检查脚本

在任意一个OBServer节点中指定sys租户直连OBServer节点的登录信息，执行upgrade_checker.py脚本进行升级前置检查。

cd /home/admin/oceanbase/etc
python upgrade_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p******

脚本执行成功表示可以继续升级。

执行预升级脚本

在任意一个OBServer节点中指定sys租户直连OBServer节点的登录信息，执行upgrade_pre.py脚本进行升级前置检查。

cd /home/admin/oceanbase/etc
python upgrade_pre.py -h 127.0.0.1 -P 2881 -u root@sys -p******

脚本执行成功表示可以继续升级。

📖 upgrade_pre.py脚本会执行以下命令及动作：

• alter system begin upgrade
• alter system begin rolling upgrade
• special pre action：关闭及调整配置项。
• health check: 集群级别健康检查。

集群升级

按Zone升级，每个Zone都要按照下面的步骤执行一遍，以zone1为例。

---

1. 进行集群级别的健康检查。

cd /home/admin/oceanbase/etc
python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p******

---

2. 停止Zone。

⚠️ 单机或单副本OceanBase数据库升级无需停止Zone。

使用root用户登录到集群的sys租户，使用以下命令停止Zone。

--停止zone1
ALTER SYSTEM STOP ZONE 'zone1';--查看Zone状态是否为INACTIVE 
SELECT ZONE,STATUS FROM oceanbase.DBA_OB_ZONES;

---

3. Zone内机器停进程，替换新版本binary重启。

以admin用户停止observer进程：

su - admin
kill -9 `pidof observer`

重新启动observer进程：

cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer

再次启动observer进程时不需要指定启动参数，因为之前的启动参数已经写到参数文件里了。

---

4. 执行Zone级别健康检查。

cd /home/admin/oceanbase/etc
python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p****** -z 'zone1'

---

5. 启动Zone。

使用root用户登录到集群的sys租户，使用以下命令启动Zone。

--启动zone1
ALTER SYSTEM START ZONE 'zone1';--查看Zone状态是否为ACTIVE 
SELECT ZONE,STATUS FROM oceanbase.DBA_OB_ZONES;

---

6. 重复步骤1~5，直至所有Zone升级完成。

执行升级后脚本

在任意一个OBServer节点中指定sys租户直连OBServer节点的登录信息，执行upgrade_post.py脚本完成主要的升级操作及相关检查。

cd /home/admin/oceanbase/etc
python upgrade_post.py -h 127.0.0.1 -P 2881 -u root@sys -p******

📖 upgrade_post.py 脚本会完成以下升级动作：

• 集群级别健康检查。
• alter system end rolling upgrade
• 按租户执行begin upgrade。
• 按租户执行系统变量修正。
• 按租户执行系统表修正。
• 按租户执行虚拟表/视图修正。
• 按租户执行版本相关升级动作。
• 按租户执行内部表自检操作。
• 按租户结束end upgrade。
• alter system end upgrade：结束集群升级状态。
• upgrade post check：重新打开升级过程中禁用的部分配置项，并执行检查。

⚠️ 在执行升级脚本upgrade_post.py时，如果出现错误，其原因很可能是RS切主过。可以通过以下步骤进行排查与修复：

• 可以执行SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE job_type = 'upgrade_all' ORDER BY job_id DESC LIMIT 1;验证升级任务状态。
• 若JOB_STATUS显示为inprogress，且MODIFY_TIME为最近时间（与当前时间间隔较短），则可以手动执行一下ALTER SYSTEM RUN UPGRADE JOB 'UPGRADE_ALL';命令解决这个问题。
• 重新执行升级脚本。

还原集群配置项

基于升级前备份的配置项旧值，使用root用户登录到集群的sys租户，使用以下命令还原相关配置项。

ALTER SYSTEM SET server_permanent_offline_time = '3600s';
ALTER SYSTEM SET enable_rebalance = 'True';
ALTER SYSTEM SET enable_rereplication = 'True';

升级后检查

使用root用户连接sys租户，使用视图查看集群升级相关事件信息。

SELECT * FROM oceanbase.DBA_OB_CLUSTER_EVENT_HISTORY WHERE MODULE='UPGRADE'\G

能看到具体的升级事件（BEGIN_UPGRADE、BEGIN_ROLLING_UPGRADE、END_ROLLING_UPGRADE）和版本变化（cluster_version、build_version）。

注：如果在升级前OceanBase集群配置了cgroup，那么在OceanBase集群升级后，需要重新配置cgroup。

References
【1】https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002016127