PostgreSQL 大版本升级

适用场景

需要升级 PostgreSQL 大版本（如 15→16/17）以获得新特性、性能改进或支持。常用 pg_upgrade 原地升级或逻辑导出导入。

前置条件

• 完整物理备份，并确认可恢复。
• 新版本二进制和扩展包已安装。
• 检查扩展、locale、编码、表空间和复制拓扑。
• 准备停机窗口和回滚方案。

步骤

1. 记录旧集群信息：

psql -c 'SELECT version();'
psql -c '\l'
psql -c '\dx'
pg_lsclusters

2. 安装新版本并初始化新数据目录：

/usr/lib/postgresql/16/bin/initdb -D /var/lib/postgresql/16/main

3. 运行兼容性检查：

/usr/lib/postgresql/16/bin/pg_upgrade \
  --old-bindir=/usr/lib/postgresql/15/bin \
  --new-bindir=/usr/lib/postgresql/16/bin \
  --old-datadir=/var/lib/postgresql/15/main \
  --new-datadir=/var/lib/postgresql/16/main \
  --check

4. 停旧集群，执行升级：

pg_ctl -D /var/lib/postgresql/15/main stop -m fast
pg_upgrade ... --link --jobs=4

--link 更快但不可回退到旧集群；保守场景用 --copy。

5. 启动新集群并更新统计信息：

pg_ctl -D /var/lib/postgresql/16/main start
vacuumdb --all --analyze-in-stages

6. 更新连接串、systemd 单元、备份和监控配置。

验证

• SELECT version(); 为新版本。
• 表、索引、扩展、序列和权限正常。
• 应用查询、事务和复制正常。
• 慢查询和连接数无异常。

回滚

• 保留旧数据目录、旧二进制和完整备份。
• --link 升级后旧集群可能不可用；回滚通常依赖备份。
• 恢复旧集群后更新连接配置。

常见坑

• 扩展未安装新版本对应包，pg_upgrade --check 会失败。
• locale/编码/架构不兼容不能直接升级。
• --link 不可逆；生产先用 --copy 或测试环境验证。
• 统计信息不迁移，升级后必须 ANALYZE。
• 复制槽、逻辑复制和订阅要单独处理。
• 升级后连接串、端口和认证配置要同步。

相关命令

• pg_upgrade — 大版本升级
• pg_dump / pg_restore — 逻辑迁移
• pg_ctl — 启停
• vacuumdb — 统计信息