PostgreSQL 小版本更新（patch）

在同一主版本内进行小版本更新（例如 17.4 → 17.x）：检查 release notes、备份，并保留当前的 RPM/deb 包以便回退。单服务器上只需短暂停机；在 streaming replication 集群中先更新 standby，再通过 switchover 更新 primary（rolling）；在 Patroni 集群中，replica 通过 patronictl restart 更新，leader 在 patronictl switchover 之后更新。包括扩展更新、验证和回退（downgrade）runbook。完成后所有服务器运行相同的新小版本，并且手头仍保留上一版本的文件以便回退。

如果主版本发生变化（例如 16 → 17），请使用 pg-major-upgrade 而不是本指南；Patroni 软件本身的更新见 pg-patroni。

架构: 1 台服务器、primary + standby，或 Patroni 集群

场景

• 小版本更新 — 在同一主版本内升级到较新的小版本（例如 17.4 → 17.6）：安全修复和错误修复。单服务器上短暂停机，集群中采用 rolling 方式。
• 回退：恢复到上一个小版本（downgrade） — 新小版本中出现错误或回归：使用保存的上一版本 RPM/deb 包回退。数据目录不变。

开始之前

• PostgreSQL … 已从 PGDG 仓库安装并在运行（pg-install）。更新在同一主版本内进行；从 … 升级到其他主版本请使用 pg-major-upgrade 指南。
• 已阅读当前版本与目标版本之间每个小版本的 release notes。特别记录了 “Migration to Version …” 部分是否要求额外操作（REINDEX、参数变更）：https://www.postgresql.org/docs/release/
• 服务器可以访问 PGDG 仓库或内部镜像，且镜像是最新的。
• 维护窗口已获批准…（服务停止几秒到几分钟）…（switchover/restart 时连接会中断几秒）…；已通知应用团队。
• 最近一次备份成功…（pgbackrest info status ok）…，并且可以对服务器做虚拟机/磁盘快照。
• 所有 standby 均处于 streaming 状态且没有延迟。
• switchover 后角色会发生变化，因此每个节点的 pg_hba.conf 都允许来自其他节点的 replication 连接，并且所有节点上 postgres 用户的 ~/.pgpass 文件中都有 … 的密码。
• 集群不由 Patroni 或 repmgr 等 HA 工具管理。如果由 Patroni 管理，请在“拓扑”中选择 Patroni；repmgr 请参见“说明”。此路径中的手动 switchover 步骤会与 HA 工具的决策冲突。
• Patroni 集群健康：有一个 Leader，所有 replica 均为 streaming，Lag 很小，且 Maintenance mode 已关闭。… 是当前 leader；replica 名称与 Patroni 成员名一致。
• 执行变更的 patronictl 命令（restart、switchover）需要 REST API 认证；用户名/密码位于所有节点的 /etc/patroni/patroni.env 文件中（pg-patroni 安装）。如果使用不同的布局，则 patronictl 通过 -c 读取的文件中必须定义 restapi.authentication。
• 更新前已将上一版本的 RPM/deb 文件保存到 … 目录，上一版本号记录在 …/prev-version.txt 文件中。如果没有这些文件，则需要从仓库下载上一版本（EL：PGDG 保留旧版本；Debian/Ubuntu：apt-archive.postgresql.org）。

指南阶段

• 预检查 — 记录当前版本 · 列出仓库中的版本 · 查看 release notes · 列出已安装的扩展 · 检查长事务和 prepared transaction
• 备份和回退点 — 备份（pgBackRest） · 备份（pg_dumpall + 快照） · 保留当前的 RPM/deb 文件
• Patroni 集群：预检查 — 验证集群状态和角色
• 更新 — 执行 checkpoint · 停止 PostgreSQL · 更新软件 · 启动 PostgreSQL
• 更新 primary（短暂停机） — 执行 checkpoint · 停止 primary · 更新软件 · 启动 primary
• switchover 并更新原 primary — 验证复制是最新的 · 停止应用写入 · 干净关闭原 primary 并记下最后的 checkpoint · …：验证所有 WAL 均已到达并执行 promote · 将应用重定向到新的 primary · 为原 primary 创建 replication slot …
• Leader：switchover 并更新原 leader — 原 leader：更新软件 · Switchover：让 … 成为 leader · 重启原 leader（…） · 验证集群的最终状态
• 扩展与验证 — 更新扩展（ALTER EXTENSION … UPDATE） · 更新扩展（ALTER EXTENSION … UPDATE） · 执行 release notes 中的额外操作 · 验证版本和状态 · 在日志中查找错误 · 更新后的备份 …
• 回退（downgrade） — 检查上一版本 · …：停止、安装上一版本、启动 · …：安装上一版本并通过 Patroni 重启 · Leader：安装上一版本 · 移交 leader 并重启原 leader · …停止 primary…停止 PostgreSQL… …