KingbaseES V9R2 单机环境升级实施指南：基于 sys_upgrade 的完整实践KingbaseES V9

KingbaseES V9R2 单机环境升级实施指南：基于 sys_upgrade 的完整实践

前言

KingbaseES V9R2 系列作为金仓数据库的重要版本，持续通过小版本迭代修复问题、优化性能并增强功能。其中，V9R2C14 版本引入了读写分离智能路由、FastPath 锁优化及增强的数据安全策略，对于使用 V9R2 系列的用户而言，升级至最新版本是获取这些改进的直接途径。

本文档基于 V009R002C013 升级至 V009R002C014 的实际测试环境，详细复盘了使用 sys_upgrade 工具进行单机版升级的完整流程。内容涵盖工具原理、升级模式选择、前置参数检查、执行步骤、常见问题处理及回退方案。旨在为 DBA 提供一份逻辑清晰、可落地执行的标准化操作指南，确保升级过程安全、可控。

一、sys_upgrade 工具概述

1.1 工具定位

sys_upgrade 是 KingbaseES 官方提供的版本升级工具，其设计目标是在不进行数据转储（dump）的前提下，完成数据库版本的就地升级。通过升级系统目录元数据，使新版本的服务进程能够兼容并访问旧版本的数据文件，从而将升级停机时间从数小时缩短至分钟级。

1.2 工作原理

理解 sys_upgrade 的工作原理，有助于正确执行升级操作并预判可能的风险。其核心机制是升级系统目录元数据，而非迁移用户数据：

┌─────────────────────────────────────────────────────────────────────────────┐
│                         sys_upgrade 工作原理                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   旧数据目录                              新数据目录                         │
│   ┌─────────────────────┐                ┌─────────────────────┐            │
│   │  sys_catalog (C13)  │                │  sys_catalog (C14)  │            │
│   │  · 系统表结构       │                │  · 全新创建的结构   │            │
│   │  · 元数据（源）     │  ──提取转换─▶  │  · 升级后的元数据   │            │
│   ├─────────────────────┤                ├─────────────────────┤            │
│   │  user_data          │                │  user_data          │            │
│   │  · 表/索引文件      │  ──硬链接/拷贝─▶│  · 复用物理文件     │            │
│   │  · 物理存储         │                │  · 二进制兼容       │            │
│   └─────────────────────┘                └─────────────────────┘            │
│                                                                             │
│   本质：1. 重建系统表 2. 转换元数据 3. 复用数据文件                          │
└─────────────────────────────────────────────────────────────────────────────┘

工作流程说明：

兼容性验证：检查新旧集群的二进制兼容性
停止服务：确保两个集群都处于停止状态
分析差异：识别系统表结构变化
创建新系统表：在新目录中初始化新版本的系统表
复用数据文件：通过硬链接或拷贝复用用户数据文件
转换导入元数据：从旧系统表提取元数据，转换后导入新系统表
更新文件映射：在新系统表中建立到复用文件的正确引用
生成后处理脚本：创建统计信息更新等脚本

核心理解：用户数据（表、索引等）文件在物理层面保持不变，sys_upgrade 通过升级系统表结构，使新版本的服务进程能够正确读取这些文件。这也是为什么 sys_upgrade 能够实现快速升级的本质原因。

1.3 关键限制

使用 sys_upgrade 前，需了解以下限制：

限制类型	说明
平台限制	仅支持 Linux，不支持 Windows
数据类型限制	用户表中严禁包含 regproc、regprocedure、regoper、regoperator、regconfig、regnamespace、regdictionary 等 OID 依赖类型（regtype、regclass、regrole 可正常升级）
文件系统要求	使用链接模式（`-k`）时，新旧数据目录必须在同一文件系统

1.4 升级模式对比

sys_upgrade 提供三种升级模式，可根据磁盘空间和安全需求选择：

模式	命令参数	特点	回退风险	适用场景
拷贝模式	(默认)	物理复制文件，新旧库完全独立	✅ 低（旧库独立存在）	首次升级、重要生产库
链接模式	`-k`	创建硬链接，几乎不占额外空间	⚠️ 高（启动新库后旧库不可用）。如需保留旧库，可在升级前复制旧集簇副本，在副本上执行链接模式升级	大数据库、磁盘空间紧张
克隆模式	`--clone`	文件系统级写时复制（CoW）	✅ 低（CoW技术）	支持 reflink 的文件系统（XFS/Btrfs）

推荐：对于生产环境，建议优先使用拷贝模式，确保旧库独立可回退。

1.5 支持的升级路径

sys_upgrade 支持以下版本升级至当前版本：

已发布的 KingbaseES（Oracle 兼容版）历史版本（如 V009R002C013、V009R002C012、V009R002C010）
KingbaseES V009R001C010（Oracle 兼容模式）

二、升级前准备

2.0 环境信息确认

本文档基于以下测试环境编写，请根据实际环境调整路径：

