Connection Pool at >90% Saturation, PostgreSQL

​

At a glance

This is the alert card that fires when your PostgreSQL connection pool crosses 90% of max_connections and holds there. In plain terms: the database is running out of places to put new connections. When the last few slots fill, new connection attempts get rejected with “too many clients already” (FATAL: sorry, too many clients already), and every application that talks to the database starts throwing connection errors at the same time. For an SRE or DBA this is one of the highest-signal alerts on the board, because pool exhaustion is the single most common cause of a total, instant database outage that looks like a crash but is not one.

​

Calculation

saturation = count(pg_stat_activity backends) / max_connections
fire when:  saturation > 0.90  AND  the condition holds for >= 60 seconds

​

Worked example

1. The pool is nearly full and not draining. At 187 of 200 with traffic still climbing, the next minute will hit the wall. New API requests are about to start failing with FATAL: sorry, too many clients already.
2. 41 of those backends are idle in transaction. That is the tell. These are connections that opened a transaction (BEGIN) and then went quiet without committing or rolling back, often because an application thread is blocked on an external call while holding a database connection open. Cross-reference Idle-in-Transaction Backends.
3. This is a pooling problem, not a query problem. Latency (see Query Latency p95 (ms)) is still healthy at 38ms. The database can do the work; it just cannot accept the connections.

Triage path during the breach:
  1. Identify the idle-in-tx offenders:
     SELECT pid, state, now() - state_change AS idle_for, query
     FROM pg_stat_activity
     WHERE state = 'idle in transaction'
     ORDER BY state_change ASC;
  2. If a deploy just shipped, suspect a code path that forgot to commit.
  3. Short-term relief: terminate the oldest idle-in-tx backends:
     SELECT pg_terminate_backend(pid)
     FROM pg_stat_activity
     WHERE state = 'idle in transaction'
       AND now() - state_change > interval '5 minutes';
  4. Set idle_in_transaction_session_timeout so the DB self-heals next time.
  5. Confirm PgBouncer pool_size and the app's own pool size are not summed
     above what PostgreSQL can serve.

1. Pool exhaustion is almost never about traffic alone. A healthy app with correct connection handling will queue at the pooler, not flood the server. When this fires, the first suspect is a connection leak (idle-in-transaction), not “we got popular”.
2. The fix is usually configuration, not a bigger box. Raising max_connections to paper over a leak makes the eventual failure worse, because each backend costs memory (work_mem per sort, plus per-backend overhead). The durable fix is a pooler sized correctly plus idle_in_transaction_session_timeout.
3. This alert is a leading indicator of a total outage. Unlike a slow query, which degrades one endpoint, a full pool takes the whole database offline for every caller at once. Treat a sustained breach as a near-page-1 event.

​

Sibling cards

​

Reconciling against the source

Run SELECT count(*) FROM pg_stat_activity; and compare against SHOW max_connections;. The ratio is the saturation the card reports. Break it down by state with SELECT state, count(*) FROM pg_stat_activity GROUP BY state; to see how much of the pool is genuinely working versus idle or stuck. On PgBouncer, connect to the admin console (psql -p 6432 pgbouncer) and run SHOW POOLS; and SHOW CLIENTS; to see client-side queueing the server-side count cannot show. On a managed service (Amazon RDS / Aurora, Google Cloud SQL, Azure Database for PostgreSQL), the DatabaseConnections metric in the provider’s monitoring console is the same number, sampled at the provider’s interval.

​

Known limitations / FAQs

​

Tracked live in Vortex IQ Nerve Centre