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

原创 jiayou 2026-03-27

276

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）

二、升级前准备

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 官方文档中心：https://help.kingbase.com.cn/
金仓技术社区：https://bbs.kingbase.com.cn/

数据库实操数据库避坑墨力计划金仓数据库

最后修改时间：2026-04-03 13:26:53

「喜欢这篇文章，您的关注和赞赏是给作者最好的鼓励」

关注作者

文章被以下合辑收录

金仓数据库 kingbaseES（共32篇）

kingbaseES

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

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

前言

一、sys_upgrade 工具概述

1.1 工具定位

1.2 工作原理

1.3 关键限制

1.4 升级模式对比

1.5 支持的升级路径

二、升级前准备

2.0 环境信息确认

2.1 核心参数检查

2.2 兼容性深度检查

2.2.1 reg* 类型检查

2.2.2 表空间检查

2.2.3 事务状态检查

2.3 数据备份

2.4 环境配置调整

2.5 升级前检查清单

三、新版本安装与初始化

3.1 定义路径变量

3.2 安装新版本

3.3 初始化新数据目录

3.4 拷贝配置文件

3.5 处理扩展共享对象

四、执行升级

4.1 sys_upgrade 参数说明

4.1.1 关键参数详解

4.1.2 环境变量支持

4.2 停止所有数据库实例

4.3 兼容性预检查

4.4 执行正式升级

五、升级后处理

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

5.2 更新统计信息

5.3 恢复归档配置

5.4 验证扩展版本

5.5 恢复安全配置

5.6 更新环境变量

5.7 升级后验证清单

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

六、应急回退方案

6.1 回退触发条件

6.2 回退方式选择

6.3 回退步骤

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

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

6.4 回退后处理

6.5 回退方案选择指南

6.6 回退方案速查表

七、测试案例

7.1 案例环境

7.2 升级前信息收集

7.3 执行升级

7.4 升级后验证

7.5 统计信息更新

7.6 归档恢复验证

八、总结

8.1 关键参数一致性要求

8.2 核心流程回顾

8.3 关键注意事项

8.4 常见问题速查

参考资料

文章被以下合辑收录

评论