项目	值	说明
操作系统	Red Hat 7.9	Linux 环境
旧版本	V009R002C013	当前生产版本
旧安装目录	`/opt/Kingbase/ES/V9`	保持不变
旧数据目录	`/kdb/data`	当前生产数据
新安装目录	`/opt/Kingbase/ES/V9R2C14`	升级目标版本
新数据目录	`/kdb/data_V9R2C14`	升级目标数据
归档目录	`/kdb/arclog`	WAL 日志归档位置
备份目录	`/kdb/backup`	备份文件存放位置
监听端口	54321	数据库服务端口
环境语言	`zh_CN.UTF-8`	根据当前环境设置

2.1 核心参数检查

sys_upgrade 升级的是整个数据簇，新库初始化参数必须与旧库全局严格一致。

说明：同一实例下的所有数据库共享兼容模式、编码、区域设置及大小写敏感配置，只需查询任意一个库即可代表全实例。

-- 连接数据库，记录关键参数
SELECT version();
SHOW database_mode;              -- 兼容模式 (oracle/pg)
SHOW server_encoding;            -- 字符编码 (UTF8/GBK)
SHOW lc_ctype;                   -- 区域设置
SHOW block_size;                 -- 块大小 (通常为 8192)
SHOW segment_size;               -- 段大小 (通常为 1GB)
SHOW wal_segment_size;           -- WAL段大小 (通常为 16MB)
SHOW enable_ci;                  -- 大小写敏感 (off/on)
SHOW data_checksums;             -- 数据校验和 (off/on)
SHOW max_connections;            -- 最大连接数
SHOW shared_buffers;             -- 共享缓冲区大小
SHOW timezone;                   -- 时区
SHOW data_directory;             -- 数据目录路径
SHOW port;                       -- 端口号

# 记录已安装扩展（用于升级后对比）
ksql -U system -d test -c "SELECT extname, extversion FROM sys_extension ORDER BY extname;" > /kdb/backup/extensions_before.txt

2.2 兼容性深度检查

2.2.1 reg* 类型检查

** 阻断项**：用户表中若包含 reg* 类型字段，升级将失败。

-- 检查用户表中是否存在不兼容的 reg* 类型
SELECT 
    n.nspname AS schema_name,
    c.relname AS table_name,
    a.attname AS column_name,
    t.typname AS data_type
FROM sys_class c
JOIN sys_namespace n ON c.relnamespace = n.oid
JOIN sys_attribute a ON c.oid = a.attrelid
JOIN sys_type t ON a.atttypid = t.oid
WHERE t.typname IN ('regproc', 'regprocedure', 'regoper', 'regoperator', 
                    'regconfig', 'regnamespace', 'regdictionary')
  AND c.relkind = 'r'
  AND n.nspname NOT IN ('sys_catalog', 'information_schema', 'pg_catalog', 'sys_toast', 'sys_temp')
  AND n.nspname NOT LIKE 'sys_%'
  AND n.nspname NOT LIKE 'pg_%';

2.2.2 表空间检查

-- 记录自定义表空间信息（如有）
SELECT spcname, oid, sys_tablespace_location(oid) AS location
FROM sys_tablespace 
WHERE spcname NOT LIKE 'sys%';

2.2.3 事务状态检查

-- 检查长事务
SELECT pid, state, now() - xact_start AS duration, query 
FROM sys_stat_activity 
WHERE xact_start IS NOT NULL AND now() - xact_start > interval '1 hour';

-- 检查预备事务
SELECT * FROM sys_prepared_xacts;

2.3 数据备份

** 推荐**：物理冷备份是最可靠的回退方案。

# 停止数据库
sys_ctl -D /kdb/data stop -m fast

# 物理全量备份（包含所有配置文件和用户数据）
BACKUP_DIR="/kdb/backup/data_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
rsync -av --delete /kdb/data/ "$BACKUP_DIR/"

# 验证备份
sys_controldata -D "$BACKUP_DIR" | grep "数据库簇状态"

说明：上述 rsync 命令已完整备份整个数据目录，包括 kingbase.conf、sys_hba.conf、kingbase.auto.conf、sys_ident.conf 等所有配置文件，无需单独备份。

2.4 环境配置调整

# ==================== 归档处理 ====================
# 重要：关闭归档前，必须确保所有WAL日志已归档

# 1. 手动切换WAL日志，触发归档（执行2-3次）
ksql -U system -d test -c "SELECT sys_switch_wal();"
ksql -U system -d test -c "SELECT sys_switch_wal();"
sleep 2

# 2. 检查归档目录，确认最后一个WAL段已归档
ls -lt /kdb/arclog/ | head -5

# 3. 记录当前归档配置值（用于升级后恢复）
grep -E "^archive_(mode|command|timeout)" /kdb/data/kingbase.conf > /kdb/backup/archive_config.txt

# 4. 关闭归档
sed -i 's/^archive_mode = on/archive_mode = off/' /kdb/data/kingbase.conf

# 5. 重新启动数据库服务
sys_ctl -D /kdb/data restart

# 6. 确认归档已关闭
ksql -U system -d test -c "SHOW archive_mode;"
# 预期输出：off

# ==================== 认证简化 ====================
# 临时改为 trust 认证，避免升级过程中密码验证失败
sed -i 's/scram-sha-256/trust/g' /kdb/data/sys_hba.conf
sed -i 's/md5/trust/g' /kdb/data/sys_hba.conf

