PostgreSQL / 系统课时
用 pg_stat_progress_vacuum 观察执行进度
用 pg_stat_progress_vacuum 观察执行进度
这节课解决“VACUUM 正在跑,但到底走到哪一步”的问题。你会用 pg_stat_progress_vacuum 读取当前 phase、heap 扫描进度和索引处理进度,并判断进度缓慢究竟是正常阶段切换、重复索引清理,还是需要继续排查的停滞。
学习目标
- 根据
phase判断 VACUUM 当前正在扫描 heap、处理索引还是执行收尾。 - 计算 heap 扫描比例,并正确解释
heap_blks_vacuumed与index_vacuum_count。 - 在 PostgreSQL 17+ 使用索引进度字段观察当前索引处理阶段,而不把单一百分比误当成总 ETA。
先把 phase 当成主坐标
普通 VACUUM 不是一次线性扫描。典型过程会从 initializing 进入 scanning heap,随后可能执行 vacuuming indexes 和 vacuuming heap;如果一次无法容纳本轮发现的全部待处理项,这两个阶段可能出现多轮,再进入 cleaning up indexes、可选的 truncating heap 和 performing final cleanup。

因此,heap_blks_scanned / heap_blks_total 只能回答 heap 扫描走了多少,不能直接代表整次 VACUUM 的完成百分比。即使扫描达到 100%,后面仍可能有索引清理、heap vacuum 和最终收尾。
查询正在运行的 VACUUM
下面的主查询按 PostgreSQL 17+ 编写,因为 indexes_total 与 indexes_processed 从这一代开始可直接观察索引处理进度。它同时保留 index_vacuum_count,用于判断已经完成了多少轮索引 vacuum。
SELECT
pid,
datname,
relid::regclass AS table_name,
phase,
heap_blks_total,
heap_blks_scanned,
round(
100.0 * heap_blks_scanned
/ NULLIF(heap_blks_total, 0),
1
) AS heap_scan_pct,
heap_blks_vacuumed,
index_vacuum_count,
indexes_total,
indexes_processed,
CASE
WHEN indexes_total > 0 THEN round(
100.0 * indexes_processed / indexes_total,
1
)
END AS current_index_pct
FROM pg_stat_progress_vacuum
ORDER BY pid;预期输出
pid | datname | table_name | phase | heap_blks_total | heap_blks_scanned | heap_scan_pct | heap_blks_vacuumed | index_vacuum_count | indexes_total | indexes_processed | current_index_pct
------+---------+---------------+---------------+-----------------+-------------------+---------------+--------------------+--------------------+---------------+-------------------+------------------
<ID> | appdb | public.orders | scanning heap | <VALUE> | <VALUE> | <VALUE> | <VALUE> | <VALUE> | <VALUE> | <VALUE> | <VALUE>实际进度值会随执行不断变化;没有普通 VACUUM 或 autovacuum 正在运行时,这个视图返回 0 行。VACUUM FULL 不在这里报告进度,因为它走的是表重写流程。
正确解释各个计数器
当 phase = 'scanning heap' 时,优先看 heap_blks_scanned。它最终会接近 heap_blks_total,适合回答“扫描还剩多少块”。heap_blks_vacuumed 不是同一个概念:它只在对应 heap vacuum 工作阶段推进,而且没有 dead tuple 需要处理的块可能被跳过,所以它不能拿来做全表线性百分比。
进入索引阶段后,indexes_processed / indexes_total 表示当前索引处理阶段的进度。index_vacuum_count 表示已经完成的索引 vacuum 轮次;如果它持续增长,说明 VACUUM 发生了多轮索引处理,这通常意味着本次发现的待清理项需要分批处理,而不是任务在原地不动。
PostgreSQL 16 及更早版本没有 indexes_total 和 indexes_processed。在这些版本上删除这两列及 current_index_pct 计算即可,仍可用 phase、heap 块计数和 index_vacuum_count 判断大部分进度。
判断慢还是卡住
单次快照只能告诉你“现在在哪”。判断是否停滞应间隔采样:如果 scanning heap 中 heap_blks_scanned 持续增加,说明工作仍在推进;如果处于索引阶段,观察 indexes_processed 或 index_vacuum_count 是否变化。阶段长时间不变也不一定异常,大表索引处理和 I/O 限速都可能让某个阶段停留很久。
真正需要升级排查的是“同一 phase 长时间不变,且对应计数器也不增长”。这时再结合 pg_stat_activity 的等待事件、I/O 压力、锁和 autovacuum 成本延迟去定位原因。用 pg_stat_progress_vacuum 的正确方式,是先确定阶段与仍在变化的工作量,再决定是否值得追查阻塞,而不是看到一个低百分比就判断 VACUUM 失效。