暂无图片
暂无图片
2
暂无图片
暂无图片
暂无图片

pg_walex —— WAL 解析为 SQL / undo SQL 工具使用经验

原创 岳麓丹枫 2026-11-07
214

Table of Contents

pg_walex —— WAL 解析为 SQL / undo SQL 工具使用经验

项目地址:https://github.com/shaohuasong-fang/pg_walex
版本:pg_walex 1.2.0
许可证:AGPL-3.0
文档整理日期:2026-11-07
本文分两部分:第一部分为工具学习(原理、参数、构建、同类对比);第二部分为在 192.168.139.12(PolarDB 15 / openEuler 22.03 aarch64)上的实际验证案例与踩坑记录。


第一部分:工具学习

1. 工具定位

pg_walex(PostgreSQL WAL Extractor)是一个离线、无依赖的 WAL 读取器,直接读取 WAL 段文件,把物理 WAL 记录重新还原为可移植、可执行的 SQL 文本。

它从不启动数据库服务、不链接 libpq、不连接任何运行中的实例。这一点是它与 walminer(需要装 PG 扩展)最大的区别:

维度 pg_walex walminer PDU
运行形态 独立 C 二进制 PG 扩展(CREATE EXTENSION) 独立 CLI
是否需实例运行 否 否,但需 PG 环境装扩展 否
输出 SQL / JSON / text / stats SQL + UNDO SQL CSV / 行级恢复
undo 能力 --rollback walminer_undo() WAL 定向行恢复
附带能力 目录重建、TOAST、REST API 时间/LSN 解析 离线元数据重建、碎片扫描
License AGPL-3.0 MIT(XLogMiner) Apache-2.0

典型场景

  • 审计与取证:查清数据库实际发生了哪些变更;
  • 从崩溃、被删除或无法启动的实例中恢复 DML/DDL;
  • 无误操作前的备份、但仍有 WAL 时,生成反向 SQL 回滚;
  • 在没有逻辑复制或在线连接的情况下把变更复制到另一系统;
  • 把 WAL 以 SQL / JSON 送入外部流水线。

2. 核心原理(四层递进)

物理解析  →  目录状态重建  →  可见性判断  →  逻辑化渲染
  1. 物理层:直接解析段文件 → 页头 → 跨页续写(contrecord)→ 记录头 → 块引用(block reference)→ 主数据(main data)。
  2. 完整性/解压:CRC32C 校验;PGLZ / LZ4 / Zstandard 压缩的整页镜像(FPI)自动解压。
  3. 系统目录重建:边解析边用 WAL 中的 pg_class、pg_attribute、pg_namespace、pg_type、pg_index、pg_constraint、pg_enum、pg_sequence、pg_database、pg_authid、pg_attrdef 元组变更,重建"OID X 是 schema.table 第 N 列、类型 T、属于主键"的映射;目录元组也能从 FPI 页中抢救。
  4. 离线目录预热:当 WAL 目录形如 <pgdata>/pg_wal 时,读取同级 base/、global/、pg_xact/,离线判断元组可见性 —— 这是"只保留最近 WAL 窗口,INSERT/UPDATE 仍带完整列名和值"的关键。可用 --pgdata PATH 显式指定,--no-pgdata 关闭。
  5. 行缓存:维护 ctid → 原始元组字节(--max-rows 默认 200000)。因此 wal_level=replica 下前缀/后缀压缩的 UPDATE 也能展开为完整新行 + 按主键定位的 UPDATE;TOAST 窗口外的块按 valueid 从关系文件精确读取。
  6. SQL 逻辑化:堆表变更 → DML,目录变更 → DDL;按 xid 分组包 BEGIN/COMMIT;每事务前输出 -- pg_walex: type=...,xid=...,lsn=...,timestamp=...;跨库输出 psql \connect。
  7. 逆操作:--rollback 为每条 UPDATE/DELETE 追加可回放的逆语句(README 称"一般仅 wal_level=logical 时有效",本次实测 replica 下也生效,见第二部分)。

3. 功能要点