# 重新加载认证配置
sys_ctl -D /kdb/data reload

2.5 升级前检查清单

类别	检查项	命令/方法	状态
参数一致性	兼容模式	`SHOW database_mode;`	☐
	字符编码	`SHOW server_encoding;`	☐
	区域设置	`SHOW lc_ctype;`	☐
	块大小	`SHOW block_size;`	☐
	大小写敏感	`SHOW enable_ci;`	☐
	WAL段大小	`SHOW wal_segment_size;`	☐
	数据校验和	`SHOW data_checksums;`	☐
	段大小	`SHOW segment_size;`	☐
	最大连接数	`SHOW max_connections;`	☐
	时区	`SHOW timezone;`	☐
归档配置	归档配置已记录	`cat /kdb/backup/archive_config.txt`	☐
	WAL已完整归档	`ls -lt /kdb/arclog/ \| head -5`	☐
兼容性	reg*类型检查	执行2.2.1节SQL（返回空）	☐
	无长事务/预备事务	执行2.2.3节SQL（返回空）	☐
数据备份	物理备份完成	`ls -la /kdb/backup/data_*`	☐
	扩展版本已记录	`ls -la /kdb/backup/extensions_before.txt`	☐
磁盘空间	新数据目录空间	`df -h $NEW_DATA_DIR`（≥旧目录2倍）	☐
	临时目录空间	`df -h /tmp`（≥旧目录大小）	☐
服务状态	旧数据库已停止	`sys_ctl -D $OLD_DATA_DIR status`	☐
	无残留 kingbase 进程	`ps aux \| grep kingbase \| grep -v grep`	☐
连接测试	旧库本地连接正常	`ksql -U system -d test -c "SELECT 1;"`	☐
文件权限	运行用户一致	`ls -ld $OLD_DATA_DIR \| awk '{print $3}'`	☐

提示：建议逐项确认后勾选，确保升级前所有检查项均满足要求。

三、新版本安装与初始化

3.1 定义路径变量

# 定义新旧版本路径变量（举例）
export OLD_INSTALL_DIR=/opt/Kingbase/ES/V9
export OLD_DATA_DIR=/kdb/data
export NEW_INSTALL_DIR=/opt/Kingbase/ES/V9R2C14
export NEW_DATA_DIR=/kdb/data_V9R2C14

3.2 安装新版本

# 创建安装目录
mkdir -p $NEW_INSTALL_DIR

# 解压安装（根据实际安装包格式调整）
cd /opt/Kingbase/ES
tar -xzf /tmp/KingbaseES_V009R002C014_Lin64_install.tar.gz -C $NEW_INSTALL_DIR
...
# 验证安装
$NEW_INSTALL_DIR/Server/bin/ksql -V

3.3 初始化新数据目录

** 关键**：参数必须与 2.1 节记录的值完全一致。

# 根据 2.1 节检查结果执行初始化
$NEW_INSTALL_DIR/Server/bin/initdb \
  -U system \
  -W \                     # 提示输入密码
  -m oracle \              # 根据 2.1 节记录的值
  -E UTF8 \                # 根据 2.1 节记录的值
  --lc-ctype=zh_CN.UTF-8 \ # 根据 2.1 节记录的值
  -D $NEW_DATA_DIR \
  --wal-segsize=16         # 根据 2.1 节记录的值
  # 注意：data_checksums=off 时不加 --data-checksums
  # 注意：enable_ci=off 时不加 --enable-ci

3.4 拷贝配置文件

重要：将旧版本配置文件拷贝至新数据目录，确保参数设置与旧版本一致。

# 拷贝旧版本配置文件到新数据目录
cp $OLD_DATA_DIR/kingbase.conf $NEW_DATA_DIR/          # 主配置文件
cp $OLD_DATA_DIR/sys_hba.conf $NEW_DATA_DIR/           # 认证配置
cp $OLD_DATA_DIR/kingbase.auto.conf $NEW_DATA_DIR/ 2>/dev/null || true  # 动态配置（如有）
cp $OLD_DATA_DIR/sys_ident.conf $NEW_DATA_DIR/ 2>/dev/null || true      # ident配置（按需）

# 修改配置文件中的路径（指向新数据目录）
sed -i "s|$OLD_DATA_DIR|$NEW_DATA_DIR|g" $NEW_DATA_DIR/kingbase.conf
sed -i "s|$OLD_DATA_DIR|$NEW_DATA_DIR|g" $NEW_DATA_DIR/kingbase.auto.conf 2>/dev/null || true

# 临时关闭归档和简化认证
sed -i 's/^archive_mode = on/archive_mode = off/' $NEW_DATA_DIR/kingbase.conf
sed -i 's/scram-sha-256/trust/g' $NEW_DATA_DIR/sys_hba.conf
sed -i 's/md5/trust/g' $NEW_DATA_DIR/sys_hba.conf

说明：

kingbase.auto.conf 是 ALTER SYSTEM 命令动态修改的参数文件，如存在建议拷贝

sys_ident.conf 仅在配置了 ident 认证方式时需要，大多数环境可忽略

使用 2>/dev/null || true 确保文件不存在时不报错

