PostgreSQL 逻辑复制支持系统表同步详细设计文档


 TL;DR
本设计的目标不是实现完整 DDL 自动复制链路,而是先补齐以下两项基础能力:
难度 中等

—— 新增系统表 pg_publication_sync 与用户接口扩展


1. 设计目标

本设计的目标不是实现完整 DDL 自动复制链路,而是先补齐以下两项基础能力:

  1. 新增系统 catalog 表 pg_publication_sync
    用于在内核中持久化 publication 维度的 DDL 同步控制信息。

  2. 扩展 publication / subscription 用户接口
    在 CREATE/ALTER PUBLICATION 与 CREATE/ALTER SUBSCRIPTION 中增加 ddl 参数,使用户能够声明 DDL 同步能力范围。

本设计仅覆盖:

  • 系统表定义
  • catalog 结构
  • 用户语法
  • 参数解析与校验
  • catalog 存储模型
  • 与现有 pg_publication / pg_subscription 的关系

本设计不包含:

  • DDL 捕获机制
  • DDL WAL 编码机制
  • logical decoding 如何发送 DDL
  • apply worker 如何执行 DDL
  • DDL 冲突处理
  • 初始 schema 同步

2. 设计原则

2.1 pg_publication_sync 的定位

pg_publication_sync 应被设计为一张类似 pg_publication 的系统 catalog 表,而不是运行时消息队列表。

它的定位是:

  • 系统表
  • pg_catalog 下的 catalog
  • 保存 publication 相关的 DDL 同步元信息
  • 由内核维护
  • 不作为普通用户表参与逻辑复制对象集管理
  • 不承载逐条 DDL 事件日志

因此它的角色更接近:

  • pg_publication
  • pg_subscription
  • pg_publication_rel

而不是:

  • 运行时 message queue
  • 审计流水表
  • DDL 事件日志表

2.2 用户接口先行

本阶段首先冻结用户接口和 catalog 结构,确保:

  • SQL 语法明确
  • 参数语义明确
  • catalog 模型稳定
  • 后续捕获与应用逻辑可以在此基础上继续扩展

2.3 与现有逻辑复制模型兼容

本设计沿用现有逻辑复制控制面风格:

  • publication 保存“发布侧配置”
  • subscription 保存“订阅侧配置”
  • 新增 pg_publication_sync 保存“DDL 同步维度的附加控制信息”

尽量避免把 DDL 设计成与现有 publication 体系完全独立的一套机制。


3. 总体方案

整体上引入三类元数据:

  1. pg_publication.pubddl
    表示该 publication 开启了哪些 DDL 类型。

  2. pg_subscription.subddl
    表示该 subscription 允许接收哪些 DDL 类型。

  3. pg_publication_sync
    保存 publication 维度的 DDL 同步附加配置,用于描述:

    • 哪个 publication 参与 DDL 同步
    • DDL 同步对象范围
    • DDL 类型集合
    • 与对象标识、归属范围相关的控制信息

因此,pg_publication_sync 不是“替代 pg_publication”,而是:

对 pg_publication 在 DDL 同步维度上的补充 catalog。


4. 系统表 pg_publication_sync 设计


4.1 表用途

pg_publication_sync 用于保存 publication 的 DDL 同步控制元数据。

它主要解决的问题是:

  • pg_publication 只描述 publication 本身的通用属性

  • pg_publication_rel 只描述 publication 与 table 的映射关系

  • 对于 DDL 同步,还需要一张单独的 catalog,来表达:

    • publication 在 DDL 维度上的配置
    • publication 对象范围与 DDL 类型之间的映射
    • 后续扩展不同对象类别时的统一元数据载体

因此:

pg_publication_sync 是一张publication 的 DDL 同步控制表。


4.2 表属性

建议该表具备如下属性:

  • 系统 catalog
  • 位于 pg_catalog
  • 参与 initdb 初始化
  • 仅内核维护
  • 普通用户不可直接 DML
  • 可由超级用户只读查询用于排障
  • 不属于普通 publication object
  • 不允许用户通过 FOR TABLE 直接操作它

4.3 建议字段设计

既然现在表定位改为“类似 pg_publication 的 catalog 表”,那么你前面那套字段:

  • lsn
  • xid
  • ddl_seqno
  • message_data

这类明显偏运行时事件消息的字段就不适合继续保留在 pg_publication_sync 里了。

这里应该改成配置型字段。

建议字段如下:

