v5.0

升级指南

升级概述

当数据库发布的新的版本，用户根据发布信息决定使用新版本数据库时，需要做升级操作。集群升级是指在现有集群的基础上，无需导出数据的情况下，直接将数据库二进制文件及元数据升级到更高的版本。

本文档主要适用于升级操作人员。操作人员必须具备以下经验和技能：

熟悉当前网络的组网和相关网元的版本信息。
有该设备维护经验，熟悉设备的操作维护方式。

升级方案

MogDB支持的升级方式有三种：就地升级、临时升级和灰度升级。升级策略需要考虑版本间是否发生元数据变更。当元数据的版本不发生变化时可以使用临时升级和灰度升级（如V5.0.0升级至V5.0.1），发生变化时只能通过PTK升级（如V3.0.0升级至V5.0.0）。

就地升级（推荐）：使用MogDB配套的部署运维工具PTK升级，是最方便常用的升级方式，升级过程简单易操作，只需将新版压缩包放在指定目录，然后执行对应的PTK命令，PTK就会自动完成所有检查（包括系统、磁盘、数据库状态等）、执行备份操作，然后进行升级或回滚。

说明：MogDB V5.0.6支持通过PTK对V3.0.0-V3.0.7和V5.0.0-V5.0.5版本的数据库进行集群升级，用户操作简单，使用场景限制最小。

临时升级：当用户遇到严重问题时，研发工程师定位该问题并进行修复，发出新的补丁版本进行替换，将采用临时升级。该升级方式只进行二进制文件替换，不需要额外操作，主要用于替换版本和原版本之间代码更新非常少的场景。该升级方式的优点是轻量化、操作灵活。缺点在于使用场景仅限问题修复，版本之间不能有任何的元数据或者存储文件格式变更。临时升级仅支持小版本升级，升级操作需要停止业务进行，一次性升级所有节点。

灰度升级：该升级方式面向集群模式，对于集群中的节点逐个进行升级。优点在于始终有节点能够对外提供服务，保证业务不中断。缺点在于主备节点上不同版本数据库同时运行，元数据的版本和日志存储文件的版本都不能有任何变更。灰度升级仅支持元数据无变更的版本之间升级。

请根据业务情况做好方案选择，如有疑问请联系云和恩墨工程师提供支持。

升级影响和约束

升级包含以下影响和约束，在升级前应该做好充分检查和了解，确保条件都能满足的情况下再进行升级，如果有任何疑问需联系原厂工程师。

升级操作不能和扩容、缩容同时执行。
不支持虚拟IP。
升级过程中，不允许对wal_level，max_connections，max_prepared_transactions，max_locks_per_transaction这四个GUC参数的值进行修改。如果修改，会导致回滚后实例启动异常。
建议在数据库系统空闲情况下进行升级，尽量避开业务繁忙的时间段（可按照经验判断，如节假日等）。
升级前尽可能保证数据库状态正常。通过PTK安装的版本可通过ptk cluster -n <CLUSTER_NAME> status命令查看集群状态，Normal代表集群所有实例正常可用。通过OM安装的版本可以通过gs_om -t status查询，查询结果的cluster_state为Normal代表数据库正常可用。
升级前保证数据库互信正常，可以在任意节点上，通过ssh hostname命令，连接另外一个节点进行验证。如果各机器间互连不用输入密码，说明互信正常（通常数据库状态正常时，互信一般都是正常的）。
升级前后，数据库的部署方式（配置文件）不能发生变化。升级前PTK会对部署方式进行校验，如果改变会报错。
数据库运行正常且主DN的数据完全同步到备DN。
升级过程中不允许打开kerberos开关。

注意：

如果原数据库版本为3.0.X，需要额外检查是否存在包含rownum和connect by语法的视图。

可以通过如下语句来获取视图定义，检查其是否存在rownum或者connect by语法：
select pg_get_viewdef('viewname') def where def like '%ROWNUM%' or def like '%CONNECT BY%' ;
如果存在这样的视图，需执行以下操作：
获取视图定义
Select pg_get_viewdef('v1'); 
v1代表存在rownum或者connectby语法的视图名称。
删除相关视图
Drop view v1;
升级完成后使用原视图定义重建这些视图
Create view as viewdef;
viewdef代表第一步中获取的视图定义。

