Read pg_locks: relation waits versus tuple waits
pg_locks mixes relation, tuple and transaction ID locks into one flat view. Decoding locktype is the difference between 'a DDL is queued behind everything' and 'two updates are fighting over one row'.
Problem
What you're actually looking at
The symptom as it shows up on a real server.
Everyone reads pg_locks eventually, and most people read it wrong. The row that looks like the wait is usually granted, and the one that actually represents the wait is a transactionid lock that names nothing recognisable. Until you decode locktype, the view is noise.
Three sessions on parcel_ledger_lines: settlement_owner has a row locked, settlement_waiter is queued behind it, and index_rebuild wants the whole table.
Simple terms
Almost everyone reads pg_locks eventually, and most read it wrong. The row that looks like the block is usually the one that has already been granted; the row that actually represents the waiting is a "transactionid" lock that names nothing you recognize. The key is the locktype column, decoding it is the difference between "a schema change is queued behind everything" and "two updates are fighting over a single row".
Full runbook for this incident
- The full identify checklist, the exact signals that tell you it's this incident
- Every diagnostic query; lab output is attached only to the steps we actually captured
- The resolution path and the pitfalls that make it worse
- Mitigation steps to stop it recurring, plus a verify-you're-done query
Card required. Cancel before day 7 and you are not charged.
More in this category
Other Observability runbooks
Neighbouring incidents that share the same diagnostic surface.
Connected
How this connects to the rest of the library
A live view of this page's real cross-references, what explains it, what fixes it, what to tune, and where to go next. Every link is an authored relationship, not a guess.
Fixes these errors
Need the full procedure?
Pro runbooks finish the incident path
Free runbooks teach the shape. Pro opens the full step transcript, edge cases, and prevention depth.