列号 字段 类型 说明
1 oid oid catalog 行 OID
2 pfsyncpubid oid 关联 pg_publication.oid
3 pfsynckind char 同步对象类型
4 pfsyncnspid oid 关联 schema 的 OID,可为空
5 pfsyncrelid oid 关联 table/relation 的 OID,可为空
6 pfsyncobjid oid 关联对象 OID,可为空
7 pfsyncsubid int4 子类型或细分类别
8 pfsyncenabled bool 是否启用
9 pfsyncddl int4 DDL 类型 bitmask
10 pfsyncextra text 或 jsonb 预留扩展字段

4.4 字段说明

4.4.1 oid

系统 catalog 行 OID,保持与 pg_publication、pg_subscription 等系统表一致风格。


4.4.2 pfsyncpubid

引用 pg_publication.oid,表示该条同步配置属于哪个 publication。

这是该表最核心的归属字段。


4.4.3 pfsynckind

表示这条配置对应的同步对象维度。建议用单字符编码,例如:

  • r:relation/table
  • n:namespace/schema
  • p:publication 级默认项
  • o:generic object

这个字段的作用是区分一条 pg_publication_sync 记录到底描述的是:

  • publication 级全局 DDL 同步配置
  • 某个 schema 范围的 DDL 同步配置
  • 某个 relation 范围的 DDL 同步配置
  • 某个特定对象的 DDL 同步配置

这样后续扩展会比较平滑。


4.4.4 pfsyncnspid

当同步规则绑定到 schema 时,记录 schema OID。

典型对应:

  • FOR TABLES IN SCHEMA ...
  • 后续 schema 级 DDL 对象归属控制

无 schema 语义时可为 InvalidOid。


4.4.5 pfsyncrelid

当同步规则绑定到 relation/table 时,记录 relation OID。

典型对应:

  • FOR TABLE ...
  • 表附属对象(index/trigger/rule/sequence)的归属控制

不是表范围时可为 InvalidOid。


4.4.6 pfsyncobjid

预留给非 relation 普通对象使用,例如:

  • function
  • type
  • domain
  • extension
  • view

这样设计是为了给未来的非表对象 DDL 同步留下 catalog 表达能力。

若当前实现只先承载 publication/schema/relation 范围,也可以允许该字段为空。


4.4.7 pfsyncsubid

用于表达对象子类或附加类型。例如:

  • index / trigger / rule / sequence 作为 relation 附属对象的子类区分
  • function 重载签名的辅助区分
  • 后续对象细粒度同步控制

当前阶段若暂不需要精细区分,也可以保留字段但先不启用复杂语义。


4.4.8 pfsyncenabled

表示该同步项是否启用。

这样可以支持后续:

  • 逻辑禁用某条规则而不删除行
  • ALTER PUBLICATION ... SET (...) 时平滑更新
  • 调试和升级兼容

4.4.9 pfsyncddl

保存 DDL 类型集合,建议为 bitmask。

与 pg_publication.pubddl 的区别是:

  • pubddl:publication 全局能力声明
  • pfsyncddl:某条具体同步规则上实际生效的 DDL 类型集合

例如:

  • publication 全局声明支持 table,index,trigger,view,function
  • 某个 table 范围同步项仅允许 table,index,trigger

则具体记录体现在 pfsyncddl 上。


4.4.10 pfsyncextra

预留扩展字段。可选:

  • text
  • jsonb

如果追求 catalog 简洁,建议先用 text 预留;
如果预期很快需要结构化扩展,建议直接用 jsonb。

考虑 PostgreSQL catalog 一贯风格,系统表中直接用 jsonb 不是不可以,但会显得偏重。
若当前仅做接口与表设计,建议先用 text 更稳妥。


4.5 推荐建模方式

我建议把 pg_publication_sync 设计成:

pg_publication 的 DDL 同步扩展表

类似于:

  • pg_publication:publication 主表
  • pg_publication_rel:publication 与 relation 的关联表
  • pg_publication_namespace:publication 与 namespace 的关联表
  • pg_publication_sync:publication 与 DDL 同步控制项的关联表

这样结构最清晰,也最符合 PostgreSQL 现有 catalog 风格。


5. 与现有 catalog 的关系


5.1 pg_publication 扩展

在 pg_publication 中新增字段:

pubddl int4

表示 publication 级别声明允许同步的 DDL 类型集合。

示例:

  • 0:不启用 DDL 同步
  • PUBDDL_TABLE | PUBDDL_INDEX:启用 table/index DDL 同步
  • 更大集合:启用更多对象类型

pubddl 的作用偏向全局总开关 + 能力声明。


5.2 pg_subscription 扩展

在 pg_subscription 中新增字段:

subddl int4

表示 subscription 接受哪些 DDL 类型。

其作用是:

  • 用户接口持久化
  • 建立订阅时做兼容校验
  • 后续运行时作为本地约束边界

5.3 pg_publication_sync 与 pg_publication_rel 的关系