就地升级

安装升级PTK

PTK作为一个部署管理工具，并不需要和数据库实例安装到一起。我们推荐使用一个中控管理机器来安装PTK，然后通过该中控机去部署管理数据库实例到其他服务器，这样的话，可以避免数据库实例机器的故障造成PTK不可用。

在线安装

注意：命令行安装方式不支持 Windows 系统

在 MacOS 或 Linux 系统的终端中，执行以下指令即可自动完成安装：

curl --proto '=https' --tlsv1.2 -sSf https://cdn-mogdb.enmotech.com/ptk/install.sh | sh

该指令会自动将 PTK 安装在用户的家目录 $HOME/.ptk 目录下，该目录以后会作为 PTK 工具的工作目录，其产生的缓存文件、数据文件以及集群的配置信息，备份信息等文件均会存储到该目录下。同时，安装指令会自动将 $HOME/.ptk/bin 的路径加入到对应 SHELL Profile 文件的 PATH 环境变量中，这样在用户登录到服务器后就可以直接使用 ptk 指令了。

离线安装

如果你需要安装的服务器无法直接访问外网或者是需要在 Windows 系统上使用 PTK 工具，此时可以通过手动方式进行安装。

请按照以下操作步骤进行安装：

第一步：先在个人电脑上下载你所要安装的机器的对应安装包，以下是不同系统架构的最新版的安装包:

文件	操作系统	架构
ptk_darwin_arm64.tar.gz	Darwin	arm64
ptk_darwin_x86_64.tar.gz	Darwin	x86_64
ptk_linux_arm64.tar.gz	Linux	arm64
ptk_linux_x86_64.tar.gz	Linux	x86_64
ptk_windows_x86_64.tar.gz	Windows	x86_64

第二步：下载好安装包以后，通过内网将安装包发送到目标服务器上解压；

第三步：解压后会得到一个名为 ptk 的二进制文件，该文件即为 PTK 的可执行文件，可以根据个人偏好，将该文件移动到合适的目录（推荐 $HOME/.ptk/bin/ 目录，需手动创建），然后将所在所在目录添加到 PATH 环境变量中即可；

升级PTK

如果是离线方式安装的，重新下载最新的安装包后替换覆盖服务器上的二进制文件即可升级到最新版。

如果是在线方式安装的，执行以下指令即可自动将 PTK 升级到最新版：

ptk self upgrade

备份数据

在升级过程中，为避免执行错误出现升级异常，导致原版本数据库文件或数据被意外修改，而无法执行回滚操作的情况，升级前须做好数据备份和完整性保护，方便在升级发生错误时使用已备份的数据恢复到升级前状态，避免因操作失误导致业务无法恢复的情况出现。

在使用PTK升级过程中，工具会自动完成原版本数据库软件的备份，如果需要备份全部的数据文件，可以使用gs_basebackup进行基础的物理备份，示例如下：

使用数据库用户（如omm）创建备份目录
```
mkdir /home/omm/mogdb_data_bak
```
通过gs_basebackup进行备份
```
gs_basebackup -D /home/omm/mogdb_data_bak -h 127.0.0.1 -p 26000
```
需根据实际情况替换主机名、端口号。

集群升级

升级前检查

我们需要先通过以下命令来确认当前数据库集群是否有创建过插件：

ptk cluster -n <CLUSTER_NAME> list-plugins

执行后会输出两个表格，第一个表格代表安装过的插件列表，安装过并不意味着数据库里使用了。第二个表格代表具体的每个数据库中创建过的插件，如果没有创建过任何插件，Extension(s)字段会为空。我们需要确认第二个表格中Extension(s)字段下是否有值，不同的情况升级的方式有些许差别。

未创建插件的集群升级

如果升级前的数据库内没有创建过任何插件，可以直接指定新版本的安装包进行升级：

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

含有插件的集群升级

如果数据库中使用了插件的话，由于升级后数据库元数据会发生改变，可能会导致升级后插件不可用或者升级失败。所以对于使用了插件的集群，需要额外指定以下参数来升级：

--plugin-dir: 本地目录，该目录下存放提前下载的新版本插件包（下载的插件包请勿变更文件名）

