postgresql-troubleshootinglisted

# PostgreSQL Troubleshooting Find out whether the database is waiting, working, or blocked — then find on what. ## Purpose **Use this when:** - `FATAL: sorry, too many clients already`, or connection timeouts from applications. - Queries that were fast are now slow. - Sessions are blocked, or a deployment's migration is hanging. - Replication lag is growing. - Autovacuum warnings, table bloat, or transaction ID wraparound messages. **Do not use this when:** - The problem is the host underneath — use `linux-performance`. - The problem is network reachability to the database — use `linux-network-debugging`. - The database is healthy and the application is slow — use `production-debugging`. **What this skill assumes:** a psql connection with sufficient privileges to read `pg_stat_activity` in full (a superuser or `pg_monitor` role; other roles see truncated query text), and ideally `pg_stat_statements` installed. State the PostgreSQL version — behaviour around vacuum, locks and monitoring views has changed materially across recent versions. ## Operating Procedure 1. **Establish version and configuration.** `max_connections`, `shared_buffers`, `work_mem`, and whether a pooler is in front. 2. **Look at what is happening right now.** `pg_stat_activity` is the single most informative view. 3. **Classify.** Is the database blocked (locks), busy (CPU/IO), waiting (client or replication), or out of a resource (connections, disk, transaction IDs)? 4. **Find the specific q