PostgreSQL 逻辑复制（publication / subscription）

在两个 PostgreSQL 集群之间进行表级逻辑复制：wal_level=logical、replica identity 检查、publication 和 subscription、初始同步、监控、冲突（conflict）处理、手工同步 sequence。还包括跨版本迁移（大版本升级、更换服务器）时将停机控制在数秒内的最终切换（cutover）步骤。

逻辑复制不是 HA 或备份方案：整个集群的完整副本和 failover 请使用 流复制 或 Patroni，备份请使用 pgBackRest。在同一服务器上原地进行大版本升级（pg_upgrade）见 pg-major-upgrade。

架构: 2 台服务器：发布端（publisher）+ 订阅端（subscriber）；发布端可以是单台服务器、流复制或 Patroni 集群

场景

• 持续复制（报表、集成、部分副本） — 选定的表持续流向另一个集群（报表服务器、数据仓库供数、服务间集成）。订阅端保持可写。
• 迁移：新服务器 / 新大版本 + 最终切换（cutover） — 以秒级停机迁移到新服务器或新大版本：初始复制和持续同步，然后短暂停止写入并进行最终切换（cutover）。

开始之前

• 发布端运行 PostgreSQL …，且存在 … 数据库。
• Patroni 集群 … 运行正常，… 当前为 Leader；replica 上 hot_standby_feedback = on（pg-patroni 默认值）。
• Standby … 通过 physical replication slot 连接到 primary（primary_slot_name = …，pg-streaming 中的 slot 选项）。没有该 slot，slot 同步无法工作。
• 订阅端已通过 pg-install 安装 PostgreSQL … 并在运行；发布端所用扩展（PostGIS 等）的 … 版本已安装。
• 订阅端可以访问发布端的… HAProxy/VIP 地址（…:…）… … 端口…（防火墙 / 安全组）。
• 发布端当前的 wal_level 是什么值？如果不是 logical，修改需要重启：请安排维护窗口。
• 要发布的表都有 primary key 或合适的 unique index。否则 UPDATE/DELETE 会在发布端报错：为列出的表添加 PK，或定义 replica identity（见下面的步骤）。
• 逻辑复制不复制 DDL（CREATE/ALTER TABLE），也不复制 sequence 值和 large object。复制期间的 schema 变更将手工先在订阅端、再在发布端执行；已通知团队。
• 发布端为 WAL 预留了额外磁盘空间：订阅端停止时 slot 会积累 WAL（上限：… GB）。

指南阶段

• 准备发布端 — 确认发布端是… Leader… primary… · 写入逻辑复制设置 · 将逻辑复制设置写入 Patroni · 重启发布端 · 重启 Patroni 成员 · 创建复制用户 …
• Replica identity — 列出没有 PK 的表 · 为没有 PK 的表定义 replica identity
• Publication — 创建 publication
• 准备订阅端 — 写入订阅端 worker 设置 · 重启订阅端 · 将发布端密码写入 .pgpass · 创建数据库和 schema · 迁移角色和权限
• Subscription 与初始同步 — 创建 subscription · 等待初始同步完成 · 比较数据行数 · 实时变更测试
• failover 时保留 slot — 在 Patroni 中将 slot 定义为持久（permanent） · 确认 slot 出现在 replica 上 · Primary：定义已同步的 standby slot · Standby：启用 slot 同步 · failover 后将订阅指向新 primary · failover 后重建订阅
• 监控 — 订阅状态（订阅端） · Slot 延迟（发布端）
• 冲突（conflict）处理 — 查找错误 · 在订阅端修正冲突的行 · 跳过冲突的事务
• 同步 sequence — 将 sequence 值从发布端传到订阅端
• 最终切换（cutover） — 停止发布端的写入 · 确认最后的变更已传递 · 最后一次同步 sequence · 删除订阅 · 收集统计信息 · 将应用切换到订阅端 …
• 维护操作 — 添加新表 · Schema 变更（ALTER TABLE） · 删除订阅（无法访问发布端时）