1. 前言

本文档为恒生电子企业级数据库 LightDB-X 升级手册，主要介绍了升级 LightDB-X 的步骤及方法。LightDB-X 的每次迭代都会引入不同的新特性，新特性的引入可能会导致系统表的变化。因此 LightDB-X 提供了三种不同的升级方式，以应对不同特性的版本迭代。

  1. 复用实例目录：

    • 如果 LightDB-X 某次的版本迭代未导致系统表的修改，那么只需要安装新版本的 LightDB-X，复用原来的实例目录即可。

    • 目前 LightDB-X 支持直接复用实例目录的版本包括：

      Old version

      New version

      13.8-23.1

      13.8-23.2

  2. 使用 lt_upgrade 进行升级：

    • lt_upgrade 是 LightDB-X 的标准升级工具，用于将存储在 LightDB-X 数据文件中的数据升级到新版本（比如从 22.1 升级到 22.2），LightDB-X 从 23.3 开始支持跨版本升级，支持将 22.3 以及之后的任意版本升级到最新版本的 LightDB。

    • LightDB-X 的发行版本通常会加入新的特性，这些新特性可能会修改系统表，但是内部数据存储格式很少会改变。 lt_upgrade 正是基于这一点实现了快速升级，它会创建新的系统表，但复用了旧的用户磁盘数据文件。因此如果某个 LightDB-X 的主发行版本更改了数据存储格式，导致无法读取旧的数据格式，则无法使用 lt_upgrade 进行升级，不过 LightDB-X 会尽力避免这种情况。

    • 在升级之前需要为当前版本的数据库安装适合该版本的所有 PATCH，目前需要安装补丁的版本包括 13.8-22.3 和 13.8-22.4（补丁包可通过官网下载）：

      • 13.8-22.3 需要安装的补丁包括：

        Patch package name

        lightdb-x-13.8-22.3-el8.x86_64-patch-5.0-8131.zip

        lightdb-x-13.8-22.3-el8.x86_64-patch-7.0-8271.zip

        lightdb-x-13.8-22.3-el8.x86_64-patch-8.0-8464.zip

        lightdb-x-13.8-22.3-el8.x86_64-patch-9.0-8623.zip

        lightdb-13.8-22.3-generic-patch-10.0-8737.zip

      • 13.8-22.4 需要安装的补丁包括：

        Patch package name

        lightdb-x-13.8-22.4-generic-patch-2.0-8964.zip

        lightdb-x-13.8-22.4-el8.x86_64-patch-3.0-9984.zip

  3. 通过 lt_dump 和 lt_restore 进行升级；

    • 在无法通过前两种升级方式升级数据库的情况下，可以考虑通过逻辑备份恢复的方式实现数据库的升级；

2. 单机版升级复用实例目录

2.1. 检查旧实例

在进一步升级数据库之前，需要首选确保当前数据库运行正常。如果数据库处于异常状态，则需要先进行处理。

  • 阻止所有应用程序访问当前数据库实例。

2.2. 停止旧实例

使用如下命令停止当前数据库服务：

lt_ctl stop -D /home/lightdb/lightdb-23.1/lightdb-x/13.3-23.1/data/defaultCluster

2.3. 安装新版本单机 LightDB-X

  • 获取新版数据库安装包，进行解压。

  • 安装新版本数据库（具体步骤可参考 LightDB-X 安装手册），需要额外注意以下几点：

    • 安装参数中安装路径不能和旧版一样，其他参数和旧版保持一致。

    • 安装程序会提示用户选择安装模式，有三个选项：

      • 选项一：仅安装数据库， 此处必须要选择该选项 。

      • 选项二：除了安装数据库外，还会生成默认的实例目录并启动。

      • 选项三：为开发者模式。

  • 确保 LTHOME 环境变量已经指向新的目录，而 LTDATA 环境变量保持不变（如果需要改变新实例的 LTDATA 目录，也可以考虑将旧的 LTDATA 目录拷贝到新位置，并保证 LTDATA 指向的是新位置）。

2.4. 启动新数据库实例

  • 启动数据库：

    lt_ctl start -D /home/lightdb/lightdb-23.1/lightdb-x/13.3-23.1/data/defaultCluster

  • 升级数据库插件版本：

    所有的数据库插件都需要手动升级，升级方式参考后续内容「特定版本升级说明」；

  • 检查数据，插件，定时任务是否完整迁移。

