逻辑解码是PostgreSQL 9.4引入的重要能力，它把数据库的事务日志（WAL）转换成结构化的变更事件流，供外部消费者使用。而输出插件（Output Plugin）决定了这些变更以什么格式呈现给消费端。同样是捕获一条UPDATE语句产生的变更，test_decoding给出的是类文本描述，wal2json输出的是标准JSON，pgoutput则走二进制协议路线。理解这几种格式的差异，是做好数据同步、缓存失效、CDC管道设计的第一步。
逻辑解码与输出插件的工作原理
要理解输出格式的差异，先要明白逻辑解码的执行链路。PostgreSQL在写入WAL时，如果配置了wal_level = logical，会在物理日志基础上额外记录逻辑重组所需的信息（比如主键、元组的完整前后镜像）。逻辑解码进程按事务为单位读取WAL，把物理层面的页级变更还原成行级别的逻辑变更，再交给输出插件逐个回调。
输出插件需要实现一组固定的C函数回调，包括pg_decode_startup、pg_decode_begin、pg_decode_change、pg_decode_commit等。每当解码器遇到事务开始、行变更、事务提交这些事件，就会调用对应回调，由插件决定输出什么样的内容。也就是说，解码本身由数据库内核完成，格式化由插件完成，这就是不同插件能产生完全不同输出形态的根本原因。
消费端通过复制协议连接数据库，常见方式有两种：SQL层使用pg_logical_slot_get_changes()系列函数拉取变更，或者像逻辑订阅那样通过流式复制接口持续接收。无论哪种方式，变更都会先经过输出插件的转换，再以插件定义的格式传递出去。
test_decoding：原生自带的调试利器
test_decoding是PostgreSQL源码 contrib 目录下自带的输出插件，安装即用（默认已编译进大多数发行版）。它的输出是易读的文本格式，每条消息描述一个操作，非常适合用来验证逻辑解码是否正常工作、排查复制槽问题，但并不适合作为生产环境的数据同步协议。
创建槽并消费变更的方式非常简单：
-- 确认 wal_level 为 logical 后创建槽
SELECT * FROM pg_create_logical_replication_slot('test_slot', 'test_decoding');
-- 制造一些变更
UPDATE products SET price = price + 10 WHERE id = 1;
-- 拉取变更
SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL);
输出大致形如一段文本，包含事务号、表名、操作的旧值与新值等信息。它的优点是零依赖、直观、便于人工阅读；缺点是格式没有正式规范，字段以空格分隔，解析脆弱，且不支持二进制传输，大字段（如bytea）输出会非常冗长。因此它更多出现在测试、教学和故障诊断场景中。
wal2json：面向集成的JSON格式
wal2json是社区中使用最广泛的第三方输出插件之一，它把每个事务的变更组装成一个JSON对象输出，天然适合与下游的ETL工具、消息队列、脚本消费端对接。它的安装需要单独编译动态库并放入$libdir/plugins目录，之后创建槽时指定插件名为wal2json即可。
wal2json支持两种输出形态：默认按事务输出一个完整JSON，开启format-version 2后可以按行输出流式JSON，每行一条消息，配合actions参数还能过滤只关心的事件类型。典型用法如下：
SELECT * FROM pg_create_logical_replication_slot('json_slot', 'wal2json');
SELECT * FROM pg_logical_slot_get_changes('json_slot', NULL, NULL,
'format-version', '2',
'write-in-chunks', 'true',
'include-lsn', 'true');
输出的JSON会包含schema、table、操作类型、列名与列值的键值对，消费端用任何JSON库都能直接反序列化。相比test_decoding，它的结构化程度高得多，但代价是JSON序列化的CPU开销，在高吞吐场景下文本体积也偏大。如果需要把变更写入Kafka或推送给非PostgreSQL系统，wal2json通常是性价比很高的选择。
pgoutput：为逻辑复制的二进制协议
pgoutput是PostgreSQL 10起内置的输出插件，专门服务于原生的逻辑订阅（logical replication）和第三方工具如Debezium。它不输出人类可读的文本，而是定义了一套二进制协议：B消息表示事务开始，I/U/D表示插入、更新、删除，R表示关系元数据，C表示提交。每条消息经过紧凑编码，传输效率显著高于文本格式。
使用pgoutput必须通过流式复制协议连接，并在START_REPLICATION命令中声明publication和proto_version参数：
-- 创建发布
CREATE PUBLICATION pub_all FOR ALL TABLES;
-- 创建使用 pgoutput 的槽
SELECT * FROM pg_create_logical_replication_slot(
'pgout_slot', 'pgoutput');
客户端（例如psql之外的专用消费程序）连接时指定proto_version和publication_names，数据库就会按协议推送二进制变更流。它的优势是官方维护、协议稳定、性能好，且能利用发布订阅机制按表过滤；劣势是不能用简单的SQL函数直接查看内容，开发消费端需要理解协议细节或借助客户端库，灵活定制输出格式的空间也不如wal2json。
三者对比与选型建议
从功能维度做一个横向对比，可以帮助快速决策：
| 维度 | test_decoding | wal2json | pgoutput |
|---|---|---|---|
| 来源 | 官方内置 | 第三方插件 | 官方内置 |
| 输出格式 | 文本描述 | JSON | 二进制协议 |
| 易解析程度 | 低 | 高 | 需协议客户端 |
| 性能开销 | 中 | 较高 | 低 |
| 典型场景 | 调试验证 | ETL、消息队列 | 逻辑订阅、Debezium |
选型时可以遵循几条原则：如果只是验证逻辑解码配置是否正确，或者在学习阶段观察WAL解码结果，直接用test_decoding，无需额外安装；如果下游是异构系统、脚本或消息中间件，希望拿到自描述的结构化数据，wal2json是最省事的方案；如果构建的是PostgreSQL到PostgreSQL的级联复制，或采用Debezium这类成熟的CDC框架，pgoutput是唯一且正确的选择，它的协议性能和官方支持都有保障。
还要注意一点：无论选哪个插件，逻辑复制槽都会持有未消费的WAL，一旦消费端长期宕机，磁盘可能被撑爆。生产环境务必监控pg_replication_slots视图中的confirmed_flush_lsn与WAL堆积情况，必要时及时删除废弃的槽。选好输出格式只是第一步，稳定运维逻辑解码管道同样重要。
PostgreSQL逻辑解码 wal2json pgoutput修改时间：2026-09-02 16:55:04