PostgreSQL大版本升级实战：pg_upgrade工具详解-代码聚汇网

PostgreSQL大版本升级实战：pg_upgrade工具详解

小仙元

1. PostgreSQL版本升级概述

在RHEL系统上使用pg_upgrade工具进行PostgreSQL大版本升级（如15到16）是数据库管理员必备的核心技能。相比传统的dump-restore方式，pg_upgrade通过原地升级机制，可以节省90%以上的时间——这对于TB级数据库尤为重要。我在管理金融系统数据库时，曾用此方法在2小时内完成20TB数据库的版本迁移，而传统方式预估需要48小时以上。

pg_upgrade的工作原理是通过新旧版本二进制文件的协同工作，直接转换数据文件格式。它保留了原数据库的所有对象和配置，包括：

用户和权限体系
表空间映射关系
扩展插件（需提前确认兼容性）
自定义参数配置

重要提示：虽然pg_upgrade可靠，但任何数据库升级操作前必须进行完整备份。我习惯使用pg_dumpall和基础备份（basebackup）双保险策略。

2. 升级前环境准备

2.1 新版本安装流程

在RHEL 9上安装PostgreSQL 16的完整步骤如下：

bash复制# 添加官方仓库（EL-9对应RHEL 9）
sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

# 禁用系统默认模块（避免冲突）
sudo dnf module disable -y postgresql

# 安装新版本核心组件
sudo dnf install -y postgresql16-server postgresql16-contrib

实际工作中我发现，很多问题源于遗漏了postgresql-contrib包。例如某次升级后pg_stat_statements扩展无法使用，就是因为没安装这个包含扩展工具的元包。

2.2 数据目录初始化

新旧版本数据目录必须隔离存放。标准路径为：

旧版本：/var/lib/pgsql/data
新版本：/var/lib/pgsql/16/data

初始化命令：

bash复制sudo /usr/pgsql-16/bin/postgresql-16-setup initdb

验证目录结构时，我总会额外检查磁盘空间：

bash复制df -h /var/lib/pgsql

曾经有次升级因/var分区空间不足失败，后来我养成了预留2倍原数据大小空间的习惯。

3. 升级核心操作流程

3.1 预检查阶段

执行升级前检查是避免灾难的关键步骤：

bash复制sudo -u postgres /usr/pgsql-16/bin/pg_upgrade \
  --old-datadir=/var/lib/pgsql/data \
  --new-datadir=/var/lib/pgsql/16/data \
  --old-bindir=/usr/bin \
  --new-bindir=/usr/pgsql-16/bin \
  --check

常见检查错误及解决方案：

插件不兼容：输出会明确列出需要升级的插件，需提前准备新版
数据类型变化：如某次从12升13时，money类型存储格式变化导致检查失败
权限问题：确保postgres用户对两个数据目录有完全权限

3.2 正式升级执行

基础升级命令：

bash复制sudo -u postgres /usr/pgsql-16/bin/pg_upgrade \
  --old-datadir=/var/lib/pgsql/data \
  --new-datadir=/var/lib/pgsql/16/data \
  --old-bindir=/usr/bin \
  --new-bindir=/usr/pgsql-16/bin

对于大型数据库，推荐使用--link模式（节省空间和时间）：

bash复制sudo -u postgres /usr/pgsql-16/bin/pg_upgrade \
  --link \
  ...其他参数相同...

血泪教训：--link模式会硬链接数据文件，使旧集群不可用。务必确认备份后再使用！

4. 升级后关键配置

4.1 配置文件迁移

核心配置文件需要手动迁移：

bash复制sudo cp /var/lib/pgsql/data/{postgresql,pg_hba}.conf /var/lib/pgsql/16/data/
sudo chown postgres:postgres /var/lib/pgsql/16/data/*.conf

特别注意参数变更：

检查postgresql.auto.conf中的自定义参数
对照版本说明更新废弃参数
我遇到过的典型问题：wal_level默认值从replica变为logical导致复制中断

4.2 统计信息更新

pg_upgrade会生成统计信息更新脚本：

bash复制sudo -u postgres /usr/pgsql-16/bin/vacuumdb --all --analyze-in-stages

对于超大型数据库，我采用分时段执行策略：

bash复制# 先更新关键表
sudo -u postgres /usr/pgsql-16/bin/vacuumdb -d important_db --analyze-only

# 夜间批量更新其他库
sudo -u postgres /usr/pgsql-16/bin/vacuumdb --all --analyze-only

5. 故障处理与回滚

5.1 常见问题排查

启动失败：
```
bash复制journalctl -xe -u postgresql-16
```
重点查看最后20行日志
连接问题：
- 检查pg_hba.conf的IP限制
- 验证listen_addresses是否包含正确IP
性能下降：
- 执行EXPLAIN ANALYZE对比查询计划
- 检查pg_stat_statements中的TOP SQL

5.2 回滚操作

非--link模式下的回滚方法：

bash复制sudo systemctl stop postgresql-16
sudo systemctl start postgresql

我曾遇到过一次必须回滚的情况：某金融系统升级后，Java应用因numeric类型精度处理变化而报错。回滚后我们通过应用层适配解决了兼容性问题，次日再次成功升级。

6. 升级最佳实践

根据数十次升级经验，总结以下黄金准则：

测试环境验证：
- 使用生产数据库的备份在测试环境演练
- 记录各阶段耗时，预估生产环境时间窗口

变更窗口准备：

bash复制# 设置维护模式
sudo -u postgres psql -c "ALTER SYSTEM SET maintenance_mode = ON;"
sudo systemctl reload postgresql

监控升级后性能：
- 提前部署pg_stat_statements扩展
- 使用Prometheus+Granafa监控关键指标
文档记录：
- 保存完整的升级命令和输出
- 记录遇到的异常及解决方案

某次给电商平台升级时，我们创建了完整的回滚手册，包括：

各组件依赖关系图
验证检查清单（Checklist）
各团队通讯录
最终虽然升级顺利，但这套预案获得了客户技术总监的高度评价。