3. 高可用升级复用实例目录

3.1. 检查旧实例

在进一步升级数据库之前，需要首选确保当前数据库运行正常。如果数据库处于异常状态，则需要先进行处理。

  • 检测集群状态：

    • 在主节点或从节点执行如下命令，确认展示信息中没有 WARNING 且 Status 和 Upstream 字段没有出现 ? 和 ! 符号，示例结果：

      ltcluster -f $LTDATA/../etc/ltcluster/ltcluster.conf cluster show


ID | Name     | Role    | Status    | Upstream| Location | Priority | Timeline | Connection string
----+---------+---------+-----------+---------+----------+----------+----------+--------------------------------
 1  | node199 | primary | * running |         | default  | 100      | 1        |
 2  | node193 | standby |   running | node199 | default  | 100      | 1        |

    • 在各个节点执行如下命令，确保展示的各个检查项的均为 OK ，示例结果：

      ltcluster -f $LTDATA/../etc/ltcluster/ltcluster.conf node check


Node "node193":
Server role: OK (node is standby)
Replication lag: OK (0 seconds)
WAL archiving: OK (0 pending archive ready files)
Upstream connection: OK (node "node193" (ID: 2) is attached to expected upstream node "node199" (ID: 1))
Downstream servers: OK (this node has no downstream nodes)
Replication slots: OK (node has no physical replication slots)
Missing physical replication slots: OK (node has no missing physical replication slots)
Configured data directory: OK (configured "data_directory" is "/data1/data5432")

  • 阻止所有应用程序访问当前数据库实例。

3.2. 停止旧实例

  • 确保 LTHOME 和 LTDATA 环境变量指向旧实例。

  • 使用一键启停脚本停止当前数据库服务：

    lightdb_service.py -c stop

    如果实例未使用 Keepalived，则需要额外指定 --ignore-keepalived 选项。

3.3. 安装新版本高可用 LightDB-X

  • 获取新版数据库安装包，进行解压（只需要在主服务器上解压即可）。

  • 安装新版本数据库（具体步骤可参考 LightDB-X 安装手册），需要额外注意以下几点：

    • 安装参数中安装路径和实例路径不能和旧版一样，其他参数和旧版保持一致。

    • 安装程序会提示用户选择安装模式，有三个选项：

      • 选项一：仅安装数据库 。

      • 选项二：除了安装数据库外，还会生成默认的实例目录并启动 此处必须要选择该选项 。

      • 选项三：为开发者模式。

  • 确保 LTHOME 和 LTDATA 环境变量已经指向新库。

  • 使用一键启停脚本停止新数据库服务：

    lightdb_service.py -c stop

    如果实例未使用 Keepalived，则需要额外指定 --ignore-keepalived 选项。

3.4. 替换实例目录

  • 删除新数据库的实例目录（实例目录是安装时指定的，是 LTDATA 目录的上层目录，具体细节可参考 LightDB-X 安装手册）；

  • 拷贝旧数据库的实例目录到新库的实例目录；

  • 主机和所有备机都需要执行上述操作；

3.5. 启动新数据库实例

  • 使用一键启停脚本启动新数据库服务：

    lightdb_service.py -c start

    如果实例未使用 Keepalived，则需要额外指定 --ignore-keepalived 选项。

  • 升级数据库插件版本：

    所有的数据库插件都需要手动升级，升级方式参考后续内容「特定版本升级说明」；

  • 检查数据，插件，定时任务是否完整迁移。

4. 使用 lt_upgrade 升级单机版

4.1. 安装 PATCH

在升级之前需要为当前版本的数据库安装适合该版本的所有 PATCH；

4.2. 检查旧实例

在进一步升级数据库之前，需要首选确保当前数据库运行正常。如果数据库处于异常状态，则需要先进行处理。

  • 记录当前数据库的安装目录，实例目录、端口号 和 密码。

  • 记录当前数据库 WAL 日志的分片大小：

    lightdb@postgres=# show wal_segment_size ;
 wal_segment_size
------------------
 512MB
(1 row)

  • 阻止所有应用程序访问当前数据库实例。

  • 检查 LTDATA 目录的容量，确认服务器磁盘空闲空间是否大于该目录的大小，因为 lt_upgrade 升级时需要对其中部分文件进行拷贝。

