FATAL: sorry, too many clients already

The exact error string

psql: error: connection to server failed:
FATAL:  sorry, too many clients already

# application drivers surface the same thing:
# psycopg2.OperationalError: FATAL:  sorry, too many clients already
# error: sorry, too many clients already   (node-postgres)

Every connection slot is in use. Postgres allows max_connections simultaneous connections (default 100); once they are all taken, the next client is rejected. This is about the number of open connections, not the queries themselves.

Step 1: see what is holding connections

Before changing anything, look at who is connected. A pile of idle connections is the classic sign of a leak:

-- how many connections, grouped by state
SELECT count(*), state FROM pg_stat_activity GROUP BY state;

-- the configured ceiling
SHOW max_connections;

-- who is connected, and to what
SELECT pid, usename, application_name, state, query
FROM pg_stat_activity ORDER BY state;

Lots of idle rows → connections opened and never closed. idle in transaction → transactions left open (a missing commit/rollback).

Fix 1: use a connection pool (the real fix)

The root cause is almost always "a new connection per request/worker." A pool keeps a small, fixed set of connections and reuses them. Set a sane max in your app's pool:

// node-postgres: one shared pool, capped
import { Pool } from 'pg';
const pool = new Pool({ max: 10 });          // not a client per request
const { rows } = await pool.query('SELECT 1');

# Python / SQLAlchemy: bounded pool
engine = create_engine(url, pool_size=10, max_overflow=5)

For many app instances (or serverless), put PgBouncer between the app and Postgres in transaction mode — hundreds of clients then share a few dozen real connections.

Fix 2: close what you open

If you create connections manually, always release them — use a context manager or finally so an exception can't leak the connection:

# ✅ context manager returns the connection even on error
with psycopg2.connect(dsn) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT 1")

// ✅ always release a pooled client
const client = await pool.connect();
try { await client.query('SELECT 1'); }
finally { client.release(); }

Fix 3: serverless needs a pooler

On Lambda, Vercel, or Cloud Functions, each concurrent instance opens its own connections — hundreds of instances exhaust Postgres instantly. Don't connect directly; route through a pooler: PgBouncer, RDS Proxy, or a provider pooler (Supabase, Neon). Use the pooled connection string, not the direct one.

Fix 4: raise max_connections (last resort)

Only after pooling. Each connection reserves memory, so a high limit can exhaust RAM:

-- postgresql.conf  (requires a restart)
max_connections = 200

-- then verify
SHOW max_connections;

Debugging checklist

• ✓ Count connections by state: pg_stat_activity — many idle means a leak
• ✓ Add or fix a connection pool with a bounded max size
• ✓ Release connections in finally / a context manager
• ✓ idle in transaction? Commit or roll back — don't leave transactions open
• ✓ Serverless? Route through PgBouncer / RDS Proxy / a provider pooler
• ✓ Raise max_connections only as a stopgap (it costs RAM per connection)