PostgreSQL集群原地大版本升级指南：vitabaks/postgresql_cluster项目详解

概述

在数据库运维工作中，PostgreSQL大版本升级是一项关键但风险较高的操作。vitabaks/postgresql_cluster项目提供了一套完整的自动化解决方案，通过Ansible角色实现PostgreSQL集群的原地(in-place)大版本升级（如从16版本升级到17版本）。本文将深入解析这一升级过程的技术细节和最佳实践。

兼容性说明

该升级方案支持从PostgreSQL 9.3到最新版本的所有大版本升级。值得注意的是，升级过程采用硬链接而非文件复制的方式，因此无需为升级预留额外的磁盘空间，但要求新旧数据目录(pg_old_datadir和pg_new_datadir)必须位于同一个顶级目录(pg_upper_datadir)下。

升级前准备

系统要求

1. 版本声明：必须明确指定当前版本(pg_old_version)和目标版本(pg_new_version)
2. 目录结构：新旧数据目录必须位于同一顶级目录下
3. 空间要求：由于使用硬链接技术，无需额外磁盘空间

推荐操作

1. 全面更新：建议在升级前先更新PostgreSQL及其扩展，同时考虑更新Patroni和整个系统

   • 可使用update_pgcluster.yml剧本完成此操作

2. 预检查：执行预检查确保数据库模式与目标版本兼容

   ansible-playbook pg_upgrade.yml -t pre-checks,upgrade-check
   

   成功检查后会显示：

   • "数据库模式与PostgreSQL <新版本>兼容"
   • "集群兼容"

升级执行流程

1. 升级前检查阶段

这一阶段包含多项关键检查，确保升级条件完备：

• 变量验证：确认必需变量已正确设置
• 目录验证：确保新旧数据目录和配置目录不冲突
• 环境检查：
  • 验证Python依赖(pexpect)
  • 测试PostgreSQL Unix socket访问
  • 检查当前PostgreSQL版本
• 集群健康检查：
  • 验证物理复制状态
  • 检查复制延迟(不超过max_replication_lag_bytes)
  • 检查长事务(不超过max_transaction_sec)
• 基础设施检查：
  • SSH密钥认证配置
  • Rsync功能测试
  • 表空间检查
  • PgBouncer访问测试
  • 集群VIP状态检查(如配置)

2. 软件包安装

• 清理包管理器缓存(yum/dnf或apt)
• 安装新版本PostgreSQL软件包
• 可选安装TimescaleDB扩展(如启用)

3. 数据库初始化与兼容性检查

• 新数据库初始化：
  • 创建新数据目录
  • 保留原用户、编码和数据校验设置
• 模式兼容性检查：
  • 启动临时PostgreSQL实例
  • 使用pg_dumpall --schema-only检查模式兼容性
  • 分析检查日志(/tmp/pg_schema_compatibility_check.log)
• 升级检查：
  • 执行pg_upgrade --check验证集群兼容性

4. Patroni配置准备

• 备份原patroni.yml配置
• 更新关键参数：
  • data_dir、bin_dir、config_dir
  • 调整不兼容的PostgreSQL参数
  • 移除standby_cluster参数(如存在)
• 复制pg_hba.conf到新配置目录

5. 正式升级阶段

• 进入维护模式：
  • 暂停Patroni集群
  • 根据架构类型调整：
    • Type A：暂停HAProxy检查
    • Type B：暂停vip-manager
• 停止Patroni服务
• 执行pg_upgrade：
  • 使用硬链接方式升级数据文件
  • 保留原数据目录作为备份
• 更新扩展：
  • 自动更新所有PostgreSQL扩展(如配置)
• 调整目录权限：
  • 确保新目录权限正确
• 更新Patroni配置：
  • 恢复维护前的配置
• 重启服务：
  • 启动Patroni
  • 恢复HAProxy/vip-manager
• 清理工作：
  • 可选移除旧软件包
  • 执行pgBackRest stanza升级(如使用)

数据库停机考量

升级过程中，通过暂停PgBouncer连接池来最小化应用影响：

• 应用不会立即断开连接，但可能遇到查询延迟增加
• 默认暂停时间约30秒，大型数据库可能更长
• 默认查询超时时间为2分钟(query_wait_timeout)
• 可配置终止长时间运行的查询(pgbouncer_pool_pause_terminate_after)

回滚机制

升级失败时可执行回滚：

ansible-playbook pg_upgrade_rollback.yml

回滚流程：

1. 检查当前集群状态
2. 验证PostgreSQL版本
3. 确保新版本未运行
4. 切换回旧版本路径
5. 重启Patroni服务

注意：回滚仅在新版本未完全启动时有效。

关键配置参数

最佳实践建议

1. 充分测试：在生产环境升级前，在测试环境完整演练整个流程
2. 备份优先：确保有完整的数据库备份，包括pgBackRest等备份工具配置
3. 监控准备：升级期间密切监控系统资源和数据库状态
4. 维护窗口：选择业务低峰期执行升级
5. 回滚预案：预先准备好回滚方案和验证步骤
6. 文档记录：详细记录升级过程和遇到的问题

通过vitabaks/postgresql_cluster项目提供的这套自动化升级方案，DBA可以大大降低PostgreSQL大版本升级的风险和复杂度，实现安全可靠的版本迁移。