4.3. 停止旧实例

使用如下命令停止当前数据库服务：

lt_ctl stop -D /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster

4.4. 安装新版本单机 LightDB-X

  • 获取新版数据库安装包，进行解压。

  • 安装新版本数据库（具体步骤可参考 LightDB-X 安装手册），需要额外注意以下几点：

    • 安装参数中安装路径和实例路径不能和旧版一样，其他参数和旧版保持一致。

    • 安装程序会提示用户选择安装模式，有三个选项：

      • 选项一：仅安装数据库， 此处必须要选择该选项 。

      • 选项二：除了安装数据库外，还会生成默认的实例目录并启动。

      • 选项三：为开发者模式。

  • 确保 LTHOME 和 LTDATA 环境变量已经指向新库。

4.5. 创建新实例

  • 执行以下命令，创建新的实例目录：

    lt_initdb -p 5432 --wal-segsize=512 --compatible-type=oracle --upgrade-mode

    • 示例 -p 5432 表示指定新库的端口号为 5432，用户实际升级时可自行指定，通常保持和旧库一致即可。

    • 示例 –wal-segsize=512 用于指定 wal 日志分片的大小（单位为 MB），确保和旧库一致即可。

    • 示例 –compatible-type=oracle 表示新库的语法兼容模式为 oracle，用户实际升级时可自行指定，通常保持和旧库一致即可。

    • 示例 –upgrade-mode 是专门用于升级的选项，表示不创建扩展插件，因为该工作后续会由 lt_upgrade 完成。

  • 使用如下命令启动新数据库服务，并确认新安装的库运行正常：

    lt_ctl start -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

  • 使用如下命令停止新数据库服务：

    lt_ctl stop -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

4.6. lt_upgrade 检测

在执行真正的升级前强烈建议使用 lt_upgrade_check 进行校验（lt_upgrade_check 是 LightDB 开发的升级兼容性检查工具），检查 lt_upgrade 是否支持本次升级。如果 check 不通过，则先处理异常。若无法处理，则表示 lt_upgrade 不支持本次升级（考虑使用 lt_dump 和 lt_dumpall 进行升级）。

lt_upgrade_check 的详细用法可以参考其手册说明，参考如下命令：

lt_upgrade_check -b /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/bin \
       -B /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/bin \
       -d /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster \
       -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

4.7. lt_upgrade 升级

执行如下命令进行升级：

export PGDATAOLD=/home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster
export PGDATANEW=/home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster
export PGBINOLD=/home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/bin
export PGBINNEW=/home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/bin
${PGBINNEW}/lt_upgrade

也可以通过 lt_upgrade 的 -b、-B、-d、-D 选项指定 旧/新程序目录 和 旧/新数据目录 ，从而不必设置环境变量（不过需要确保使用的是新版本 lt_upgrade ）：

lt_upgrade -b /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/bin \
       -B /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/bin \
       -d /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster \
       -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

4.8. 启动新数据库实例

  • 启动数据库：

    lt_ctl start -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

  • 升级用户数据库插件版本：

    用户创建的数据库插件需要手动升级，如需升级可执行如下命令（其中 update_extensions.sql 是在 lt_upgrade 成功升级后自动生成的，文件位于执行 lt_upgrade 时所在的目录）：

    ltsql -p 5432 -f update_extensions.sql

  • 检查数据，插件，定时任务是否完整迁移。

5. 使用 lt_upgrade 升级高可用

5.1. 安装 PATCH

在升级之前需要为当前版本的数据库安装适合该版本的所有 PATCH（所有节点都需要安装 PATCH）；

5.2. 检查旧实例

在进一步升级数据库之前，需要首选确保当前数据库运行正常。如果数据库处于异常状态，则需要先进行处理。

  • 检测集群状态：

    • 在主节点或从节点执行如下命令，确认展示信息中没有 WARNING 且 Status 和 Upstream 字段没有出现 ? 和 ! 符号，示例结果：

      ltcluster -f $LTDATA/../etc/ltcluster/ltcluster.conf cluster show


