PostgreSQL 三类存储完整性故障:TOAST 缺块、B-tree 零页与业务字段恢复
文中的主机、库名、Schema、表名、索引名、OID、主键、时间、数据量、连接参数和文件路径均已泛化。
SQL 中的示例对象必须替换成实际对象;
不能直接在生产库执行。
最近遇到的三次 PostgreSQL 存储完整性故障的处理记录:
pg_statistic的 TOAST 值缺块,业务 SQL 在规划阶段失败;- 分区叶子表的唯一 B-tree 索引出现零页,新增数据失败;
- 业务表大字段的 TOAST chunk 丢失,查询和
pg_dump都无法完整读取。
处理这类问题时,最重要的不是马上跑 REINDEX 或 VACUUM FULL,而是先回答两个问题:
- 损坏的到底是统计信息、索引,还是业务数据?
- 损坏内容能否从其他数据重建?
这两个答案决定了后面的修复方式。
案例一:pg_statistic TOAST 缺块
故障现象
某条业务 UPDATE 还没进入正常执行,就在规划/绑定阶段报错:
ERROR: missing chunk number 0 for toast value ... in pg_toast_<oid>
第一反应往往是“业务表里某个大字段坏了”。但把报错中的 TOAST 表映射回 owner 后,发现它属于 pg_catalog.pg_statistic。
SELECT c.oid,
c.oid::regclass AS owner_relation,
c.reltoastrelid::regclass AS toast_relation
FROM pg_catalog.pg_class AS c
WHERE c.reltoastrelid = 'pg_toast.pg_toast_<oid>'::regclass;
这一步很关键。pg_statistic 保存优化器使用的列统计信息,其中的 MCV、直方图边界等数组也可能进入 TOAST。业务 SQL 在生成计划时要读这些统计值,所以即使 SQL 没有选取任何大字段,也会被损坏的统计信息拦住。
怎样缩小范围
分区表的统计信息通常分布在父表和多个叶子分区上。直接对整张表做大范围维护,既扩大锁和 I/O,也会破坏现场。
排查时先确定哪个叶子分区拥有统计记录,再对 staattnum 做范围切分。因为一条 SELECT 遇到第一个坏值就会中止,可以通过二分法把坏统计列缩小到很小的范围。
测试时要显式解码统计槽,只查目录行数不够:
SELECT staattnum,
stakind1,
stakind2,
stavalues1::text,
stavalues2::text,
stanumbers1::text,
stanumbers2::text
FROM pg_catalog.pg_statistic
WHERE starelid = 'schema_name.partition_name'::regclass
AND staattnum BETWEEN 1 AND 16;
如果该范围报 missing chunk,就继续缩小;正常返回则检查另一半。
为什么普通 ANALYZE 没有直接修好
对准确的叶子分区执行 ANALYZE,采样阶段完成了,但替换旧统计记录时又读到了损坏的 TOAST 值,命令整体回滚。
所以不能只看 ANALYZE VERBOSE 前面的采样输出。必须确认命令最终成功,并检查 pg_stat_all_tables.last_analyze 和损坏统计槽的解码结果。
最终修复
pg_statistic 是可再生数据。精确定位目标叶子分区后,可在受控事务内删除该对象的旧统计记录,紧接着重新 ANALYZE:
BEGIN;
DELETE FROM pg_catalog.pg_statistic
WHERE starelid = 'schema_name.partition_name'::regclass;
ANALYZE VERBOSE schema_name.partition_name;
COMMIT;
这是针对“已精确定位的 pg_statistic 损坏”的例外处置,需要超级用户权限和完整审批。它不是 missing chunk 的通用修复模板,更不能照搬到业务表上。
修复后至少要检查:
ANALYZE最终成功;last_analyze更新;- 所有
stavaluesN/stanumbersN都能转成文本; - 原业务 SQL 能正常生成计划;
- 日志不再出现同类 value ID。
案例二:B-tree 索引出现零页
故障现象
一条 INSERT 在维护分区叶子表的唯一索引时失败:
ERROR: index "..." contains unexpected zero page at block ... HINT: Please REINDEX it.
B-tree 页应该有合法页头和索引内容。“unexpected zero page”表示访问到的块呈现为未初始化或异常全零状态,它不再符合 B-tree 结构要求。
pg_index.indisvalid=true 和 indisready=true 并不能反证物理页正常。这两个标志是目录状态,PostgreSQL 不会因为某个索引块损坏就自动把索引标记为 invalid。
先确认损坏范围
处理前要保存以下信息:
SELECT i.indexrelid::regclass AS index_name,
i.indrelid::regclass AS table_name,
i.indisunique,
i.indisprimary,
i.indisvalid,
i.indisready,
pg_get_indexdef(i.indexrelid) AS index_definition
FROM pg_catalog.pg_index AS i
WHERE i.indexrelid = 'schema_name.index_name'::regclass;
还要核对:
- 该索引是普通索引、主键还是唯一约束的依托索引;
- 是分区父索引还是真正存储数据的叶子索引;
- 同表其他索引和同父索引下其他叶子是否报错;
- 源堆表能否完整读取;
- 唯一键是否存在重复值;
- 当前锁等待、磁盘剩余空间和 I/O 能否支撑重建。
如果堆表本身也出现 invalid page、checksum failure 或读取错误,就不能把问题当成单纯索引损坏。
为什么 REINDEX 有效
索引是堆表的派生结构。REINDEX INDEX 不需要从旧的损坏索引中读键值,而是扫描堆表,重新生成一套 B-tree,再替换旧索引。
在确认源堆表可读、唯一键无重复、空间足够后,只重建报错的叶子索引:
REINDEX INDEX schema_name.leaf_index_name;
普通 REINDEX 锁影响明确,但路径简单,在已经损坏的索引上通常比盲目追求并发重建更稳妥。是否能使用 REINDEX CONCURRENTLY 还取决于 PostgreSQL 版本、索引状态和兼容内核的实现,不应在故障现场临时试验。
重建后检查:
- 索引的
relfilenode已变化; - 索引仍挂接在正确的分区父索引下;
- 唯一/主键约束仍有效;
- 原 INSERT 路径恢复;
- 安装了
amcheck时,对新索引执行bt_index_check; - 日志中没有在其他索引上出现新的零页。
SELECT bt_index_check(
'schema_name.leaf_index_name'::regclass,
true
);
单个索引重建成功,只代表这个派生对象恢复了。如果同一实例在很短时间内又出现 TOAST 缺块或另一个索引零页,应该立即上升为实例级完整性事件,继续查存储、文件系统、宿主机、异常重启、HA 切换和内核缺陷。
案例三:业务表 TOAST chunk 丢失
从 pg_dump 报错开始
一次逻辑备份在 COPY 业务日志表时失败:
pg_dump: error: Dumping the contents of table "..." failed ERROR: missing chunk number 0 for toast value ... in pg_toast_<oid>
该表规模较大,包含请求参数、响应内容和错误信息等多个大字段。处理目标不是跳过整张表,而是找到引用缺失 TOAST value 的准确字段和业务行。
先判断是索引问题还是真缺块
每个外置 TOAST 值都会被拆成多个 chunk,TOAST 表上的唯一索引键为 (chunk_id, chunk_seq)。
如果只通过索引查不到 chunk_id,还不能说明数据真的没了,因为也可能是 TOAST 索引漏项。必须分别走索引和强制顺序扫描。
索引路径:
BEGIN READ ONLY;
SET LOCAL enable_seqscan = off;
SELECT ctid, chunk_id, chunk_seq
FROM pg_toast.pg_toast_<oid>
WHERE chunk_id = '<value_id>'::oid
ORDER BY chunk_seq;
ROLLBACK;
堆表路径:
BEGIN READ ONLY;
SET LOCAL enable_indexscan = off;
SET LOCAL enable_bitmapscan = off;
EXPLAIN (COSTS OFF)
SELECT ctid, chunk_id, chunk_seq
FROM pg_toast.pg_toast_<oid>
WHERE chunk_id = '<value_id>'::oid;
SELECT ctid, chunk_id, chunk_seq
FROM pg_toast.pg_toast_<oid>
WHERE chunk_id = '<value_id>'::oid
ORDER BY chunk_seq;
ROLLBACK;
判断标准很直接:
| 索引扫描 | 顺序扫描 | 结论 |
|---|---|---|
| 0 行 | 有 chunk | TOAST 索引可能漏项,评估 REINDEX |
| 0 行 | 0 行 | chunk 实际缺失,REINDEX 不能恢复数据 |
| 都有记录但序号不连续 | 都有记录但序号不连续 | 部分 chunk 丢失 |
本案两种扫描均为 0 行,因此没有对 TOAST 索引做无效的 REINDEX。
不读坏字段,如何找到坏行
大表上直接 SELECT * 既会很快命中坏值,也难以知道是哪一行。有效做法是把“定位”和“完整读取”分开。
先查结构,确定:
- 哪些列可能进入 TOAST;
- 主键是什么;
- 有没有可用于切片的时间索引;
- 坏列是否参与索引、触发器、检查约束和逻辑复制行标识。
SELECT a.attnum,
a.attname,
format_type(a.atttypid, a.atttypmod) AS data_type,
a.attnotnull,
a.attstorage
FROM pg_catalog.pg_attribute AS a
WHERE a.attrelid = 'schema_name.audit_log'::regclass
AND a.attnum > 0
AND NOT a.attisdropped
ORDER BY a.attnum;
再按候选大字段分开检查。大范围排查可以用首字符触发首块读取,不返回业务正文:
SELECT count(substring(request_payload::text FROM 1 FOR 1))
FROM schema_name.audit_log
WHERE event_time >= timestamp 'YYYY-MM-DD 00:00:00'
AND event_time < timestamp 'YYYY-MM-DD 00:00:00'
AND request_payload IS NOT NULL;
时间范围按“月 → 周 → 日 → 小时 → 10 分钟”缩小。某个范围正常后就不再重复扫描,只继续细分报错范围。
到少量候选行后,每个主键用独立 SQL 完整读取字段:
SELECT record_id,
md5(request_payload::text) AS payload_md5
FROM schema_name.audit_log
WHERE record_id = '<candidate_id>';
substring(... FROM 1 FOR 1) 适合缩小范围,但只能保证读到所需的部分,不能代替完整值验证。最终要用 md5(column::text) 或同等方式强制读完整个值。
一个容易被忽略的陷阱:定位索引也可能不完整
本案在定位目标行时遇到过一个反常现象:
- 主键查询能找到记录;
- 主键加精确时间条件时,规划器选择时间索引,结果反而是 0 行。
这说明时间索引至少存在漏项迹象。如果继续把它当成“全量完整性扫描”的路径,坏行会被跳过,得到假阴性结果。
所以,修复事务最终只用主键锁定行,修复后的全表检查则显式禁用普通和位图索引扫描。出现过漏项迹象的索引还需要单独用 amcheck 或重建评估闭环。
修复前先保全其余字段
如果可靠备库、历史备份或 PITR 环境能够完整读取原值,应该优先恢复原值。只有确实没有可靠来源,而业务又接受字段丢失时,才考虑置空。
置空前把除坏字段以外的列导出到受控目录,设置严格文件权限并记录哈希:
\copy (
SELECT record_id,
event_time,
title,
response_body,
status,
error_message
FROM schema_name.audit_log
WHERE record_id = '<bad_row_id>'
) TO '/secure/path/bad_row_without_payload.csv'
WITH (FORMAT csv, HEADER true)
导出结果必须是 COPY 1。不要为了“多保一列”又把坏字段放回投影列表,否则导出本身也会失败。
为什么把坏字段设为 NULL 仍会报错
第一次修复很直接:
UPDATE schema_name.audit_log
SET request_payload = NULL
WHERE record_id = '<bad_row_id>';
结果仍然是同一个 missing chunk。
表上没有读取旧字段的业务触发器,坏字段也不在索引和检查约束中。继续排查发现,该表使用了:
REPLICA IDENTITY FULL
并且已经加入逻辑发布。
REPLICA IDENTITY FULL 使更新和删除需要记录旧行的全部列。即使新值是 NULL,PostgreSQL 为逻辑变更准备旧行信息时,仍会尝试解 TOAST 旧的 request_payload,因此在写入新值前就失败。
表上存在有效主键。临时切换到 REPLICA IDENTITY DEFAULT 后,变更只需要使用旧主键标识行,不再需要读取坏字段的完整旧值。
最小损失置空流程
这是生产 DDL/DML,需要业务确认字段原值无法恢复、可以丢失,并在维护窗口执行。ALTER TABLE ... REPLICA IDENTITY 需要强锁,不能在忙时不加评估地直接运行。
先切换行标识,再用主键锁定目标行。不使用已经出现漏项迹象的时间索引作为必须谓词:
\set ON_ERROR_STOP on
BEGIN;
SET LOCAL lock_timeout = '3s';
SET LOCAL statement_timeout = '30s';
SET LOCAL idle_in_transaction_session_timeout = '5min';
SET LOCAL synchronous_commit = on;
ALTER TABLE schema_name.audit_log
REPLICA IDENTITY DEFAULT;
SELECT ctid,
xmin::text AS xmin_before,
record_id,
event_time,
request_payload IS NULL AS already_null
FROM schema_name.audit_log
WHERE record_id = '<bad_row_id>'
FOR UPDATE;
UPDATE schema_name.audit_log
SET request_payload = NULL
WHERE record_id = '<bad_row_id>'
AND request_payload IS NOT NULL
RETURNING ctid,
xmin::text AS xmin_after,
record_id,
event_time,
request_payload IS NULL AS payload_is_null;
SELECT record_id,
request_payload IS NULL AS payload_is_null,
md5(request_payload::text) AS payload_md5,
md5(response_body::text) AS response_md5
FROM schema_name.audit_log
WHERE record_id = '<bad_row_id>';
只有以下条件同时满足才提交:
FOR UPDATE 只返回一行 record_id 和 event_time 符合预期 UPDATE 1 payload_is_null = true payload_md5 = NULL 其他大字段能正常读取
COMMIT;
任意一项不符就执行 ROLLBACK。ALTER TABLE 是事务性变更,回滚会同时撤销该事务中的 REPLICA IDENTITY DEFAULT。
修复提交后记录 WAL LSN,检查逻辑复制消费进度和订阅端结构。确认变更已正常消费后,恢复原配置:
BEGIN;
SET LOCAL lock_timeout = '3s';
SET LOCAL statement_timeout = '30s';
ALTER TABLE schema_name.audit_log
REPLICA IDENTITY FULL;
COMMIT;
如果订阅端没有与发布端一致的主键,临时切换 DEFAULT 可能使逻辑应用失败。这个检查不能省略。
这种修复到底做了什么
置空操作不会找回原文。它只是创建了一个新的 MVCC 行版本:
- 主键和其他业务列保留;
- 坏字段变为 SQL NULL;
- 新行不再保存指向缺失 TOAST value 的外置指针;
- 新快照读取新行,不再访问丢失的 chunk;
- 旧行版本等到不再被任何快照需要后,由常规 autovacuum 回收。
所以这是“最小数据损失隔离”,不是“原值恢复”。
修复后怎样确认没有其他坏行
精确行验证通过后,再强制扫描全表当前可见行。为了避免可疑索引跳过数据,显式关闭普通和位图索引扫描;用 MD5 强制读完整个大字段,但不把业务正文返回到客户端。
BEGIN READ ONLY;
SET LOCAL enable_indexscan = off;
SET LOCAL enable_bitmapscan = off;
SET LOCAL enable_seqscan = on;
SET LOCAL max_parallel_workers_per_gather = 0;
SET LOCAL statement_timeout = '60min';
SET LOCAL lock_timeout = '2s';
EXPLAIN (COSTS OFF)
SELECT count(md5(request_payload::text)) AS payload_count,
count(md5(response_body::text)) AS response_count,
count(md5(error_message::text)) AS error_count
FROM schema_name.audit_log;
SELECT count(md5(request_payload::text)) AS payload_count,
count(md5(response_body::text)) AS response_count,
count(md5(error_message::text)) AS error_count
FROM schema_name.audit_log;
ROLLBACK;
执行计划必须显示 Seq Scan。查询完成且没有新的 missing chunk,能说明该快照中当前可见行的这些字段都能完整读取。
它不能证明数据文件的每个物理字节都完好,也不会读不可见的死元组。最终还要重新执行单表 pg_dump,并在空的隔离环境中做恢复演练。
三个案例放在一起看
最容易犯的错误,是看到数据库完整性报错就套用同一个命令:
- 用
REINDEX修复真实丢失的 TOAST chunk,什么也找不回; - 把删除
pg_statistic的方法用到业务表,会变成真正的业务数据丢失; - 对可从堆表重建的索引做字段置空,完全是不必要的损失。
修复手段必须由对象的可再生性决定。
前两起故障发生在同一实例的相近时间窗口,因此具有共同底层诱因的可能,应合并排查存储、文件系统、异常恢复、HA 操作和内核缺陷。
第三起发生在独立环境,虽然共享 TOAST 悬空引用这一表层机制,但没有证据支持它与前两起具有同一根因。
data_checksums=off 是不是根因
数据页校验和会在页读取时检查页内容是否与写入时的校验值一致。关闭它不会主动删除 TOAST chunk,也不会主动生成 B-tree 零页。
但它会影响发现和取证:
- 底层静默改写可能无法在第一次读页时被明确标记为 checksum failure;
- 日志中少了一类重要证据;
- 事后更难区分逻辑不一致、介质错误和其他写入问题。
另一方面,即使开启 checksums,也不会检出所有逻辑损坏。一个校验正确的页仍可能包含错误的引用关系;B-tree 顺序、堆表与索引映射也需要 amcheck 等逻辑工具另行检查。
准确的结论是:
一套可复用的处理顺序
1. 先固定现场
修复前不要先跑 VACUUM FULL、CLUSTER、全库 REINDEX或者人工 DML TOAST 表。
保存:
- 完整错误、SQLSTATE、发生时间和触发 SQL 结构;
- 数据库和节点角色;
- relation OID、TOAST value ID、block number;
- PostgreSQL 启动时间;
- 备库回放位点和延迟;
- 故障前后的 PostgreSQL、内核、文件系统、存储和 HA 日志。
2. 把物理对象映射回逻辑 owner
目录映射做错,后面的修复命令就会整体走错方向。
先确认错误属于:
- 系统目录;
- 堆表;
- TOAST 表;
- 普通索引;
- 分区父索引或叶子索引。
3. 判断是否可再生
先查物理备库、逻辑副本、历史备份和 PITR。副本上“其他查询正常”没有意义,必须精确读取同一对象、同一行、同一字段。
统计信息 -> 可从业务表重新采样 索引 -> 可从堆表重建 业务字段 -> 只能从副本/备份恢复,或接受损失
4. 对象恢复后继续查底层原因
建议继续核对:
- 故障窗口是否有异常停机、崩溃恢复、主备切换或强制重启;
- 内核日志是否有 I/O error、reset、timeout、文件系统转只读;
- 云盘、SAN、RAID 或虚拟化层是否有介质告警;
- PostgreSQL 或兼容内核是否有已知缺陷和补丁;
- 基础备份、WAL 归档和 PITR 是否真正可用;
- 重要索引能否在低峰用
amcheck分批检查; - 大表的 TOAST 字段能否按时间或主键分段做逻辑读取校验。
对象修好了,只代表业务症状得到隔离,不代表介质、文件系统和整个实例已经证明安全。
参考资料
- PostgreSQL TOAST:https://www.postgresql.org/docs/current/storage-toast.html
- PostgreSQL
REINDEX:https://www.postgresql.org/docs/current/sql-reindex.html - PostgreSQL
ALTER TABLE/REPLICA IDENTITY:https://www.postgresql.org/docs/current/sql-altertable.html - PostgreSQL 逻辑复制发布:https://www.postgresql.org/docs/current/logical-replication-publication.html
- PostgreSQL
amcheck:https://www.postgresql.org/docs/current/amcheck.html - PostgreSQL 数据页校验和:https://www.postgresql.org/docs/current/checksums.html