3.5 处理扩展共享对象

注意：sys_upgrade 会自动处理内置扩展的版本升级，对于第三方自定义扩展，需遵循以下原则：

处理原则	说明
查阅官方文档	确认第三方扩展是否支持目标数据库版本
优先使用新版本	从新版本的 contrib 包或扩展仓库安装对应版本
兼容性测试	如必须使用旧版本文件，需在测试环境验证后再用于生产
准备回退方案	复制前备份原文件，确保可快速回退

# 如确认兼容，从旧版本复制（谨慎操作）
# cp $OLD_INSTALL_DIR/Server/lib/xxx.so $NEW_INSTALL_DIR/Server/lib/

四、执行升级

4.1 sys_upgrade 参数说明

在执行升级前，了解各参数含义有助于正确使用工具：

参数	说明	本文档使用值	注意事项
`-b, --old-bindir`	旧版本可执行文件目录	`$OLD_INSTALL_DIR/Server/bin`	必须存在且可执行
`-B, --new-bindir`	新版本可执行文件目录	`$NEW_INSTALL_DIR/Server/bin`	必须存在且可执行
`-d, --old-datadir`	旧版本数据目录	`$OLD_DATA_DIR`	必须存在且可读
`-D, --new-datadir`	新版本数据目录	`$NEW_DATA_DIR`	必须为空或不存在
`-U, --username`	数据库超级用户	`system`	需有足够权限
`-c, --check`	仅检查兼容性，不执行升级	—	可用于预检查
`-j, --jobs`	并行进程数	`4`	建议为CPU核心数
`-v, --verbose`	输出详细日志	开启	便于排查问题
`-s, --socketdir`	升级期间使用的套接字目录	当前目录	当当前目录路径过长导致套接字创建失败时指定
`-k, --link`	硬链接模式	未使用	⚠️ 启动新库后旧库不可用
`--clone`	克隆模式（reflink）	未使用	需文件系统支持
`-o, --old-options`	旧实例额外选项	—	如 `-o '-c config_file=...'`
`-O, --new-options`	新实例额外选项	—	同 `-o`
`-r, --retain`	保留日志文件	—	调试时使用
`-s, --socketdir`	套接字目录	—	路径长时需指定
`-p, --old-port`	旧实例端口（仅检查模式）	—	仅 `-c` 模式且旧库运行时需要
`-P, --new-port`	新实例端口（仅检查模式）	—	仅 `-c` 模式且新库运行时需要

4.1.1 关键参数详解

连接相关参数说明：

-p, --old-port 和 -P, --new-port 仅在检查模式（-c）且数据库运行时需要
本文档执行升级时数据库已停止，sys_upgrade 会自动启动临时实例，无需指定端口参数

升级模式选择：

默认模式（拷贝）：最安全，新旧库独立，回退简单
链接模式（-k）：节省空间，但启动新库后旧库数据同步变更
克隆模式（--clone）：需要文件系统支持（XFS/Btrfs/APFS）

性能优化参数：

-j：并行处理，显著提升大数据库升级速度
建议值：min(CPU核心数, 表空间数量)

4.1.2 环境变量支持

sys_upgrade 也支持通过环境变量指定参数，优先级：命令行 > 环境变量 > 默认值。

环境变量	对应参数	示例值
`KBBINOLD`	`-b`	`/opt/Kingbase/ES/V9/Server/bin`
`KBBINNEW`	`-B`	`/opt/Kingbase/ES/V9R2C14/Server/bin`
`KBDATAOLD`	`-d`	`/kdb/data`
`KBDATANEW`	`-D`	`/kdb/data_V9R2C14`
`KBUSER`	`-U`	`system`

4.2 停止所有数据库实例

# 停止旧数据库
$OLD_INSTALL_DIR/Server/bin/sys_ctl -D $OLD_DATA_DIR stop -m fast

# 确认无残留进程
ps -ef | grep kingbase | grep -v grep

4.3 兼容性预检查

必须执行：预检查通过后再执行正式升级。

$NEW_INSTALL_DIR/Server/bin/sys_upgrade \
  -b $OLD_INSTALL_DIR/Server/bin \
  -B $NEW_INSTALL_DIR/Server/bin \
  -d $OLD_DATA_DIR \
  -D $NEW_DATA_DIR \
  -U system \
  -c

预期输出：*集簇是兼容的/Clusters are compatible*

4.4 执行正式升级

$NEW_INSTALL_DIR/Server/bin/sys_upgrade \
  -b $OLD_INSTALL_DIR/Server/bin \
  -B $NEW_INSTALL_DIR/Server/bin \
  -d $OLD_DATA_DIR \
  -D $NEW_DATA_DIR \
  -U system \
  -j 4 \
  -v

成功标志：输出 升级完成/Upgrade Complete，并在当前目录生成 analyze_new_cluster.sh 和 delete_old_cluster.sh 两个脚本。

说明：sys_upgrade 会报告所有影响升级成功的失败、重建和重新索引情况。升级成功后，sys_upgrade 会在执行该命令时的工作目录中生成必要的后处理脚本。

五、升级后处理

5.1 启动新数据库并验证参数

