Table of Contents
- pg_walex —— WAL 解析为 SQL / undo SQL 工具使用经验
- 第一部分:工具学习
- 第二部分:实测经验案例(192.168.139.12)
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. 核心原理(四层递进)
物理解析 → 目录状态重建 → 可见性判断 → 逻辑化渲染
- 物理层:直接解析段文件 → 页头 → 跨页续写(
contrecord)→ 记录头 → 块引用(block reference)→ 主数据(main data)。 - 完整性/解压:CRC32C 校验;PGLZ / LZ4 / Zstandard 压缩的整页镜像(FPI)自动解压。
- 系统目录重建:边解析边用 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 页中抢救。 - 离线目录预热:当 WAL 目录形如
<pgdata>/pg_wal时,读取同级base/、global/、pg_xact/,离线判断元组可见性 —— 这是"只保留最近 WAL 窗口,INSERT/UPDATE 仍带完整列名和值"的关键。可用--pgdata PATH显式指定,--no-pgdata关闭。 - 行缓存:维护
ctid → 原始元组字节(--max-rows默认 200000)。因此wal_level=replica下前缀/后缀压缩的 UPDATE 也能展开为完整新行 + 按主键定位的 UPDATE;TOAST 窗口外的块按 valueid 从关系文件精确读取。 - SQL 逻辑化:堆表变更 → DML,目录变更 → DDL;按 xid 分组包
BEGIN/COMMIT;每事务前输出-- pg_walex: type=...,xid=...,lsn=...,timestamp=...;跨库输出 psql\connect。 - 逆操作:
--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. 使用前提与限制
- WAL 必须还在:段被回收/覆盖后无法恢复,生产必须开
archive_mode或pg_receivewal长期保留。 wal_level至少replica,full_page_writes=on更利于旧值还原。- 表最好有主键/唯一约束:有主键时 UPDATE/DELETE 用主键定位;无主键时用全列
IS NOT DISTINCT FROM,重复行有误伤风险。 - 无法渲染的类型输出
NULL+ 注释,脚本可执行但值丢失。 --table只过滤 DML,DDL 不受影响。-F json输出的是原始 WAL 记录级 JSON(含 lsn/xid/rmgr/blocks),不是重建后的 SQL。- 项目很新(社区规模小),属第三方工具;AGPL-3.0 对网络服务有源码开放要求,商用需评估。
- 作者明确:应急辅助工具,不能替代备份 / 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 输出里也混进了它们。
建议:
- 误操作后立即固定/归档一段 WAL(拷贝
pg_wal或 archive 目录到只读位置)再分析;- 回放验证放到独立实例或停库后的副本上做;
- 分析时用
-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"之类的怪异报错,第一反应检查变量是否为空。




