PostgreSQL 19: WAIT FOR LSN 命令添加 MODE 选项

PostgreSQL 的高可用架构，一直被广泛应用在企业的各种业务场景中，需要满足各种各样的需要。

特性提交日志

为 WAIT FOR LSN 命令添加 MODE 选项

本次提交为WAIT FOR LSN命令添加了一个可选的MODE选项，该选项通过WITH子句指定待等待的 LSN 类型，语法格式如下：

WAIT FOR LSN '<lsn>' [WITH (MODE '<mode>', TIMEOUT '<timeout>', ...)]

其中mode支持以下取值：

• standby_replay（默认值）：等待备库将 WAL 重放至指定 LSN，
• standby_write：等待备库将 WAL 写入（接收）至指定 LSN，
• standby_flush：等待备库将 WAL 在指定 LSN 处刷盘持久化，
• primary_flush：等待主库上的 WAL 刷盘持久化至指定 LSN。

默认模式为standby_replay，与未指定MODE时的原有行为保持一致。该设计遵循了COPY和EXPLAIN命令的使用模式，即通过 WITH 子句以字符串形式指定选项。

模式名称通过显式命名区分主库与备库操作：

• 备库模式（standby_replay、standby_write、standby_flush）仅可在恢复期间（备库上）使用，
• 主库模式（primary_flush）仅可在主库上使用。

standby_write和standby_flush模式适用于以下场景：应用需确保 WAL 已在备库接收或持久化，但无需等待重放完成。primary_flush模式则支持等待主库上的 WAL 刷盘操作。

特性介绍

在 PostgreSQL 的高可用架构中，WAL 预写日志是保障数据一致性和主从复制的核心：主库的事务会先写入 WAL，再同步到备库，备库通过接收、写入、刷盘、重放 WAL 完成数据同步。此前，WAIT FOR LSN命令仅支持 “等待备库重放完成至指定 LSN” 这一种场景，无法满足不同业务对数据安全性和性能的差异化需求。

PostgreSQL 重构并增强了 LSN 等待机制：底层细分 WAL 流转的关键节点，上层扩展 SQL 语法支持等待模式的选择，让用户可精准控制等待粒度（从主库刷盘到备库重放），既满足金融级数据安全要求，又能灵活平衡性能开销，大幅提升了高可用架构的适配性。

四种等待模式的用途：

用例

某业务平台采用“一主一备”高可用架构，主库数据实时同步到异地备库。要求每次批量订单写入后，确保备库已接收并持久化 WAL，避免主库故障时备库数据不完整，影响业务恢复。

现在需要主库批量写入后，等待备库 WAL 刷盘完成，再结束批量任务，确保灾备数据一致性。

1. 主库执行批量写入并记录 LSN：

-- 批量插入 1000 条订单数据
INSERT INTO orders (order_id, user_id, amount, create_time)
  SELECT generate_series(10001, 11000), 'user_' || floor(random()*1000), 
         floor(random()*1000), CURRENT_TIMESTAMP;

-- 获取批量操作的结束 LSN
SELECT pg_current_wal_insert_lsn();
 pg_current_wal_insert_lsn
---------------------------
 0/306EE20
 (1 row)

2. 备库等待 WAL 刷盘：

-- 备库执行，等待目标 LSN 刷盘完成，超时 60 秒
WAIT FOR LSN '0/306EE20' WITH (MODE 'standby_flush', TIMEOUT '60s');

3. 任务确认：

若等待成功，批量任务结束；若超时，排查主备复制延迟（如网络带宽、备库IO），确保灾备链路正常。

备库 WAL 刷盘完成后，数据已持久化，即使主库彻底故障，备库可直接提升为主库，无订单数据丢失，RTO（目标恢复时间）大幅缩短。

总结

WAIT FOR LSN的增强特性，通过细分 WAL 持久化级别 + 灵活的 SQL 接口，让 PostgreSQL 在数据一致性与性能之间实现了精细化控制。无论是金融场景零数据丢失的要求，还是读写分离的“一致性查询”需求，亦或是高吞吐量场景的“快速灾备确认”，都能找到适配的解决方案。

该特性不仅强化了 PostgreSQL 的高可用架构能力，还降低了用户的使用门槛。无需底层开发，仅通过 SQL 即可实现不同粒度的一致性控制，对于依赖主从复制、灾备架构的企业用户而言，是提升系统稳定性与业务适配性的关键更新。

参考

提交日志：https://git.postgresql.org/pg/commitdiff/49a181b5d634340fcfb7c762c387c03f6405367e