PostgreSQL Wait Event Atlas

What the backend is waiting for, where the wait begins, and what an operator should do next.

Operator entry point

Start with the waiting sessions, not the event name

Capture who is waiting, how long, whether a transaction is open, and who blocks it. Then use the event page to connect the snapshot to PostgreSQL source and a bounded response.

13–18PostgreSQL versions

327versioned matrix identities

8operator-facing classes

2languages, paired page-for-page

Fact chainofficial docs → pg_wait_events → source grep → executable SQL

Take the first snapshot

Run this before restarting anything or cancelling a backend:

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;

Important

A wait-event snapshot shows where a process is sleeping now, not what consumed the elapsed query time. Repeat the snapshot and correlate it with latency, throughput, locks, and operating-system evidence before calling a wait the cause.

Continue with the wait-event triage map or open the class that matches wait_event_type.

Read by class

Class	Read it as	First question
Lock	Another transaction or session owns a heavyweight lock	Who is at the head of the blocking chain?
LWLock	Internal shared-memory structure is contended	Is one internal resource hot across repeated samples?
IO	A backend is waiting for a file operation	Is storage slow, or is PostgreSQL simply doing expected work?
IPC	Processes are coordinating with each other	Which peer or phase has not reached the rendezvous?
Client	PostgreSQL is waiting on the application or network	Is the session idle, backpressured, or inside a transaction?
Activity	A background process is in its normal main loop	Is this expected idleness for that backend type?
Timeout	A deliberate timer or rate limit has not expired	Which policy intentionally inserted the delay?
BufferPin	A buffer cannot move while another backend pins it	Which cursor or scan is holding the pin?

The generic extension wait-event mechanism is documented separately; extension-defined names are intentionally outside this catalogue.

Evidence contract

Every finished event page carries four different kinds of statement:

Fact — identity, version presence, and official description.
Analysis — the source path that reports the wait and what that path is doing.
Advice — a workload-aware normal/trouble boundary and scenario-specific action.
Evidence — executable SQL plus source file:line, tied to an exact PostgreSQL release.

Use the version matrix when an event appears on one major version but not another.

Triage map

A decision tree from one pg_stat_activity snapshot to the next safe action.

Matrix

The reconciled PostgreSQL 13–18 wait-event inventory, including renames and type moves.

Glossary

Terms used consistently across identity, analysis, advice, and evidence fields.

Lock

Heavyweight locks whose owner and blocking chain can usually be identified from SQL.

LWLock

Contention on PostgreSQL’s internal shared-memory data structures.

I/O

File reads, writes, synchronization, allocation, and asynchronous I/O completion.

IPC

PostgreSQL processes waiting for peers, workers, barriers, queues, or phase changes.

Client

PostgreSQL waiting for an application, network socket, TLS/GSS handshake, or replication client.

Activity

Background processes sleeping in their main loop until work arrives.

Timeout

Deliberate sleeps, retry intervals, throttles, and rate-limiting delays.

BufferPin

A backend needs an exclusive buffer pin while another backend still holds one.

Extension

How PostgreSQL extensions register and report custom wait-event names, and why they are outside the core catalogue.

GUC

Configuration controls referenced by wait-event response guidance.

Metrics

Signals used to decide whether a wait is expected or harmful.