升级命令如下：

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

注意：插件版本必须和数据库版本进行匹配，如果包含插件，在数据库升级时必须对插件也进行升级。

升级提交

执行上述命令后，PTK会完成升级的完整操作，升级后集群以新版本运行，此时您可以在数据库上进行验证操作，当升级后检查集群状态为正常的情况下，可以通过以下命令提交升级，开启集群读写状态，删除旧版本的备份文件。注意，提交后集群无法再回滚，请确认正确后再提交。

ptk cluster -n <cluster_name> upgrade-commit

确认提交升级后，可以通过以下命令查看集群状态：

ptk cluster -n <cluster_name> status

注意：

MogDB 5.0.6新增并行导入导出功能（详见逻辑备份恢复效率增强），该功能依赖于新增内置插件tidrangescan。升级完成后，如需使用gs_dump、gs_restore并行导入导出功能，需在要进行导入导出的库里手动创建tidrangescan插件：
create extension tidrangescan;

升级回滚和数据恢复

如果升级过程中存在报错中断，您可以通过人为介入来解决，当解决了问题后，可以通过重新执行升级指令继续完成升级。

如果升级后验证发现问题可以通过upgrade-rollback命令进行回滚，PTK会将集群回滚为旧版本的状态。

ptk cluster -n <cluster_name> upgrade-rollback

如果升级过程发生异常，需要从备份数据进行恢复，可执行以下操作：

停止数据库服务器
```
gs_ctl stop -D $PGDATA
```
清理原库中的所有或部分数据文件
```
rm -rf $PGDATA/*
```
使用数据库系统用户权限从备份中还原需要的数据库文件
```
cp -r /home/omm/mogdb_data_bak/* $PGDATA/
```
若数据库中存在链接文件，需要修改使其链接到正确的文件
重启数据库服务器，并检查数据库内容，确保数据库已经恢复到所需的状态
```
gs_ctl start -D $PGDATA
```

注意事项

在执行以上升级操作的过程中，如果发现未能按照预期正常进行，例如展示集群状态时，状态信息为异常等，需要联系原厂工程师进行解决。

请在升级后所有数据库状态都验证正确以后，再执行升级提交操作，如果状态不正确，需进行回滚操作，确保数据库恢复到升级前的正确状态，然后联系原厂工程师对升级中遇到的问题进行确认。

临时升级

升级前检查

升级前需要检查的所有内容在升级影响和约束章节已经列出。请在对所有内容进行充分检查和了解后再进行升级操作。在升级过程中如遇到任何问题，请及时联系原厂工程师进行处理。

备份数据

采用临时升级方式时，在升级前，请务必手动完成备份，具体操作示例如下：

备份原版本可执行文件

