PostgreSQL usually does not fail out of nowhere. The incident that gets everyone's attention is often the last step in a chain: connections accumulate for days, a transaction stays open, a migration waits for a lock, or a forgotten replication slot retains WAL until the disk is full.

Public incident reports make this pattern hard to ignore. Sentry lost most of a working day to transaction ID wraparound. GitLab has documented WAL backlog incidents and a customer cluster where replication slots contributed to cascading disk failures. Locking investigations from pganalyze show how a migration that needs a lock for a few milliseconds can still stall an application.

This guide turns those lessons into a troubleshooting runbook. The diagnostic queries are read-only. The commands that change roles, tables, sessions, or replication slots are explained separately—do not run those against production until you understand their blast radius.

Production warning: Start with the read-only diagnostic queries.…