# 启动新数据库
$NEW_INSTALL_DIR/Server/bin/sys_ctl -D $NEW_DATA_DIR start

# 验证关键参数（升级后，参数应从旧配置继承）
$NEW_INSTALL_DIR/Server/bin/ksql -U system -p 54321 -d test -c "
-- 基础参数
SELECT '1. 版本' as item, version() as value;
SELECT '2. 兼容模式' as item, current_setting('database_mode') as value;
SELECT '3. 字符编码' as item, current_setting('server_encoding') as value;
SELECT '4. 区域设置' as item, current_setting('lc_ctype') as value;

-- 存储参数
SELECT '5. 块大小' as item, current_setting('block_size') as value;
SELECT '6. 段大小' as item, current_setting('segment_size') as value;
SELECT '7. WAL段大小' as item, current_setting('wal_segment_size') as value;

-- 功能参数
SELECT '8. 大小写敏感' as item, current_setting('enable_ci') as value;
SELECT '9. 数据校验和' as item, current_setting('data_checksums') as value;

-- 运行时参数（应从旧配置继承）
SELECT '10. 最大连接数' as item, current_setting('max_connections') as value;
SELECT '11. 共享缓冲区' as item, current_setting('shared_buffers') as value;
SELECT '12. 时区' as item, current_setting('timezone') as value;
"

预期输出（应与 2.1 节记录的值一致）：

 item | value
------+------------------------------------------------
 1. 版本 | KingbaseES V009R002C014 ...
 2. 兼容模式 | oracle
 3. 字符编码 | UTF8
 4. 区域设置 | zh_CN.UTF-8
 5. 块大小 | 8192
 6. 段大小 | 131072
 7. WAL段大小 | 16MB
 8. 大小写敏感 | off
 9. 数据校验和 | off
10. 最大连接数 | 300
11. 共享缓冲区 | 128MB
12. 时区 | Asia/Shanghai

5.2 更新统计信息

** 关键**：统计信息不会通过 sys_upgrade 自动迁移，必须手动执行。

# 进入生成脚本的目录（执行 sys_upgrade 时的当前目录，通常为用户家目录）
cd ~

# 执行统计信息更新，传递正确的端口号
./analyze_new_cluster.sh --port 54321

> **脚本说明**：
> - **来源**：`analyze_new_cluster.sh` 是 `sys_upgrade` 执行成功后**自动生成**的脚本，位于执行 `sys_upgrade` 命令的当前工作目录中。
> - **作用**：调用 `vacuumdb` 工具为新集群中的所有数据库更新优化器统计信息。
> 
> **执行必要性**：`sys_upgrade` **不会自动迁移统计信息**，必须手动执行此脚本。如果不执行，新集群的查询优化器将使用过时或缺失的统计信息，可能导致严重的性能问题。
> 
> **执行时机**：必须在**新数据库启动后、业务连接前**执行。
> 
> **警告说明**：执行过程中出现的 `WARNING: skipping "_kingbase_loginfo"` 是正常现象。`_kingbase_loginfo` 是 KingbaseES 内部用于系统日志记录的特殊表，`vacuumdb` 工具无法对其收集统计信息，这不会影响用户业务表的统计信息更新。

5.3 恢复归档配置

# 恢复归档模式
sed -i 's/^archive_mode = off/archive_mode = on/' $NEW_DATA_DIR/kingbase.conf

# 重新启动数据库服务
$NEW_INSTALL_DIR/Server/bin/sys_ctl -D $NEW_DATA_DIR restart

# 验证归档功能
$NEW_INSTALL_DIR/Server/bin/ksql -U system -p 54321 -d test -c "SELECT sys_switch_wal();"
ls -lt /kdb/arclog/ | head -5

5.4 验证扩展版本

# 记录升级后扩展版本
$NEW_INSTALL_DIR/Server/bin/ksql -U system -p 54321 -d test -c "SELECT extname, extversion FROM sys_extension ORDER BY extname;" > /tmp/extensions_after.txt

# 对比升级前后差异
diff /kdb/backup/extensions_before.txt /tmp/extensions_after.txt

结果解读：

无差异或仅内置扩展版本号增加：正常，sys_upgrade 已自动处理
出现自定义扩展缺失：需按照 3.5 节原则处理
出现扩展版本回退：异常，需检查升级过程

5.5 恢复安全配置

# 将认证方式改回原来的加密方式
sed -i 's/trust/scram-sha-256/g' $NEW_DATA_DIR/sys_hba.conf

# 重新加载配置
$NEW_INSTALL_DIR/Server/bin/sys_ctl -D $NEW_DATA_DIR reload

5.6 更新环境变量

# 编辑用户配置文件
vi ~/.bashrc

# 修改以下内容
export KINGBASE_HOME=$NEW_INSTALL_DIR
export KINGBASE_DATA=$NEW_DATA_DIR
export KINGBASE_PORT=54321
export PATH=$KINGBASE_HOME/Server/bin:$PATH
export LD_LIBRARY_PATH=$KINGBASE_HOME/Server/lib:$LD_LIBRARY_PATH

# 使配置生效
source ~/.bashrc

# 验证
ksql -V