两者不是替代关系,而是分工不同:

  • pg_publication_rel:描述 DML 复制对象范围
  • pg_publication_sync:描述 DDL 同步控制范围

例如:

  • 一张表被加入 publication 的 DML 集合,不代表它的 DDL 一定同步
  • 一条 DDL 同步规则可以引用与 relation 相关的对象范围,但其语义不同于 DML 复制成员关系

因此需要独立建模。


6. 用户接口设计


6.1 CREATE PUBLICATION 扩展

在 publication 参数中增加:

WITH (ddl = 'table,index,sequence,trigger,view,rule,schema,function,type,domain,extension')

6.1.1 参数语义

ddl 表示该 publication 声明允许同步的 DDL 类型集合。

该参数本质上是 publication 的DDL 能力开关。


6.1.2 示例

CREATE PUBLICATION pub1
FOR TABLE public.t1
WITH (ddl = 'table,index,trigger');

CREATE PUBLICATION pub2
FOR TABLES IN SCHEMA public
WITH (ddl = 'table,index,view,function,type');

CREATE PUBLICATION pub3
FOR ALL TABLES
WITH (ddl = 'table,index,sequence,trigger,view,rule,schema,function,type,domain,extension');

6.1.3 支持 token

建议一次性支持以下 token:

  • table
  • index
  • sequence
  • trigger
  • view
  • rule
  • schema
  • function
  • type
  • domain
  • extension

6.1.4 解析规则

在 gram.y 中扩展 publication option 解析:

  1. 读取 ddl 字符串
  2. 按逗号拆分
  3. trim 空白
  4. 标准化大小写
  5. 校验 token
  6. 转换为 bitmask
  7. 存入 pg_publication.pubddl

6.2 ALTER PUBLICATION 扩展

支持:

ALTER PUBLICATION pub1 SET (ddl = 'table,index,trigger');

语义:

  • 更新 pg_publication.pubddl
  • 如有必要,同步调整 pg_publication_sync 中的对应规则项

由于本阶段只讨论接口和系统表,文档里只需定义:

ALTER PUBLICATION 修改 ddl 后,系统 catalog 中 publication 级 DDL 配置必须保持一致。

不需要展开具体同步更新算法。


6.3 CREATE SUBSCRIPTION 扩展

增加:

WITH (ddl = 'table,index,sequence,trigger,view,rule,schema,function,type,domain,extension')

6.3.1 参数语义

ddl 表示该 subscription 允许接收的 DDL 类型集合。

它是订阅端的能力声明与约束条件。


6.3.2 示例

CREATE SUBSCRIPTION sub1
CONNECTION '...'
PUBLICATION pub1
WITH (ddl = 'table,index,trigger');

CREATE SUBSCRIPTION sub2
CONNECTION '...'
PUBLICATION pub1, pub2
WITH (ddl = 'table,index,sequence,view,function');

6.3.3 校验规则

在创建 subscription 时,检查:

subddl ⊆ OR(pubddl of all selected publications)

也就是订阅端请求的 DDL 能力不能超出发布端可提供能力。

这里只做接口层校验定义,不展开远端拉取与实现细节。


6.4 ALTER SUBSCRIPTION 扩展

支持:

ALTER SUBSCRIPTION sub1 SET (ddl = 'table,index,view,function');

语义:

  • 更新 pg_subscription.subddl
  • 后续接收 DDL 时按新集合解释

本阶段无需展开运行时行为。


7. ddl 参数的内部表示


7.1 bitmask 定义

建议统一定义:

#define PUBDDL_TABLE      (1 << 0)
#define PUBDDL_INDEX      (1 << 1)
#define PUBDDL_SEQUENCE   (1 << 2)
#define PUBDDL_TRIGGER    (1 << 3)
#define PUBDDL_VIEW       (1 << 4)
#define PUBDDL_RULE       (1 << 5)
#define PUBDDL_SCHEMA     (1 << 6)
#define PUBDDL_FUNCTION   (1 << 7)
#define PUBDDL_TYPE       (1 << 8)
#define PUBDDL_DOMAIN     (1 << 9)
#define PUBDDL_EXTENSION  (1 << 10)

publication 与 subscription 复用同一套定义。


7.2 解析辅助函数

建议增加统一函数:

  • parse_publication_ddl_option(const char *value)
  • parse_subscription_ddl_option(const char *value)
  • ddl_mask_to_string(int mask)

用于:

  • SQL option 解析
  • 错误消息输出
  • catalog 回显

8. pg_publication_sync 的 catalog 建模建议


8.1 文件

新增:

  • src/include/catalog/pg_publication_sync.h
  • src/include/catalog/pg_publication_sync.dat

8.2 索引建议