mkdir -p /home/omm/mogdb_app_bak
cp -r $GAUSSHOME/* /home/omm/mogdb_app_bak/*

备份用户数据

mkdir /home/omm/mogdb_data_bak
gs_basebackup -D /home/omm/mogdb_data_bak -h 127.0.0.1 -p 26000

需根据实际情况替换主机名、端口号。

升级步骤

临时升级的具体操作步骤如下：

关停数据库
```
gs_ctl stop -D $PGDATA
```

解压目标版本安装包，如：

tar -xvf MogDB-5.0.6-Kylin-x86_64-all.tar.gz

进入解压后的目录
```
cd MogDB-5.0.6-Kylin-x86_64-all/
```

解压内核包，覆盖原始的app文件夹

tar -xvf MogDB-5.0.6-Kylin-64bit.tar.gz -C $GAUSSHOME --strip-components=1

启动数据库进行功能验证
```
gs_ctl start -D $PGDATA
```

注意：

MogDB 5.0.6新增并行导入导出功能（详见逻辑备份恢复效率增强），该功能依赖于新增内置插件tidrangescan。升级完成后，如需使用gs_dump、gs_restore并行导入导出功能，需在要进行导入导出的库里手动创建tidrangescan插件：
create extension tidrangescan;

升级回滚

使用临时升级操作无需进行额外的提交动作，如果启动后检查发现有异常，可通过原有的备份文件恢复到升级前状态。

cp -r /home/omm/mogdb_app_bak/*  $GAUSSHOME/*
rm -r $PGDATA
mv /home/omm/mogdb_data_bak  $PGDATA

注意事项

在执行以上升级操作的过程中，如果发现未能按照预期正常进行，例如替换新版本后，数据库启动异常等，需要联系原厂工程师进行解决。

请确保在升级之前进行原数据库文件的备份，在升级过程中如果遇到任何问题，先通过备份进行恢复，然后联系原厂工程师提供支持。

灰度升级

灰度升级不同于前面的升级方式，不需要将所有节点全部停机，升级后重新启动，而是可以实现对外服务的同时进行升级操作。

升级前检查

请在对以下所有内容进行充分检查和了解后再进行升级操作。在升级过程中如遇到任何问题，及时联系原厂工程师进行处理。

收集节点信息

联系数据库系统管理员，获取数据库涉及节点的节点名称、节点IP地址。节点的root、omm用户密码等环境信息，设置root用户远程登录。
备份数据

升级一旦失败，有可能会影响到业务的正常开展。提前备份数据，就可以在风险发生后，尽快的恢复业务。
获取升级包

访问MogDB官网下载页面获取想要升级的升级包。
检查数据库节点磁盘使用率

建议数据库节点磁盘使用率低于80%时再执行升级操作。

注意事项：

在灰度升级方式中，升级版本之间一定不能有元数据的变动，需确保满足该条件，才可进行灰度升级。

灰度升级必须是对包含主备的集群进行升级。

备份数据

采用灰度升级方式时，在升级前，请务必手动完成备份，具体操作示例如下：

备份原版本可执行文件

mkdir -p /home/omm/mogdb_app_bak
cp -r $GAUSSHOME/* /home/omm/mogdb_app_bak/*

备份用户数据

mkdir /home/omm/mogdb_data_bak
gs_basebackup -D /home/omm/mogdb_data_bak -h 127.0.0.1 -p 26000

需根据实际情况替换主机名、端口号。

升级步骤

灰度升级的具体操作步骤如下：

关闭备机
```
gs_ctl stop -D $PGDATA
```

升级备机，解压新版本的压缩包覆盖备机的app文件夹，例如：

tar -xvf MogDB-5.0.6-Kylin-x86_64-all.tar.gz
cd MogDB-5.0.6-Kylin-x86_64-all
tar -xvf MogDB-5.0.6-Kylin-64bit.tar.gz -C $GAUSSHOME --strip-components=1

启动备机
```
gs_ctl start -D $PGDATA -M standby
```
在备机上执行以下命令，进行主备机器切换
```
gs_ctl switchover -D $PGDATA
```
关闭原主机
```
gs_ctl stop -D $PGDATA
```

升级原主机，解压新版本的压缩包覆盖备机的app文件夹，例如：

tar -xvf MogDB-5.0.6-Kylin-x86_64-all.tar.gz
cd MogDB-5.0.6-Kylin-x86_64-all
tar -xvf MogDB-5.0.6-Kylin-64bit.tar.gz -C $GAUSSHOME --strip-components=1

以备机模式启动原主机
```
gs_ctl start -D $PGDATA -M standby
```
查询集群状态
```
gs_om -t status --detail
```
升级版本查询
```
mogdb --version
```
升级后功能验证

对新版本包含的bug fix或者功能进行验证

注意：

MogDB 5.0.6新增并行导入导出功能（详见逻辑备份恢复效率增强），该功能依赖于新增内置插件tidrangescan。升级完成后，如需使用gs_dump、gs_restore并行导入导出功能，需在要进行导入导出的库里手动创建tidrangescan插件：
create extension tidrangescan;

升级回滚

使用灰度升级操作无需进行额外的提交动作，如果启动后检查发现有异常，可通过原有的备份文件将主备节点都恢复到升级前状态。

cp -r /home/omm/mogdb_app_bak/*  $GAUSSHOME/*
rm -r $PGDATA
mv /home/omm/mogdb_data_bak  $PGDATA

注意事项

灰度升级会存在不同版本的主备同时运行的场景，因此在使用灰度升级时应确保新旧版本之间不存在元数据和日志文件格式的变更。

请提前做好数据备份，在遇到问题时可以回退到升级前状态，然后将遇到的问题反馈给原厂工程师。

反馈