5.7 升级后验证清单

类别	检查项	命令	预期结果	状态
核心参数	版本号	`SELECT version();`	V009R002C014	☐
	兼容模式	`SHOW database_mode;`	与升级前一致	☐
	字符编码	`SHOW server_encoding;`	与升级前一致	☐
	区域设置	`SHOW lc_ctype;`	与升级前一致	☐
	块大小	`SHOW block_size;`	与升级前一致	☐
	段大小	`SHOW segment_size;`	与升级前一致	☐
	大小写敏感	`SHOW enable_ci;`	与升级前一致	☐
	数据校验和	`SHOW data_checksums;`	与升级前一致	☐
	WAL段大小	`SHOW wal_segment_size;`	与升级前一致	☐
	最大连接数	`SHOW max_connections;`	与升级前一致	☐
	共享缓冲区	`SHOW shared_buffers;`	与升级前一致	☐
	时区	`SHOW timezone;`	与升级前一致	☐
归档	归档模式	`SHOW archive_mode;`	on	☐
	归档功能	检查归档目录	有新文件生成	☐
扩展	扩展列表完整	`diff extensions_before.txt extensions_after.txt`	仅内置扩展版本号增加	☐
环境变量	KINGBASE_HOME	`echo $KINGBASE_HOME`	新版本路径	☐
	KINGBASE_DATA	`echo $KINGBASE_DATA`	新数据目录	☐
数据	数据库列表	`\l`	与升级前一致	☐
	业务数据	抽样查询	数据完整	☐

5.8 清理旧环境（稳定后执行）

警告：确认新库稳定运行至少一周后再执行清理。

# 重命名保留（推荐）
mv $OLD_DATA_DIR /kdb/data_old_final_$(date +%Y%m%d)
mv $OLD_INSTALL_DIR /opt/Kingbase/ES/V9_old_final

六、应急回退方案

6.1 回退触发条件

新数据库无法启动
数据验证发现丢失或损坏
业务应用出现兼容性问题
性能严重劣化且无法快速调优

6.2 回退方式选择

回退操作取决于升级时使用的模式，不同模式下旧库状态不同：

升级模式	旧库状态	直接启动旧库	推荐回退方式
拷贝模式（默认）	完好独立	✅ 可以	直接启动旧库
链接模式（`-k`）	已损坏	❌ 不可以	从备份恢复
克隆模式（`--clone`）	不确定	⚠️ 可能可以	从备份恢复

⚠️ 重要提示：最安全的做法是无论何种模式，均从物理备份恢复，确保数据一致性和完整性。以下方案提供两种回退方式，请根据实际情况选择。

6.3 回退步骤

6.3.1 方案一：从物理备份恢复（推荐，适用于所有模式）

优点：最可靠，确保数据完整性，适用于任何升级模式。

# 1. 停止新数据库（如仍在运行）
$NEW_INSTALL_DIR/Server/bin/sys_ctl -D $NEW_DATA_DIR stop -m immediate

# 2. 备份当前状态（可选，便于问题分析）
mv $OLD_DATA_DIR $OLD_DATA_DIR_crash_$(date +%Y%m%d_%H%M%S) 2>/dev/null || true

# 3. 从物理备份恢复旧数据目录
cp -rp /kdb/backup/data_YYYYMMDD_HHMMSS $OLD_DATA_DIR

# 4. 修复权限
chown -R kingbase:kingbase $OLD_DATA_DIR
chmod 700 $OLD_DATA_DIR

# 5. 恢复环境变量（编辑 ~/.bashrc，改回旧路径）
# export KINGBASE_HOME=$OLD_INSTALL_DIR
# export KINGBASE_DATA=$OLD_DATA_DIR
# source ~/.bashrc

# 6. 启动旧数据库
$OLD_INSTALL_DIR/Server/bin/sys_ctl -D $OLD_DATA_DIR start

# 7. 验证业务
ksql -U system -p 54321 -d test -c "SELECT 1;"

6.3.2 方案二：直接启动旧库（仅适用于拷贝模式）

说明：仅当确认使用默认拷贝模式升级时，可采用此快速回退方式。

# 1. 停止新数据库
$NEW_INSTALL_DIR/Server/bin/sys_ctl -D $NEW_DATA_DIR stop -m immediate

# 2. 确认旧数据目录完好
ls -la $OLD_DATA_DIR/global/sys_control

# 3. 恢复环境变量（编辑 ~/.bashrc，改回旧路径）
# export KINGBASE_HOME=$OLD_INSTALL_DIR
# export KINGBASE_DATA=$OLD_DATA_DIR
# source ~/.bashrc

# 4. 启动旧数据库
$OLD_INSTALL_DIR/Server/bin/sys_ctl -D $OLD_DATA_DIR start

# 5. 验证业务
ksql -U system -p 54321 -d test -c "SELECT 1;"

6.4 回退后处理

无论使用哪种回退方式，建议执行以下检查：

# 1. 确认数据库状态
sys_ctl -D $OLD_DATA_DIR status

# 2. 确认归档配置已恢复
ksql -U system -d test -c "SHOW archive_mode;"

# 3. 确认备份任务已恢复（如有）
crontab -l | grep -iE "backup|dump"