至少需要:

  1. 主键 OID 索引
  2. pfsyncpubid 上索引

若后续频繁按 relation/schema 查找,可增加:

  • (pfsyncpubid, pfsyncrelid)
  • (pfsyncpubid, pfsyncnspid)

当前阶段文档可先给出推荐,不必过度展开。


8.3 唯一性约束建议

建议至少保证同一 publication 下,同一同步对象范围不会重复定义。

可抽象为:

(pfsyncpubid, pfsynckind, pfsyncnspid, pfsyncrelid, pfsyncobjid, pfsyncsubid)

唯一。

这样可以避免同一个 publication 下生成重复控制项。


9. 推荐的语义关系

可以把三层关系理解为:

9.1 pg_publication.pubddl

回答问题:

这个 publication 总体上支持哪些 DDL 类型?


9.2 pg_subscription.subddl

回答问题:

这个 subscription 总体上接受哪些 DDL 类型?


9.3 pg_publication_sync

回答问题:

这个 publication 的 DDL 同步规则具体落在哪些范围/对象上?


10. 建议的 SQL 语义说明

为了让接口更清晰,建议在文档中明确:

10.1 ddl 是能力声明,不是逐条事件记录

用户执行:

CREATE PUBLICATION pub1
FOR TABLE public.t1
WITH (ddl = 'table,index');

表达的是:

  • pub1 开启了 table/index 类别的 DDL 同步能力
  • 该能力与 public.t1 这个 publication 范围相关联
  • 系统会把相关元数据存入 pg_publication 与 pg_publication_sync

而不是:

  • 立即生成任何 DDL 事件
  • 或者记录运行时消息

10.2 pg_publication_sync 是配置表,不是运行时流水表

用户查询该表,看到的应该是:

  • publication 级控制项
  • 某个 table/schema/object 范围对应的 DDL 配置

而不是历史发生过的每条 DDL。


11. 权限与可见性设计

建议:

  • 普通用户不可直接 DML pg_publication_sync
  • 超级用户可读
  • publication owner / subscription owner 是否可读可根据现有系统表可见性策略决定
  • 任何用户 SQL 对其 INSERT/UPDATE/DELETE 应报错或被拦截

这与 pg_publication 作为系统控制表的定位一致。


12. 示例


12.1 创建 publication

CREATE PUBLICATION pub_sales
FOR TABLE public.orders
WITH (ddl = 'table,index,trigger');

含义:

  • publication pub_sales 开启 DDL 同步能力
  • 支持类型:table/index/trigger
  • 系统在 pg_publication.pubddl 中记录总体能力
  • 在 pg_publication_sync 中记录与 public.orders 对应的 DDL 同步控制项

12.2 创建 schema 范围 publication

CREATE PUBLICATION pub_app
FOR TABLES IN SCHEMA app
WITH (ddl = 'table,index,sequence,view,function,type');

含义:

  • publication 在 schema app 范围启用这些 DDL 类型
  • pg_publication_sync 中记录 schema 级同步控制项

12.3 创建 subscription

CREATE SUBSCRIPTION sub_app
CONNECTION 'host=... dbname=... user=...'
PUBLICATION pub_app
WITH (ddl = 'table,index,view,function');

含义:

  • 本地订阅端只接收 table/index/view/function 类别的 DDL
  • pg_subscription.subddl 保存此配置
  • 创建时要求这些类型不超出发布端 pubddl 能力范围

13. 本设计的收益

收敛到“系统表 + 接口”之后,这个方案的收益很明确:

  1. 先冻结 SQL 接口
    后续实现不会反复改语法。

  2. 先冻结 catalog 模型
    后续 DDL 捕获与 apply 逻辑有稳定元数据基础。

  3. 与现有 publication 架构一致
    pg_publication_sync 类似 pg_publication_rel 的扩展控制表,便于理解与维护。

  4. 避免把配置模型和运行时事件模型混在一起
    不再让 pg_publication_sync 承担消息流水职责,语义更清晰。


14. 建议的最终结论

基于你现在收敛后的目标,建议最终采用下面这套思路:

14.1 保留 pubddl/subddl

  • pg_publication.pubddl
  • pg_subscription.subddl

作为用户接口参数落盘位置。

14.2 重定义 pg_publication_sync

把它定义成:

publication 的 DDL 同步控制 catalog 表

而不是 DDL 事件日志表。

14.3 字段设计采用“配置型字段”

不要再用:

  • lsn
  • xid
  • ddl_seqno
  • message_data

这类运行时消息字段。

而应该使用:

  • pubid
  • kind
  • nspid
  • relid
  • objid
  • ddl mask
  • enabled

这类 catalog 控制字段。


这篇还发到了
今日头条 drafted
  目录