PostgreSQL 12 升级到 14 推荐使用 pg_upgrade 工具进行原地升级，该方式无需导出导入数据，能显著减少停机时间。升级前必须完整备份数据，且新旧版本数据库服务需同时停止才能执行迁移。

命令速用版

以下为 Linux 环境下执行升级的核心命令结构，需替换实际路径：

pg_upgrade \
  `--old-bindir`=/usr/pgsql-12/bin/ \
  `--new-bindir`=/usr/pgsql-14/bin/ \
  `--old-datadir`=/opt/pg12/data/ \
  `--new-datadir`=/opt/pg14/data/ \
  `--username`=postgres \
  `--check`

确认检查通过后，去掉 `--check` 参数正式执行升级。

为什么会这样

pg_upgrade 不需要转储数据是因为 PostgreSQL 大版本间内部数据存储格式通常保持兼容。

工具通过创建新版本的系统表文件，并直接链接或复制旧版本的用户数据文件来完成升级。如果未来版本更改了数据存储格式，该工具将无法使用，但社区通常会避免这种情况。

分步处理

1. 备份旧版本数据库：使用 pg_dump 或物理备份工具确保数据可恢复。

2. 安装新版本二进制文件：安装 PostgreSQL 14 到独立目录，不要覆盖旧版本。

3. 初始化新数据目录：使用新版本的 initdb 初始化一个空的数据目录。

4. 停止数据库服务：确保旧版本和新版本数据库实例均处于停止状态。

5. 执行兼容性检查：运行带 `--check` 参数的 pg_upgrade 命令，修复 reported 问题。

6. 执行升级命令：去掉 `--check` 参数运行 pg_upgrade，等待完成。

7. 更新统计信息：执行生成的 analyze_new_cluster.sh 脚本。

8. 清理旧文件：验证无误后，执行 delete_old_cluster.sh 释放空间。

怎么验证是否生效

启动新版本数据库，连接执行 SELECT version(); 确认显示 PostgreSQL 14。

检查数据库日志文件，确认无启动报错。

运行应用连接测试，验证业务查询和功能正常。

常见坑

1. 权限问题：确保运行 pg_upgrade 的用户对新旧数据目录均有读写权限。

2. 扩展兼容：旧版本安装的扩展（如 postgis）需在新版本预先安装相同版本或兼容版本。

3. 配置文件迁移：postgresql.conf 和 pg_hba.conf 需手动复制到新目录并调整参数。

4. 端口冲突：初始化新库时若需启动测试，需修改端口避免与旧库冲突。

常见问题

升级失败能回滚吗？

执行 pg_upgrade 后旧数据目录仍保留，可手动切回旧版本启动，但一旦执行清理脚本则无法回滚。

必须导出 SQL 文件吗？

使用 pg_upgrade 不需要导出 SQL 文件，这是它与 pg_dump/restore 方式的主要区别。

升级后需要重建索引吗？

通常不需要，但建议执行 analyze_new_cluster.sh 更新统计信息，特定版本 release note 可能有特殊要求。

参考来源

1. 瀚高数据库，pg 大版本升级之 pg_upgrade

2. CSDN，pg_upgrade 数据库版本升级

3. PostgreSQL 大版本升级 (pg_upgrade)，2023 年 8 月 15 日资料