too_many_connections SQLSTATE 53300 — too_many_connections

The error appears verbatim in client logs and pg_log:

FATAL:  sorry, too many clients already

Alternatively, when max_connections is set per database or user:

FATAL:  too many connections for role "app_user"
FATAL:  too many connections for database "production_db"

Observable symptoms

• Application returns 500 errors or generic "database unavailable" messages
• New connections fail instantly — no timeout, no queue
• Existing connected clients continue working normally
• Load balancers may mark backends unhealthy if they test connectivity
• Connection pool logs show exhausted pool or rapid connection churn
• APM dashboards show database error rate spike with zero latency increase (connections never open)

GUC: max_connections

Set in postgresql.conf or at server start. Requires restart to change. Default is 100. Superusers retain 3 reserved slots via superuser_reserved_connections (default: 3), so the effective limit for regular roles is max_connections - superuser_reserved_connections = 97 by default.

# postgresql.conf
max_connections = 100
superuser_reserved_connections = 3

Per-object limits (optional)

You can restrict connections further per database or per role:

-- Per database
ALTER DATABASE production_db CONNECTION LIMIT 80;

-- Per role
ALTER ROLE app_user CONNECTION LIMIT 50;

These limits compound with the server-level max_connections.

Memory cost

Each connection consumes ~5–10 MB of shared memory overhead in addition to its working memory. Raising max_connections above ~500 without a connection pooler in front is almost always counterproductive — you trade connection rejection for OOM pressure or context-switching overhead.

Shared memory sizing

max_connections directly affects how much shared memory PostgreSQL allocates at startup. On Linux, the required kernel.shmmax and kernel.shmall values must be sufficient.

PostgreSQL maintains a fixed-size connection slot array allocated at startup. When all slots are filled, there is no backpressure mechanism — new connection attempts are immediately refused with FATAL: sorry, too many clients already.

Common causes

• No connection pooler: The application opens one connection per thread/worker/request directly to PostgreSQL. Under load, this exhausts slots fast. The most common cause in web applications.
• Connection leak: Code paths that fail to call conn.close() (exceptions bypassing cleanup, early returns, abandoned goroutines/threads). Connections accumulate until the limit is hit.
• Pool misconfiguration: PgBouncer or application pool max_pool_size × num_pool_workers exceeds PostgreSQL's max_connections.
• Deployment/rolling restart spike: Old pods hold connections while new pods open theirs. Both sets run simultaneously during the transition window.
• Long-running transactions holding idle connections: A transaction opened and left idle ("idle in transaction") occupies a slot indefinitely.
• Replica or standby misrouting: Read traffic intended for replicas accidentally routed to primary, doubling connection load.
• DDoS or retry storm: After an outage, every client retries simultaneously, overwhelming the connection limit the moment the server recovers.

Immediate (< 5 min)

1. Connect as superuser using the reserved slot: psql -U postgres
2. Terminate idle connections older than a few minutes (see Diagnostics Step 5 above)
3. Identify and terminate idle-in-transaction sessions if present
4. Verify connection count drops below the limit: SELECT count(*) FROM pg_stat_activity;

Short-term stabilisation (same incident window)

• Raise max_connections temporarily if you have sufficient RAM and can tolerate a restart. Calculate memory budget: each connection needs ~5–10 MB. On a 16 GB instance with 8 GB for shared_buffers, you have ~800 MB headroom = roughly 80–160 additional connections.

  ALTER SYSTEM SET max_connections = 200;
  -- Requires full restart, not just reload
  pg_ctl restart -D /var/lib/postgresql/data

• Enable connection pooling immediately if not already present. PgBouncer in transaction mode can multiplex hundreds of application connections onto tens of PostgreSQL connections.

App-side mitigation (no DB restart required)

• Reduce connection pool max_pool_size per app instance
• Reduce number of app replicas temporarily to cut total pool size
• Enable connection timeout + exponential backoff in app config to stop retry storms

Always use a connection pooler in production

PgBouncer is the standard. Transaction mode is appropriate for most web applications. Configure it so the total PostgreSQL connections from all pooler instances stay below max_connections - superuser_reserved_connections - 5 (leave headroom for DBA access).

[databases]
production_db = host=127.0.0.1 port=5432 dbname=production_db

[pgbouncer]
pool_mode = transaction
max_client_conn = 5000
default_pool_size = 25
min_pool_size = 5
reserve_pool_size = 5
reserve_pool_timeout = 3
server_idle_timeout = 600

Set idle_in_transaction_session_timeout

ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
SELECT pg_reload_conf();

Monitor pg_stat_activity continuously

Alert when count(*) / max_connections > 0.80. That gives you time to respond before the hard limit is hit.

-- Prometheus / Grafana query for connection usage ratio
SELECT count(*) / (SELECT setting::float FROM pg_settings WHERE name='max_connections')
FROM pg_stat_activity;

Calculate the right max_connections for your hardware

A common formula: max_connections = (RAM_GB * 100) / 10. On a 32 GB instance, that gives 320. In practice, with PgBouncer, 100–200 is often sufficient and healthier for performance.