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。

VACUUM 阶段与可能的回环

因此,heap_blks_scanned / heap_blks_total 只能回答 heap 扫描走了多少,不能直接代表整次 VACUUM 的完成百分比。即使扫描达到 100%,后面仍可能有索引清理、heap vacuum 和最终收尾。

查询正在运行的 VACUUM

下面的主查询按 PostgreSQL 17+ 编写,因为 indexes_total 与 indexes_processed 从这一代开始可直接观察索引处理进度。它同时保留 index_vacuum_count,用于判断已经完成了多少轮索引 vacuum。

sql
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;

预期输出

text
 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 失效。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 pg_stat_progress_vacuum 观察执行进度

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通