ID | Name     | Role    | Status    | Upstream| Location | Priority | Timeline | Connection string
----+---------+---------+-----------+---------+----------+----------+----------+--------------------------------
 1  | node199 | primary | * running |         | default  | 100      | 1        |
 2  | node193 | standby |   running | node199 | default  | 100      | 1        |

    • 在各个节点执行如下命令，确保展示的各个检查项的均为 OK ，示例结果：

      ltcluster -f $LTDATA/../etc/ltcluster/ltcluster.conf node check


Node "node193":
Server role: OK (node is standby)
Replication lag: OK (0 seconds)
WAL archiving: OK (0 pending archive ready files)
Upstream connection: OK (node "node193" (ID: 2) is attached to expected upstream node "node199" (ID: 1))
Downstream servers: OK (this node has no downstream nodes)
Replication slots: OK (node has no physical replication slots)
Missing physical replication slots: OK (node has no missing physical replication slots)
Configured data directory: OK (configured "data_directory" is "/data1/data5432")

  • 记录当前数据库的安装目录，实例目录、端口号 和 密码。

  • 阻止所有应用程序访问当前数据库实例。

  • 检查主机和所有备机 LTDATA 目录的容量，确认服务器磁盘空闲空间是否大于该目录的大小，因为 lt_upgrade 升级时需要对其中部分文件进行拷贝。

5.3. 停止旧实例

  • 确保 LTHOME 和 LTDATA 环境变量指向旧实例。

  • 使用一键启停脚本停止当前数据库服务：

    lightdb_service.py -c stop

    如果实例未使用 Keepalived，则需要额外指定 --ignore-keepalived 选项。

5.4. 安装新版本高可用 LightDB-X

  • 获取新版数据库安装包，进行解压（只需要在主服务器上解压即可）。

  • 先清空如下 3 个脚本的内容：

    cd script/

cp 8_lightdb_create_extension.sh 8_lightdb_create_extension.sh.bk
cp 8.1_create_lt_probackup.sh 8.1_create_lt_probackup.sh.bk

cat /dev/null > 8_lightdb_create_extension.sh
cat /dev/null > 8.1_create_lt_probackup.sh

cd ../lightdb-x/13.8-23.2/scripts/

cp 8_lightdb_create_extension.sh 8_lightdb_create_extension.sh.bk
cat /dev/null > 8_lightdb_create_extension.sh

  • 安装新版本数据库（具体步骤可参考 LightDB-X 安装手册），需要额外注意以下几点：

    • 安装参数中安装路径和实例路径不能和旧版一样，其他参数和旧版保持一致。

    • 安装程序会提示用户选择安装模式，有三个选项：

      • 选项一：仅安装数据库 。

      • 选项二：除了安装数据库外，还会生成默认的实例目录并启动 此处必须要选择该选项 。

      • 选项三：为开发者模式。

  • 确保新的集群状态健康，命令参考先前内容「检查旧实例」。

  • 确保 LTHOME 和 LTDATA 环境变量已经指向新库。

  • 使用一键启停脚本停止新数据库服务：

    lightdb_service.py -c stop

    如果实例未使用 Keepalived，则需要额外指定 --ignore-keepalived 选项。

5.5. lt_upgrade 检测

在执行真正的升级前强烈建议使用 lt_upgrade_check 进行校验（lt_upgrade_check 是 LightDB 开发的升级兼容性检查工具），检查 lt_upgrade 是否支持本次升级。如果 check 不通过，则先处理异常。若无法处理，则表示 lt_upgrade 不支持本次升级（考虑使用 lt_dump 和 lt_dumpall 进行升级）。

lt_upgrade_check 的详细用法可以参考其手册说明，参考如下命令：

lt_upgrade_check -b /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/bin \
       -B /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/bin \
       -d /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster \
       -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

注意：只需要在主机上执行上述步骤即可 。

5.6. lt_upgrade 升级

执行如下命令进行升级：

export PGDATAOLD=/home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster
export PGDATANEW=/home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster
export PGBINOLD=/home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/bin
export PGBINNEW=/home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/bin
${PGBINNEW}/lt_upgrade

也可以通过 lt_upgrade 的 -b、-B、-d、-D 选项指定 旧/新程序目录 和 旧/新数据目录 ，从而不必设置环境变量（不过需要确保使用的是新版本 lt_upgrade ）：

