PostgreSQL 等待事件大典

后端在等什么、等待从哪条代码路径开始，以及值班工程师下一步该做什么。

值班入口

先看正在等待的会话，再看事件名称

先保全现场：谁在等、等了多久、事务是否仍然打开、阻塞者是谁。再用事件条目把快照连接到 PostgreSQL 源码与边界清晰的处置动作。

13–18覆盖的 PostgreSQL 版本

327版本矩阵中的事件身份

8面向运维的等待类别

2中英文逐页配对

事实链官方文档 → pg_wait_events → 源码 grep → 实际执行 SQL

先做第一张快照

重启服务或取消后端之前，先执行：

SELECT pid, backend_type, usename, datname, application_name,
       state, now() - query_start AS query_age,
       now() - xact_start AS xact_age,
       wait_event_type, wait_event,
       pg_blocking_pids(pid) AS blocking_pids,
       left(query, 160) AS query
FROM pg_stat_activity
WHERE wait_event IS NOT NULL
ORDER BY query_age DESC NULLS LAST;

重要

等待事件快照只说明进程此刻睡在哪里，不代表查询耗时都花在这里。重复采样，并与延迟、吞吐、锁以及操作系统证据关联后，才能判断它是不是根因。

接着使用等待事件排查总图，或按 wait_event_type 进入对应类别。

按类别阅读

类别	应当怎样理解	第一个问题
Lock	另一个事务或会话持有重量级锁	阻塞链最前端是谁？
LWLock	PostgreSQL 内部共享内存结构发生竞争	重复采样时是否总是同一内部资源发热？
IO	后端在等待文件操作	是存储变慢，还是 PostgreSQL 正在做预期工作？
IPC	进程正在彼此协调	哪个对端或执行阶段还没到达同步点？
Client	PostgreSQL 在等待应用或网络	会话是正常空闲、发生背压，还是卡在事务里？
Activity	后台进程处于正常主循环	对这种后端类型而言，这是不是预期空闲？
Timeout	有意设置的计时器或限速尚未到期	是哪条策略主动插入了等待？
BufferPin	其他后端钉住缓冲区，使其不能移动	哪个游标或扫描仍持有 pin？

通用的扩展等待事件机制单独说明；扩展自行注册的名称不纳入本大典。

证据契约

每个完成的事件条目都明确区分四类信息：

事实：事件身份、版本范围与官方描述译文。
分析：报告等待的源码路径，以及该路径正在做什么。
建议：结合负载的正常/异常边界与分场景动作。
证据：可执行 SQL 与精确到 PostgreSQL 发布版本的源码 file:line。

当同一名称只在部分大版本出现时，使用版本矩阵对照。

排查总图

从一张 pg_stat_activity 快照走向下一步安全动作的决策树。

版本矩阵

对账后的 PostgreSQL 13–18 等待事件清单，包括改名与类型迁移。

术语表

身份、分析、建议与证据字段中统一使用的术语。

Lock

通常可以直接从 SQL 找到持有者与阻塞链的重量级锁。

LWLock

PostgreSQL 内部共享内存数据结构上的竞争。

I/O

文件读取、写入、同步、分配与异步 I/O 完成。

IPC

PostgreSQL 进程等待对端、worker、屏障、队列或阶段变化。

Client

PostgreSQL 等待应用、网络套接字、TLS/GSS 握手或复制客户端。

Activity

后台进程在主循环中休眠，等待新工作到来。

Timeout

有意休眠、重试间隔、节流与限速延迟。

BufferPin

后端需要独占缓冲区 pin，但另一个后端仍持有 pin。

Extension

PostgreSQL 扩展如何注册并报告自定义等待名称，以及它们为什么不进入核心大典。

GUC

等待事件处置建议引用的配置控制项。

指标

用于判断等待正常还是有害的观测信号。