# 4. 确认业务数据完整
ksql -U system -d test -c "SELECT COUNT(*) FROM your_business_table;"

6.5 回退方案选择指南

┌─────────────────────────────────────────────────────────────┐
│                   确认升级时使用的模式                        │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│   拷贝模式    │    │   链接模式    │    │   克隆模式    │
│   旧库完好    │    │  旧库已损坏   │    │  旧库不确定   │
└───────────────┘    └───────────────┘    └───────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│ 两种方案均可  │    │ 必须从备份恢复 │    │ 推荐从备份恢复 │
│ 推荐备份恢复  │    │               │    │               │
└───────────────┘    └───────────────┘    └───────────────┘

6.6 回退方案速查表

升级模式	直接启动旧库	从备份恢复	推荐方案
拷贝模式	✅ 可行	✅ 可行	备份恢复（最安全）
链接模式	❌ 不可行	✅ 必须	备份恢复
克隆模式	⚠️ 不确定	✅ 可行	备份恢复

提示：无论使用哪种模式，建议在升级前完成物理备份（2.3节），并确保备份文件可读、完整。回退前确认备份文件存在且为升级前状态。

七、测试案例

7.1 案例环境

项目	值
操作系统	Red Hat 7.9
旧版本	KingbaseES V009R002C013
新版本	KingbaseES V009R002C014
旧安装目录	`/opt/Kingbase/ES/V9`
旧数据目录	`/kdb/data`
新安装目录	`/opt/Kingbase/ES/V9R2C14`
新数据目录	`/kdb/data_V9R2C14`
归档目录	`/kdb/arclog`
监听端口	54321

7.2 升级前信息收集

-- 连接数据库，记录关键参数
SELECT version();
         version
-------------------------
 KingbaseES V009R002C013
(1 行记录)

SHOW database_mode;              -- 兼容模式 (oracle/pg)
 database_mode
---------------
 oracle
(1 行记录)

SHOW server_encoding;            -- 字符编码 (UTF8/GBK)
 server_encoding
-----------------
 UTF8
(1 行记录)

SHOW lc_ctype;                   -- 区域设置
  lc_ctype
-------------
 zh_CN.UTF-8
(1 行记录)

SHOW block_size;                 -- 块大小 (通常为 8192)
 block_size
------------
 8192
(1 行记录)

SHOW segment_size;               -- 段大小 (通常为 1GB)
 segment_size
--------------
 1GB
(1 行记录)

SHOW wal_segment_size;           -- WAL段大小 (通常为 16MB)
 wal_segment_size
------------------
 16MB
(1 行记录)

SHOW enable_ci;                  -- 大小写敏感 (off/on)
 enable_ci
-----------
 off
(1 行记录)

SHOW data_checksums;             -- 数据校验和 (off/on)
 data_checksums
----------------
 off
(1 行记录)

SHOW max_connections;            -- 最大连接数
 max_connections
-----------------
 100
(1 行记录)

SHOW shared_buffers;             -- 共享缓冲区大小
 shared_buffers
----------------
 1GB
(1 行记录)

SHOW timezone;                   -- 时区
   TimeZone
---------------
 Asia/Shanghai
(1 行记录)

SHOW data_directory;             -- 数据目录路径
 data_directory
----------------
 /kdb/data
(1 行记录)

SHOW port;                       -- 端口号
 port
-------
 54321
(1 行记录)

7.3 执行升级

$ /opt/Kingbase/ES/V9R2C14/Server/bin/sys_upgrade \
    -b /opt/Kingbase/ES/V9/Server/bin \
    -B /opt/Kingbase/ES/V9R2C14/Server/bin \
    -d /kdb/data -D /kdb/data_V9R2C14 \
    -U system -j 4 -v

Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
...
*Clusters are compatible*

Performing Upgrade
-----------------
...
Upgrade Complete

7.4 升级后验证

SELECT '1. 版本' as item, version() as value;
  item   |          value
---------+-------------------------
 1. 版本 | KingbaseES V009R002C014
(1 行记录)

SELECT '2. 兼容模式' as item, current_setting('database_mode') as value;
    item     | value
-------------+--------
 2. 兼容模式 | oracle
(1 行记录)

SELECT '3. 字符编码' as item, current_setting('server_encoding') as value;
    item     | value
-------------+-------
 3. 字符编码 | UTF8
(1 行记录)

SELECT '4. 区域设置' as item, current_setting('lc_ctype') as value;
    item     |    value
-------------+-------------
 4. 区域设置 | zh_CN.UTF-8
(1 行记录)

test=# SELECT '5. 块大小' as item, current_setting('block_size') as value;
   item    | value
-----------+-------
 5. 块大小 | 8192
(1 行记录)

SELECT '6. 段大小' as item, current_setting('segment_size') as value;
   item    | value
-----------+-------
 6. 段大小 | 1GB
(1 行记录)

test=# SELECT '7. WAL段大小' as item, current_setting('wal_segment_size') as value;
     item     | value
--------------+-------
 7. WAL段大小 | 16MB
(1 行记录)

SELECT '8. 大小写敏感' as item, current_setting('enable_ci') as value;
     item      | value