类别 能力
WAL 直读 段文件、页头、contrecord、记录头、块引用、主数据
记录校验 CRC32C(--no-crc 可跳过)
压缩 PGLZ 内置;LZ4/ZSTD 需系统库
目录重建 11 张系统表,含主键、唯一约束、枚举
TOAST 分块收集解压,窗口外按 valueid 直读关系文件
SQL 重建 DML + DDL,按 xid 分组,值按类型渲染,无法渲染输出 NULL + 注释
逆操作 --rollback
输出 sql / json(每行一条原始 WAL 记录)/ text(类 pg_waldump)/ stats
批量装载 --tocopy(manifest + .meta.sql/.data.sql)、--batch-inserts[=N]
REST API /api/v1/*,可选 Bearer Token
实时监控 --serve --monitor,/api/v1/item 返回最新重建 SQL

支持 PostgreSQL 大版本:9 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17 / 18 / 19(帮助文本:9.6..19),可用 --pg-version N 强制指定。

4. 构建

要求:C11 编译器 + POSIX(Linux / macOS);可选 liblz4、libzstd。

git clone https://github.com/shaohuasong-fang/pg_walex.git cd pg_walex make # 自动检测 lz4/zstd make install PREFIX=/usr/local pg_walex --version

跨平台拷贝源码残留 .o 导致 file not recognized 时:

make clean && make

注意:--tocopy / --batch-inserts 不改变默认 SQL 输出;LZ4/ZSTD 只影响 FPI/TOAST 解压,PGLZ 由内部实现。

5. 命令行参数全表

Usage: pg_walex [options] 输入与过滤 -d, --dir PATH WAL 目录(pg_wal) -f, --file PATH 读取单个 WAL 段文件 --pg-version N 强制 PG 大版本(9..19) -s, --start-lsn LSN 从 LSN 开始(X/Y,含);此前会静默预热回放以重建目录/行缓存 -e, --end-lsn LSN 在 LSN 之前停止 -t, --timeline N 时间线(默认最高) -b, --blocksize N WAL 块大小(默认 auto/8192) -S, --segsize N WAL 段大小(默认 auto/16MB) --no-warmup 严格从 --start-lsn 开始扫描,不预热 --pgdata PATH 从离线数据目录播种目录信息 --no-pgdata 不自动检测/读取数据目录 --max-rows N ctid->row 行缓存大小(默认 200000) --no-crc 跳过 WAL 记录 CRC 校验 输出与格式 -F, --format FMT sql | json | text | stats(默认 sql) -o, --output PATH 输出到文件(--tocopy 时为输出目录) --tocopy 输出 COPY 格式:manifest.txt + <schema>.<table>.meta.sql/.data.sql --batch-inserts[=N] 合并同表连续 INSERT 为多 VALUES 语句(默认 N=100) --rollback 为每条 UPDATE/DELETE 追加逆语句(注释标记 rollback) --no-comments 输出纯 SQL,无注释/BEGIN/COMMIT --no-connect 库间不输出 psql \connect --db-oid N 仅输出指定数据库 OID --include-non-sql 为非 SQL 的 WAL 记录添加注释 --include-aborted 报告已中止事务 --logical-messages 显示 pg_logical_emit_message 载荷 -l, --limit N 处理 N 条 WAL 记录后停止 --xid N 只输出指定事务 --table NAME 只输出 NAME([schema.]table)的 DML REST API --serve 启动 RESTful API 服务 --monitor 配合 --serve:后台跟随 WAL,/api/v1/item 暴露最新 SQL --listen ADDR 监听地址(默认 127.0.0.1) --port N 监听端口(默认 8900) --token TOKEN API 要求 Bearer TOKEN 其他 -v, --verbose stderr 详细日志 --version / -h, --help

REST API 端点(从 src/pwe_http.c 源码确认):

/api/v1/health、/api/v1/info、/api/v1/wal-files、/api/v1/records、/api/v1/catalog、/api/v1/stats、/api/v1/sql、/api/v1/rollback、/api/v1/parse、/api/v1/item。

6. 典型用法

W=/path/to/data/pg_wal # 1) 先确认解析范围是否正常 pg_walex --pg-version 15 -d "$W" -F stats # 2) 定位误操作的起始 LSN(事前记录,或由 pg_waldump / 日志推算) pg_walex --pg-version 15 -d "$W" --start-lsn 0/43FCCF78 --table public.t1 -F sql -o forward.sql # 3) 生成 undo pg_walex --pg-version 15 -d "$W" --start-lsn 0/43FCCF78 --table public.t1 --rollback -F sql -o undo_all.sql # 4) 只抽取逆语句执行 grep -A1 '^-- pg_walex: rollback' undo_all.sql | grep -vE '^--|^$' > undo.sql psql -d mydb -f undo.sql

7. 使用前提与限制

  1. WAL 必须还在:段被回收/覆盖后无法恢复,生产必须开 archive_mode 或 pg_receivewal 长期保留。
  2. wal_level 至少 replica,full_page_writes=on 更利于旧值还原。
  3. 表最好有主键/唯一约束:有主键时 UPDATE/DELETE 用主键定位;无主键时用全列 IS NOT DISTINCT FROM,重复行有误伤风险。
  4. 无法渲染的类型输出 NULL + 注释,脚本可执行但值丢失。
  5. --table 只过滤 DML,DDL 不受影响。
  6. -F json 输出的是原始 WAL 记录级 JSON(含 lsn/xid/rmgr/blocks),不是重建后的 SQL。
  7. 项目很新(社区规模小),属第三方工具;AGPL-3.0 对网络服务有源码开放要求,商用需评估。
  8. 作者明确:应急辅助工具,不能替代备份 / PITR。

第二部分:实测经验案例(192.168.139.12)

以下所有命令与输出均为 2026-11-07 在目标环境实际执行的结果。
验证过程未修改任何 PG 参数、未重启实例,wal_level 保持 replica。

8. 实测环境

项目 实际值
主机 / IP openeuler22 / 192.168.139.12
OS openEuler 22.03 (LTS-SP4)
架构 aarch64
数据库 PostgreSQL 15.14(PolarDB 15.14.5.0 build b4011ae4)
psql 客户端 15.18(PolarDB 15.18.5.0 build a55bd4cb debug)—— 与 server 小版本不一致,工具按 server 15 解析
PGDATA /postgresql/tmp_polardb_pg_15_base/data
WAL 目录 $PGDATA/pg_wal
WAL 段大小 1GB(1073741824 字节),文件 000000010000000000000001 —— 非默认 16MB
wal_level replica
full_page_writes on
max_wal_size / min_wal_size 64GB / 5GB
archive_mode 注释状态(默认 off)
编译工具链 gcc 10.3.1 / GNU Make 4.3 / git 2.33.0
压缩库 liblz4.so、libzstd.so 及头文件 /usr/include/lz4.h、/usr/include/zstd.h 均存在
网络 可访问 github.com(HTTP/2 200)

执行前统一设置(重要,每个新 shell 都要重新执行)

下文所有命令都用 $W 代表 WAL 目录。$W 不是工具内置变量,必须自己定义,否则命令会展开成 -d -F stats,报 cannot open WAL directory "-F":

cd /root/pg_walex W=/postgresql/tmp_polardb_pg_15_base/data/pg_wal export W echo "$W" # 确认非空

建议始终给变量加引号 "$W",或用防呆写法让空变量立即报错:

./pg_walex --pg-version 15 -d "${W:?W 未定义}" -F stats

也可以完全不用变量,直接写绝对路径(最不容易出错):

./pg_walex --pg-version 15 -d /postgresql/tmp_polardb_pg_15_base/data/pg_wal -F stats

注意:通过 SSH 工具(或脚本)执行时,每次都是新 shell,上一次 export W=... 不会保留,必须重新定义或写进 ~/.bashrc。

9. 编译过程与第一个坑

cd /root rm -rf pg_walex git clone -q https://github.com/shaohuasong-fang/pg_walex.git cd pg_walex make ./pg_walex --version # pg_walex 1.2.0

编译成功,二进制 922,840 字节。仅有 src/pwe_http.c:961 的 snprintf 截断警告(非致命):
warning: '%s' directive output may be truncated writing up to 1023 bytes into a region of size 256。

坑 1:默认 make 未启用 LZ4/ZSTD

启动 REST API 后 /api/v1/health 返回:

{"status":"ok","tool":"pg_walex","version":"1.2.0", "postgres_versions":[9,10,11,12,13,14,15,16,17,18,19], "pglz":true,"lz4":false,"zstd":false}

但系统库和头文件都在。检查 Makefile 的自动探测:

HAVE_LZ4 := $(shell printf '\#include <lz4.h>\nint main(void){return 0;}\n' | \ $(CC) $(EXTRA_INC) -x c - -o /dev/null $(EXTRA_LIB) -llz4 >/dev/null 2>&1 && echo yes)

手工执行等价探测(正确转义)却是成功的:

printf '#include <lz4.h>\nint main(void){return 0;}\n' | cc -x c - -o /dev/null -llz4 echo $? # 0

即 Makefile 里 \# 经过 make/shell 两层解析后探测失败,导致 PWE_WITH_LZ4 / PWE_WITH_ZSTD 未定义。

规避方式(实测有效):不覆盖 CFLAGS(那样会丢掉 Makefile 内必需参数,实测编译直接失败),而是通过 CC 传宏 + LDLIBS 显式链接:

cd /root/pg_walex make clean make CC="cc -DPWE_WITH_LZ4 -DPWE_WITH_ZSTD" LDLIBS="-llz4 -lzstd -pthread" ldd ./pg_walex | grep -Ei 'lz4|zstd' # liblz4.so.1 => /usr/lib64/liblz4.so.1 # libzstd.so.1 => /usr/lib64/libzstd.so.1

重新编译后 health 变为:

{"pglz":true,"lz4":true,"zstd":true}

影响面:只有当 WAL 的 FPI / TOAST 使用 LZ4 或 ZSTD 压缩时才需要;本环境 wal_compression 为默认(未启用),PGLZ 内置,因此默认编译也能完整解析本次全部数据。但生产若开了 wal_compression=lz4/zstd,必须用上述方式重编,否则压缩页无法解压。

10. 案例 A:正向 SQL 重建

10.1 制造误操作

在测试库 walex_test 执行(脚本 /tmp/walex_test.sql):

select pg_current_wal_lsn(); -- 0/43FCCF78 ← 起点 create table public.t_walex_demo( id int primary key, name text, amount numeric(10,2), memo text, updated_at timestamptz default now()); insert into public.t_walex_demo values (1,'alice',100.50,'first row'), (2,'bob', 200.00,'second row'), (3,'carol',300.25,'third row'); update public.t_walex_demo set amount=999.99, memo='updated by mistake' where id=2; delete from public.t_walex_demo where id=3; select pg_current_wal_lsn(); -- 0/43FD1168 ← 终点

误操作后表内只剩 2 行,bob 的金额被改成 999.99,carol 被删。

10.2 先确认解析范围

cd /root/pg_walex W=/postgresql/tmp_polardb_pg_15_base/data/pg_wal ./pg_walex --pg-version 15 -d "$W" -F stats # 或写成绝对路径:./pg_walex --pg-version 15 -d /postgresql/tmp_polardb_pg_15_base/data/pg_wal -F stats
{ "records": 234606, "transactions": 10, "statements": 42938, "insert": 42771, "update": 60, "delete": 1, "ddl": 106, "first_lsn": "0/40000028", "last_lsn": "0/43FD1140", "rmgr": {"XLOG":5171,"Transaction":763,"Heap":94677,"Btree":114165, ...} }

关键验证:段大小自动识别。对比默认参数与显式 -S 1073741824:

cd /root/pg_walex W=/postgresql/tmp_polardb_pg_15_base/data/pg_wal ./pg_walex --pg-version 15 -d "$W" -F stats ./pg_walex --pg-version 15 -S 1073741824 -d "$W" -F stats

两次输出的 records 都是 234606 条,完全一致(该数值会随后续 WAL 写入增长,比对时看"是否相等"而非绝对值)。

复制命令时不要带行尾的中文注释;# 之后虽是 shell 注释,但混在命令里容易误复制。

/api/v1/info 也确认:

{"dir":".../pg_wal","version":15,"timeline":1, "segment_size":1073741824,"first_lsn":"0/40000000","last_lsn":"0/80000000", "segments":["000000010000000000000001"]}

经验:PolarDB 的 1GB WAL 段无需手工指定 -S,工具 auto 检测正确。这是本环境最需要担心但结果最好的一点。

10.3 提取正向 SQL

./pg_walex --pg-version 15 -d "$W" \ --start-lsn 0/43FCCF78 --table public.t_walex_demo \ -F sql --no-connect -o /root/walex_out.sql2

输出 30 行 / 1293 字节,完整还原:

-- pg_walex: type=create,xid=763,lsn=0/43FCCFD8,timestamp=2026-11-07 13:05:55.529812+00 BEGIN; CREATE SCHEMA IF NOT EXISTS public; CREATE TABLE public.t_walex_demo ( id int4 NOT NULL, name text, amount numeric(10,2), memo text, updated_at timestamptz, PRIMARY KEY (id) ); COMMIT; -- pg_walex: type=insert,xid=764,lsn=0/43FD0E18,... BEGIN; INSERT INTO public.t_walex_demo (id, name, amount, memo, updated_at) VALUES (1, 'alice', '100.50'::numeric, 'first row', '2026-11-07 13:05:55.541117+00'::timestamptz); INSERT INTO public.t_walex_demo (id, name, amount, memo, updated_at) VALUES (2, 'bob', '200.00'::numeric, 'second row', ...); INSERT INTO public.t_walex_demo (id, name, amount, memo, updated_at) VALUES (3, 'carol', '300.25'::numeric, 'third row', ...); COMMIT; -- pg_walex: type=update,xid=765,lsn=0/43FD1078,... BEGIN; UPDATE public.t_walex_demo SET amount = '999.99'::numeric, memo = 'updated by mistake' WHERE id IS NOT DISTINCT FROM 2; COMMIT; -- pg_walex: type=delete,xid=766,lsn=0/43FD1108,... BEGIN; DELETE FROM public.t_walex_demo WHERE id IS NOT DISTINCT FROM 3; COMMIT;

观察点

  • DDL(CREATE TABLE,含主键)也能重建;
  • numeric 渲染为 '100.50'::numeric,timestamptz 带显式 cast;
  • UPDATE / DELETE 自动用主键定位(WHERE id IS NOT DISTINCT FROM 2),不是全表扫描式条件;
  • 事务按 xid 分组,带 BEGIN/COMMIT 与 lsn/timestamp 注释;
  • 注释里时间戳是 UTC(+00),而库内显示 +08,比对时注意时区。

11. 案例 B:undo SQL(本次最重要的发现)

README 写"--rollback 一般仅 wal_level=logical 时有效",但本环境 wal_level=replica:

./pg_walex --pg-version 15 -d "$W" \ --start-lsn 0/43FCCF78 --table public.t_walex_demo --rollback \ -F sql --no-connect -o /root/walex_undo_replica.sql

undo 语句照样生成了:

-- pg_walex: type=update,xid=765,lsn=0/43FD1078,... BEGIN; UPDATE public.t_walex_demo SET amount = '999.99'::numeric, memo = 'updated by mistake' WHERE id IS NOT DISTINCT FROM 2; -- pg_walex: rollback,xid=765,lsn=0/43FD1078,... UPDATE public.t_walex_demo SET amount = '200.00'::numeric, memo = 'second row' WHERE id IS NOT DISTINCT FROM 2; COMMIT; -- pg_walex: type=delete,xid=766,lsn=0/43FD1108,... BEGIN; DELETE FROM public.t_walex_demo WHERE id IS NOT DISTINCT FROM 3; -- pg_walex: rollback,xid=766,lsn=0/43FD1108,... INSERT INTO public.t_walex_demo (id, name, amount, memo, updated_at) VALUES (3, 'carol', '300.25'::numeric, 'third row', '2026-11-07 13:05:55.541117+00'::timestamptz); COMMIT;

分析原因:full_page_writes=on 时的 FPI + 工具的行缓存(ctid → 原始元组字节)已经保留了旧行,压缩 UPDATE 也能展开,因此不必依赖 logical 级额外信息。

11.1 抽取出逆语句并真实回放

grep -A1 '^-- pg_walex: rollback' /root/walex_undo_replica.sql \ | grep -vE '^--|^$' > /tmp/undo.sql chmod 644 /tmp/undo.sql psql -d walex_test -f /tmp/undo.sql

/tmp/undo.sql 内容:

UPDATE public.t_walex_demo SET amount = '200.00'::numeric, memo = 'second row' WHERE id IS NOT DISTINCT FROM 2; INSERT INTO public.t_walex_demo (id, name, amount, memo, updated_at) VALUES (3, 'carol', '300.25'::numeric, 'third row', '2026-11-07 13:05:55.541117+00'::timestamptz);

回放前

id | name | amount | memo ----+-------+--------+-------------------- 1 | alice | 100.50 | first row 2 | bob | 999.99 | updated by mistake

执行:UPDATE 1 / INSERT 0 1

回放后

id | name | amount | memo ----+-------+--------+------------ 1 | alice | 100.50 | first row 2 | bob | 200.00 | second row 3 | carol | 300.25 | third row

结论:数据完全恢复到误操作前状态。这是本工具在 wal_level=replica 生产默认配置下可用性的关键证据。但不要盲目相信:若旧行不在行缓存且无 FPI(例如 WAL 窗口被截断、表做过 VACUUM FULL / TRUNCATE),逆语句可能缺失或不准,务必先在副本演练。

12. 案例 C:无主键表

create table public.t_walex_nopk(a int, b text); insert into public.t_walex_nopk values (10,'x'),(11,'y'); update public.t_walex_nopk set b='changed' where a=10; delete from public.t_walex_nopk where a=11;

解析结果(含 --rollback):

UPDATE public.t_walex_nopk SET b = 'changed' WHERE a IS NOT DISTINCT FROM 10 AND b IS NOT DISTINCT FROM 'x'; -- pg_walex: rollback,xid=771,... UPDATE public.t_walex_nopk SET b = 'x' WHERE a IS NOT DISTINCT FROM 10 AND b IS NOT DISTINCT FROM 'changed'; DELETE FROM public.t_walex_nopk WHERE a IS NOT DISTINCT FROM 11 AND b IS NOT DISTINCT FROM 'y'; -- pg_walex: rollback,xid=772,... INSERT INTO public.t_walex_nopk (a, b) VALUES (11, 'y');

经验:无主键时退化为全列 IS NOT DISTINCT FROM 定位。若表存在完全相同的重复行,UPDATE/DELETE 的逆语句会命中多行,undo 不精确。生产表务必建主键或唯一约束。

13. 案例 D:TOAST 大字段

create table public.t_walex_toast(id int primary key, payload text); insert into public.t_walex_toast select 1, (select string_agg(md5(i::text),'') from generate_series(1,1000) i); update public.t_walex_toast set payload = payload || '_END' where id=1; select length(payload) from public.t_walex_toast; -- 32004

用不可压缩的 32000 字符十六进制串触发外置 TOAST。解析结果:

语句 SQL 中还原的 payload 长度 尾部
原始 INSERT 32000 dc4dd82eb3c5
正向 UPDATE 32004 d82eb3c5_END
rollback UPDATE 32000 dc4dd82eb3c5

库中当前值:32004 | d82eb3c5_END,完全一致。

经验:TOAST 分块(含 WAL 窗口外按 valueid 直读关系文件)在 PolarDB 15 上工作正常,大字段可完整还原并正确生成 undo。整个输出文件 97,878 字节,长行处理时注意不要直接 cat 刷屏。

14. 案例 E:端到端重放到另一个库

把案例 A 生成的正向 SQL 完整回放到新建库 walex_replay:

psql -c 'create database walex_replay' psql -d walex_replay -f /tmp/walex_out.sql psql -d walex_replay -c 'select * from public.t_walex_demo order by id'
CREATE DATABASE / BEGIN / INSERT 0 1 x3 / UPDATE 1 / DELETE 1 / COMMIT id | name | amount | memo ----+-------+--------+-------------------- 1 | alice | 100.50 | first row 2 | bob | 999.99 | updated by mistake

与"误操作后"的源库状态完全一致,证明生成的 SQL 可直接用于把变更复制到另一系统。

坑 2:输出文件权限

第一次直接 psql -f /root/walex_out.sql 报:

psql: error: /root/walex_out.sql: Permission denied

原因:工具以 root 运行、输出落在 /root(目录 700),postgres 用户读不到。

处理:

cp /root/walex_out.sql /tmp/walex_out.sql && chmod 644 /tmp/walex_out.sql su - postgres -c 'psql -d walex_replay -f /tmp/walex_out.sql'

建议 -o 直接输出到 /tmp 或 postgres 可读目录,省一步。

15. 案例 F:--tocopy 批量装载

mkdir -p /root/walex_copy ./pg_walex --pg-version 15 -d "$W" --start-lsn 0/43FCCF78 \ --table public.t_walex_demo --tocopy -o /root/walex_copy --no-connect

生成:

manifest.txt public.t_walex_demo.meta.sql public.t_walex_demo.data.sql public.t_walex_demo.data2.sql public.t_walex_demo_28279.meta.sql / .data.sql public.t_walex_nopk.meta.sql public.t_walex_toast.meta.sql

manifest.txt 用 \i 引入建表、用 \copy 装载数据:

-- replay with: cd /root/walex_copy && psql -d <dbname> -f manifest.txt BEGIN; CREATE SCHEMA IF NOT EXISTS public; \i 'public.t_walex_demo.meta.sql' COMMIT; \copy public.t_walex_demo (id, name, amount, memo, updated_at) FROM 'public.t_walex_demo.data.sql'; ... UPDATE / DELETE 语句 ...

经验:--table 只过滤 DML,DDL 不过滤 —— 上面仍生成了 t_walex_nopk、t_walex_toast 的 .meta.sql。回放前需人工检查 manifest,剔除非目标表。

16. 案例 G:REST API

./pg_walex --pg-version 15 -d "$W" --serve --port 8900 --listen 127.0.0.1
curl -s http://127.0.0.1:8900/api/v1/health # {"code":0,...,"data":{"status":"ok","version":"1.2.0","pglz":true,"lz4":false,"zstd":false}} curl -s http://127.0.0.1:8900/api/v1/info # {"code":0,...,"data":{"dir":".../pg_wal","version":15,"timeline":1, # "segment_size":1073741824,"first_lsn":"0/40000000","last_lsn":"0/80000000", # "segments":["000000010000000000000001"]}} curl -s http://127.0.0.1:8900/api/v1/stats # {"records":236284,"transactions":23,"statements":42955, # "insert":42778,"update":64,"delete":3,"ddl":110, ...} curl -s 'http://127.0.0.1:8900/api/v1/rollback?start_lsn=0/43FCCF78' | tail # 直接返回带 rollback 注释的 SQL 文本

经验:--serve 适合把 WAL 挖掘接进自动化流程;/api/v1/rollback 可直接取 undo SQL。
后台进程要显式 kill:job-start 返回的 pid 是包装 shell,真正服务进程 pid 不同(实测 9055 → 9058、11040 → 11043),需 pgrep -af pg_walex 找出来再 kill。

17. 其他参数验证

命令 结果
--xid 765 --no-comments -F sql 只输出一条裸 UPDATE ...,注释/BEGIN/COMMIT 全去掉
--no-pgdata 本例输出与默认完全一致(因为 WAL 窗口内包含完整 CREATE TABLE 的 catalog 变更,工具能自行重建目录)
-F json 输出的是原始 WAL 记录,如 {"lsn":"0/43FCCF78","xid":763,"rmgr":"Standby","info":"RUNNING_XACTS","blocks":[]},不是重建后的 SQL
--start-lsn 会先静默预热回放最早可用 WAL 重建目录/行缓存,之后才输出 SQL —— 这是表名、列、主键正确的原因

关于 --no-pgdata 的边界:本次成功是因为 DDL 恰好在 WAL 窗口内。若只保留最近 WAL、而 CREATE TABLE 在窗口外,则必须依赖 <pgdata> 的 base//global/ 预热,否则表名/列名会退化为 OID。生产上不要随便加 --no-pgdata。

坑 3:回放会污染 WAL

在同一集群上做端到端回放(案例 E)和 undo 回放(案例 B)本身又产生了新事务。实测 last_lsn 从 0/43FD1140 涨到 0/44413090,stats 里 transactions 从 10 变 23,并出现 xid 767/768、779/780 这些"回放事务",--rollback 输出里也混进了它们。

建议:

  1. 误操作后立即固定/归档一段 WAL(拷贝 pg_wal 或 archive 目录到只读位置)再分析;
  2. 回放验证放到独立实例或停库后的副本上做;
  3. 分析时用 -s/-e 明确 LSN 窗口,或用 --xid 精确过滤,避免把回放事务算进去。

18. 本环境推荐操作 SOP

# 0) 事前(最重要):开启 WAL 归档,保证窗口 # archive_mode=on / archive_command='cp %p /archive/%f' # 并养成记录 pg_current_wal_lsn() 的习惯 # 1) 编译(本环境建议强制启用 LZ4/ZSTD) git clone https://github.com/shaohuasong-fang/pg_walex.git /root/pg_walex cd /root/pg_walex make clean && make CC="cc -DPWE_WITH_LZ4 -DPWE_WITH_ZSTD" LDLIBS="-llz4 -lzstd -pthread" ./pg_walex --version W=/postgresql/tmp_polardb_pg_15_base/data/pg_wal # 2) 确认能解析(会看到 segment_size 是否识别正确) ./pg_walex --pg-version 15 -d "$W" -F stats curl -s http://127.0.0.1:8900/api/v1/info # 若开了 --serve # 3) 用误操作起始 LSN + 表名提取正向 SQL ./pg_walex --pg-version 15 -d "$W" -s 0/43FCCF78 \ --table public.t_walex_demo --no-connect -F sql -o /tmp/forward.sql # 4) 生成 undo ./pg_walex --pg-version 15 -d "$W" -s 0/43FCCF78 \ --table public.t_walex_demo --rollback --no-connect -F sql -o /tmp/undo_all.sql # 5) 只取逆语句,人工逐条 review grep -A1 '^-- pg_walex: rollback' /tmp/undo_all.sql | grep -vE '^--|^$' > /tmp/undo.sql cat /tmp/undo.sql # 6) 先在副本库演练,核对行数/关键字段后再上生产 chmod 644 /tmp/undo.sql psql -d <验证库> -f /tmp/undo.sql

19. 实测结论

结论 证据
PolarDB 15(aarch64)可用 全部 DML/DDL 正确重建,无需改任何 PG 参数、无需重启
1GB WAL 段自动识别 默认与 -S 1073741824 的 stats 完全一致;/api/v1/info 返回 segment_size:1073741824
wal_level=replica 下 --rollback 生效 生成旧值 UPDATE 与 INSERT,回放后数据完全恢复
主键定位 有主键用 WHERE pk IS NOT DISTINCT FROM n;无主键退化为全列条件
TOAST 完整 32000/32004 字符大字段正向与 undo 值均与库中一致
端到端可重放 新库回放后与源库状态一致
默认编译未启用 LZ4/ZSTD health 为 false,需 make CC=... LDLIBS=... 重编(本环境数据未受影响)
回放会污染 WAL LSN 与事务数增长,需固定 WAL 窗口 / 独立实例演练

风险提示

  • 工具很新(社区规模小),本验证只覆盖 PolarDB 15 的标准 Heap/Btree/TOAST 记录,未覆盖 PolarDB 特有 WAL 记录类型与全部数据类型;
  • 依赖 WAL 未被回收、行缓存/FPI 能覆盖旧行;VACUUM FULL / TRUNCATE / 段复用后结果不可靠;
  • undo 语句必须人工 review 并在副本演练后再执行,尤其无主键表与重复行场景;
  • AGPL-3.0 合规、以及"不能替代备份 / PITR"这两点必须记住 —— 真正保命的仍是 pgBackRest/Barman + WAL 归档。

附录:本次实测产物清单(便于复现)

路径 说明
/root/pg_walex/ git clone 的源码与编译产物 pg_walex
/tmp/walex_test.sql 案例 A 的 DDL + INSERT/UPDATE/DELETE 脚本
/tmp/walex_test2.sql 无主键表 + TOAST 大字段脚本
/root/walex_out.sql 案例 A 正向 SQL(30 行 / 1293 字节)
/root/walex_undo_replica.sql 案例 B 带 --rollback 的 SQL
/tmp/undo.sql 抽取出的 2 条逆语句(已真实执行,数据恢复成功)
/root/walex_out.json -F json 的原始 WAL 记录输出
/root/walex_out2.sql 案例 C/D 含 TOAST 的输出(97,878 字节)
/root/walex_nopgdata.sql --no-pgdata 对比输出
/root/walex_copy/ --tocopy 的 manifest 与 .meta.sql/.data.sql
数据库 walex_test 误操作 + undo 回放的测试库
数据库 walex_replay 端到端重放验证库

验证后环境状态

  • PG 实例保持运行(PID 987),未改任何参数、未重启;
  • 测试库 walex_test / walex_replay 与 5 张测试表保留,可按需要 drop database 清理;
  • 所有 --serve 后台进程已 kill;
  • pg_walex 二进制为强制启用 LZ4/ZSTD 后重编的版本(health 返回 lz4:true, zstd:true)。

清理脚本(可选)

su - postgres -c "psql -c 'drop database if exists walex_replay'" su - postgres -c "psql -c 'drop database if exists walex_test'" rm -rf /root/pg_walex /root/walex_copy /root/walex_*.sql /root/walex_*.json rm -f /tmp/walex_test*.sql /tmp/walex_out.sql /tmp/undo.sql

常见问题(实测补充)

Q1:pg_walex: cannot open WAL directory "-F": No such file or directory

现象(2026-11-07 实际复现):

[root@openeuler22 pg_walex]# ./pg_walex --pg-version 15 -d $W -F stats pg_walex: cannot open WAL directory "-F": No such file or directory

根因:$W 未定义、展开为空字符串。命令行变成:

./pg_walex --pg-version 15 -d -F stats

选项 -d 需要一个目录参数,于是把紧随其后的 -F 当成目录名吃掉了,工具尝试打开名为 -F 的目录,报"No such file or directory"。这不是 WAL 目录不存在,也不是权限问题。

诊断:

echo "W=[$W]" # 输出 W=[] 即为空

三种修法:

# 1) 先定义变量(每个新 shell 都要重新执行) cd /root/pg_walex W=/postgresql/tmp_polardb_pg_15_base/data/pg_wal ./pg_walex --pg-version 15 -d "$W" -F stats # 2) 直接写绝对路径(最稳,推荐复制这条) ./pg_walex --pg-version 15 -d /postgresql/tmp_polardb_pg_15_base/data/pg_wal -F stats # 3) 防呆:变量为空时立即报错,而不是把 -F 吃掉 ./pg_walex --pg-version 15 -d "${W:?W 未定义}" -F stats

为什么我第一次跑没问题:验证时每条命令都在同一个 shell 里先 W=... 再执行;而文档里的案例命令省略了这一步,单独复制就会失败。已在第 8 节补充"执行前统一设置",并把全文裸 $W 改为 "$W"。

同理,任何 -d / -o / --pgdata 这类"需要值"的选项后面若跟空变量,都会把下一个选项误当成值。遇到 cannot open ... "-X"、cannot open ... "--format" 之类的怪异报错,第一反应检查变量是否为空。

「喜欢这篇文章,您的关注和赞赏是给作者最好的鼓励」
关注作者
【版权声明】本文为墨天轮用户原创内容,转载时必须标注文章的来源(墨天轮),文章链接,文章作者等基本信息,否则作者和墨天轮有权追究责任。如果您发现墨天轮中有涉嫌抄袭或者侵权的内容,欢迎发送邮件至:contact@modb.pro进行举报,并提供相关证据,一经查实,墨天轮将立刻删除相关内容。

评论