逻辑解码数据找回功能

约束

• 解析的WAL日志级别为logical。
• 数据表的复制标识必须为FULL，否则UPDATE和DELETE操作涉及到的被修改行不是全字段。
• WAL日志记录的数据修改操作所对应的业务表，从找回起始位置到目前不能执行VACUUM FULL操作，否则该表VACUUM FULL之前的DML操作不会被数据找回。
• 每条WAL日志不能超过500MB。
• 不支持扩容前的Xlog日志数据找回。
• 集群的每个分片都会生成一个结果文件，多个文件不会进行合并。
• 仅支持归档数据找回，且需要开启归档，若数据尚未归档，则无法通过本接口找回。
• OM_Agent在下载之前会验证本地已用空间是否大于总空间的80%，如果大于则会报错（需要额外空间用于存放解码文件），报错信息为："no enough space left on device, available space must be greater than 20%"。
• 下载失败或解码失败后，都会将下载的WAL日志文件进行清理，如果清理不成功，不会强制结束程序，只会把错误信息记录到DN的日志中。
• 由用户指定数据找回时间，若数据找回起始时间超过系统表GS_TXN_LSN_TIME记录的最大时间、或数据找回终止时间小于GS_TXN_LSN_TIME记录的最小时间，则会报错。
• 如果进行了节点替换，不支持节点替换前的数据找回。
• 不支持同一节点并发调用数据找回接口。
• 只支持直连DN方式的数据找回。
• 旧版本升级提交到新版本时，如果未基线化，则需要执行基线化（执行SELECT gs_logical_dictionary_disabled()和SELECT gs_logical_dictionary_baseline()函数）后才可以使用数据找回功能，且只支持对基线化后新产生的Xlog日志进行数据找回，升级前产生的Xlog日志无法解析。
• 默认支持1年内的数据找回，超过1年的数据将被自动清除。如需找回超过1年的数据，需在清理前调整GUC参数logical_replication_dictionary_retention_time的值。
• 数据找回功能依赖表的元数据信息，如果元数据异常，数据找回可能无法正常执行并报错退出。
• 数据找回功能不支持事务粒度找回，仅支持按行找回。回滚事务会打印事务XID，需人工处理；混合事务中的DML语句找回数据，需人工核对正确性。

操作步骤

1. 使用系统管理员user1连接数据库，password为密码，port为数据库端口号，用户可根据实际情况替换。

   gsql -d postgres -U user1 -W password -p port -r

2. 确认需解码的日志起始与结束位置的LSN以及待解码记录条数。此处以起始LSN“0/AE7C080”、结束LSN“0/AF5F438”为例。
3. 调用pg_logical_get_area_changes执行数据找回。
   • 对于在线日志，请执行如下命令，无需传入日志文件路径。

     gaussdb=# SELECT * FROM pg_logical_get_area_changes('0/AE7C080', '0/AF5F438', 4096, 'mppdb_decoding', NULL, 'enable-ddl', '1', 'skip-empty-xacts', 'true');
      location  |  xid   |                                                                                                       data                                                                                                       
     -----------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
      0/AF5DB40 | 167661 | {"table_name":"public.test","op_type":"INSERT","columns_name":["id","val"],"columns_type":["integer","integer"],"columns_val":["1","1"],"old_keys_name":[],"old_keys_type":[],"old_keys_val":[]}
      0/AF5DD48 | 167661 | COMMIT 167661 (at 2026-09-28 15:53:16.416012+08) CSN 1254
      0/AF5DE40 | 167662 | {"table_name":"public.test","op_type":"UPDATE","columns_name":["id","val"],"columns_type":["integer","integer"],"columns_val":["1","2"],"old_keys_name":["id"],"old_keys_type":["integer"],"old_keys_val":["1"]}
      0/AF5DFA8 | 167662 | COMMIT 167662 (at 2026-09-28 15:53:26.312868+08) CSN 1255
      0/AF5EAA8 | 167663 | COMMIT 167663 (at 2026-09-28 15:53:26.386141+08) CSN 1256
      0/AF5EB50 | 167664 | {"table_name":"public.test","op_type":"DELETE","columns_name":[],"columns_type":[],"columns_val":[],"old_keys_name":["id"],"old_keys_type":["integer"],"old_keys_val":["1"]}
      0/AF5ED60 | 167664 | COMMIT 167664 (at 2026-09-28 15:53:30.863781+08) CSN 1257
      0/AF5F328 | 167665 | COMMIT 167665 (at 2026-09-28 15:53:30.913608+08) CSN 1258
     (8 rows)

   • 对于归档日志，请执行如下命令，需要在options参数中传入归档日志文件夹路径，此时文件夹名应与WAL日志文件前8位同名。

     gaussdb=# SELECT * FROM pg_logical_get_area_changes('0/AE7C080', '0/AF5F438', 4096, 'mppdb_decoding', NULL, 'enable-ddl', '1', 'skip-empty-xacts', 'true', 'xlog_dir', '/data/00000001/');

   以下为各参数的解释，用户可根据实际情况替换。

   • '0/AE7C080'：起始LSN，若无需限制起始位置可置为NULL。归档数据找回若使用xlog_dir参数指定归档日志文件夹路径则不可为NULL。
   • '0/AF5F438'：结束LSN，若无需限制结束位置可置为NULL。归档数据找回若使用xlog_dir参数指定归档日志文件夹路径则不可为NULL。
   • 4096：待解码记录条数。若无需限制待解码记录条数可置为NULL。
   • 'mppdb_decoding'：解码插件。
   • NULL：Xlog文件绝对路径，在线数据找回可置为NULL，归档数据找回若使用xlog_dir参数传入归档日志文件夹名也可置为NULL。
   • 'enable-ddl'、'1'：options参数选项，'1'表示支持DDL语法，'0'表示不支持。归档数据找回若使用xlog_dir参数指定归档日志文件夹路径则需要置为'1'。
   • 'skip-empty-xacts'、'true'：options参数选项，'true'表示跳过空事务信息，'false'表示不跳过。
   • 'xlog_dir'、'/data/00000001/'：options参数选项，仅归档数据找回需要，表示归档日志文件夹路径。

   具体的参数解释、取值范围及约束条件等请参见《参考》中“SQL参考 > 函数和操作符 > 系统管理函数 > 逻辑复制函数”章节中“pg_logical_get_area_changes”函数。

4. 按需落盘或回放找回结果。