lt_upgrade -b /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/bin \
       -B /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/bin \
       -d /home/lightdb/lightdb-21.3/lightdb-x/13.3-21.3/data/defaultCluster \
       -D /home/lightdb/lightdb-22.1/lightdb-x/13.3-22.1/data/defaultCluster

注意：只需要在主机上执行上述步骤即可 。

5.7. 启动新数据库实例

  • 使用一键启停脚本启动新数据库服务：

    lightdb_service.py -c start

    如果实例未使用 Keepalived，则需要额外指定 --ignore-keepalived 选项。

  • 克隆主库到备库：

    • 确保备库上 LTHOME 和 LTDATA 环境变量已经指向新库。

    • 在备库上执行如下命令停止备库：

      lt_ctl -D $LTDATA stop

    • 清空备库的数据目录：

      cd $LTDATA
rm -rf *

    • 从主库克隆：

      ltcluster -h new_primary_host -p new_primary_port -U ltcluster -d ltcluster \
          -f $LTDATA/../etc/ltcluster/ltcluster.conf standby clone -F

      其中 new_primary_host 为主库的 IP 地址，new_primary_port 为主库的端口号；

    • 重新启动备库：

      lt_ctl -D $LTDATA start

    • 备库重新注册为 standby：

      ltcluster -f $LTDATA/../etc/ltcluster/ltcluster.conf standby register -F

    注意：如果有多个备机，则每个备机都需要执行上述步骤 。

  • 升级用户数据库插件版本：

    用户创建的数据库插件需要手动升级，如需升级可在主库上执行如下命令（其中 update_extensions.sql 是在 lt_upgrade 成功升级后自动生成的，文件位于执行 lt_upgrade 时所在的目录）：

    ltsql -p 5432 -f update_extensions.sql

  • 检查数据，插件，定时任务是否完整迁移。

6. 特定版本升级说明

6.1. 13.8-23.1 升级到 13.8-23.2

  • 13.8-23.2 版本的 LightDB-X 可以直接复用 13.8-23.1 的数据目录；

  • 复用数据目录不会自动更新插件版本，需要手动升级，相对于 13.8-23.1 而言，13.8-23.2 升级了如下插件：

    Extension

    Old version

    New version

    lt_stat_activity

    1.1

    1.2

    ltfce

    1.1

    1.2

    myfce

    1.2

    1.4

    orafce

    3.22

    3.23

    lt_profile

    0.3.6

    0.3.7

    如需升级可在新库的 ltsql 中执行如下命令（注意：除 template0 以外的每个数据库都需要执行，以 lt_test 库为例）

    \connect lt_test
ALTER EXTENSION "lt_stat_activity" UPDATE;
ALTER EXTENSION "ltfce" UPDATE;
ALTER EXTENSION "myfce" UPDATE;
ALTER EXTENSION "orafce" UPDATE;

    postgres 库需要额外升级 lt_profile 插件：

    ALTER EXTENSION "lt_profile" UPDATE;

7. FAQ

  1. 升级时提示 : There seems to be a postmaster servicing the old cluster.

    解决方法 ：停止旧库的 lightdb 进程。

  2. 升级时提示：The source cluster was not shut down cleanly.

    解决方法 ：主服务器没有干净停止，正常启动后，再尝试正常停止，不要强制 kill 数据库。

  3. 升级时提示： libpq environment variable PGHOST has a non-local server value.

    解决办法 ：unset PGHOST 和 LTHOST 即可。

  4. 升级时提示：undefined symbol: PQlightdbserverVersion.

    解决办法 ：检查环境变量 PGHOME 和 LD_LIBRARY_PATH 的配置，保证优先查找新版本程序。

  5. 升级时提示：lc_collate values for database “postgres” do not match: old “en_US.utf8”, new “zh_CN.UTF-8”

    解决办法 ：将环境变量 LANG 的值设置为和旧实例的一致，比如：

    export LANG="en_US.UTF-8"

  6. 升级时提示：Only the install user can be defined in the new cluster.

    解决办法 ：新版本的数据库中存在除 lightdb 以外的角色，需要重新 lt_initdb（参考“创建新实例”的相关描述）；

  7. 升级时提示：old cluster uses data checksums but the new one does not

    解决办法 ：保证新老实例的 data checksum 一致，需要重新 lt_initdb 并通过 -k 选项开启该特性（参考“创建新实例”的相关描述）