---------------+-------
 8. 大小写敏感 | off
(1 行记录)

SELECT '9. 数据校验和' as item, current_setting('data_checksums') as value;
     item      | value
---------------+-------
 9. 数据校验和 | off
(1 行记录)

SELECT '10. 最大连接数' as item, current_setting('max_connections') as value;
      item      | value
----------------+-------
 10. 最大连接数 | 100
(1 行记录)

SELECT '11. 共享缓冲区' as item, current_setting('shared_buffers') as value;
      item      | value
----------------+-------
 11. 共享缓冲区 | 1GB
(1 行记录)

SELECT '12. 时区' as item, current_setting('timezone') as value;
   item   |     value
----------+---------------
 12. 时区 | Asia/Shanghai
(1 行记录)

7.5 统计信息更新

$ cd ~
$ ./analyze_new_cluster.sh --port 54321

vacuumdb: processing database "test": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "test": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "test": Generating default (full) optimizer statistics

Done

7.6 归档恢复验证

$ sed -i 's/^archive_mode = off/archive_mode = on/' /kdb/data_V9R2C14/kingbase.conf
$ /opt/Kingbase/ES/V9R2C14/Server/bin/sys_ctl -D /kdb/data_V9R2C14 restart
$ ksql -U system -d test -c "SELECT sys_switch_wal();"
$ ls -lt /kdb/arclog/ | head -3
total 32768
-rw------- 1 kingbase kingbase 16777216 Mar 26 10:30 000000010000000000000001

八、总结

8.1 关键参数一致性要求

参数	检查命令	初始化参数
`database_mode`	`SHOW database_mode;`	`-m oracle`
`server_encoding`	`SHOW server_encoding;`	`-E UTF8`
`lc_ctype`	`SHOW lc_ctype;`	`--lc-ctype=zh_CN.UTF-8`
`wal_segment_size`	`SHOW wal_segment_size;`	`--wal-segsize=16`
`enable_ci`	`SHOW enable_ci;`	`off` 时不加 `--enable-ci`
`data_checksums`	`SHOW data_checksums;`	`off` 时不加 `--data-checksums`

8.2 核心流程回顾

升级前准备 → 新版本安装 → 执行升级 → 升级后处理 → 稳定运行
    │            │            │            │
    ├─ 参数检查  ├─ 初始化    ├─ 预检查    ├─ 统计信息更新
    ├─ 数据备份  ├─ 拷贝配置  ├─ 正式升级  ├─ 归档恢复
    ├─ 关闭归档  ├─ 扩展处理  │            ├─ 扩展验证
    └─ 简化认证  └─           └─           └─ 环境变量更新

8.3 关键注意事项

参数一致性：新库初始化参数必须与旧库完全一致，特别是 enable_ci 和 data_checksums
备份先行：物理冷备份是最可靠的回退方案
关闭归档：升级过程中归档必须关闭，关闭前确保 WAL 已归档
分步验证：预检查通过后再执行正式升级
统计信息更新：升级后必须执行统计信息更新，否则影响查询性能
扩展处理：第三方扩展需查阅官方文档确认兼容性，优先使用新版本
环境变量更新：升级后同步更新 KINGBASE_HOME 和 KINGBASE_DATA

8.4 常见问题速查

错误信息	原因	解决方案
`Checking database safety function switch is off`； `FATAL: lock file "kingbase.pid" already exists`	升级工具尝试启动旧库时，发现旧库实例已经在运行，导致无法获取锁文件。	必须先停止旧库服务。执行 `$OLD_INSTALL_DIR/Server/bin/sys_ctl -D $OLD_DATA_DIR stop -m fast`，确认进程退出后，再重新执行 `sys_upgrade`。
`旧集簇不使用数据校验和，但新集簇使用数据校验和`	新库初始化时错误地添加了 `--data-checksums` 参数，导致新旧库二进制不兼容。	删除新数据目录，重新执行 `initdb`，不要添加 `--data-checksums` 参数。
`WARNING: skipping "_kingbase_loginfo"`	`_kingbase_loginfo` 是 KingbaseES 内部用于系统日志记录的特殊表，`vacuumdb` 工具无法对其收集统计信息。	正常现象，可忽略，不影响用户业务表的统计信息更新。
`analyze_new_cluster.sh: --port: command not found`	执行统计信息更新脚本时未指定端口参数，或参数格式错误。	请指定端口号执行，例如：`./analyze_new_cluster.sh --port 54321`。
`ERROR: could not access file "xxx.so"`	升级后新库启动或查询时，找不到旧库使用的扩展插件动态链接文件。	检查新旧库的 `shared_preload_libraries` 配置，确保新库安装了相同的插件（如 `orafce`），并将 `.so` 文件拷贝至新库的 `lib` 目录。

参考资料

金仓数据库管理系统 KingbaseES V9 版本说明书（V009R002C014）— 产品版本特性说明
金仓数据库管理系统 KingbaseES 工具参考手册（V009R002C014）— sys_upgrade 工具详解
KingbaseES 官方文档中心：help.kingbase.com.cn/
金仓技术社区：bbs.kingbase.com.cn/