PostgreSQL connection pooling and "too many connections"
Quick answer:
FATAL: sorry, too many clients alreadymeans you hitmax_connections. Each PostgreSQL connection is a separate backend process with real memory cost, so raising the limit usually makes things worse. The fix is a connection pooler (PgBouncer, pgcat, or a built-in pool) that multiplexes thousands of application clients onto a small pool of real database connections.
Why the limit exists: a process per connection
Section titled “Why the limit exists: a process per connection”PostgreSQL uses a process-per-connection model. Every connection forks a dedicated backend process on the server, with its own memory for sorting, hashing, and caches. That is manageable at tens of connections but expensive at thousands. Memory use increases, and the OS spends more time switching between processes than doing query work.
max_connections caps how many can exist at once. When your app opens more, you
get:
FATAL: sorry, too many clients alreadyWhy raising max_connections is the wrong fix
Section titled “Why raising max_connections is the wrong fix”Raising the number does not remove the per-connection cost. It adds more of it. More backend processes mean more memory pressure and scheduling overhead. A database under pressure from 2,000 processes is slower than one serving 100 comfortably. The underlying problem is usually that connections are not being reused: a serverless function opens a fresh connection per invocation, or an app has no pool, so idle connections pile up.
The fix: a connection pooler
Section titled “The fix: a connection pooler”A pooler like PgBouncer sits between your application and PostgreSQL. Your app connects to the pooler, and the pooler multiplexes those clients onto a small set of real database connections. Thousands of clients can then share a few dozen backends.
PgBouncer offers three pooling modes:
| Mode | A server connection is held… | Trade-off |
|---|---|---|
| Session | for the client’s whole session | Safest; least reuse |
| Transaction | only for the duration of each transaction | Highest reuse; most common, but session-state features can break |
| Statement | only for a single statement | Most aggressive; disallows multi-statement transactions |
Transaction pooling is the most widely used mode and gives the highest reuse,
but session state does not survive the handoff. Session-level SET, SQL
PREPARE, session advisory locks, LISTEN, WITH HOLD cursors, and
session-lifetime temp tables break. NOTIFY and ON COMMIT DROP temps are
fine. Protocol-level prepared statements work under transaction pooling since
PgBouncer 1.21, and since PgBouncer 1.24 they are enabled by default.
max_prepared_statements now defaults to 200 rather than 0. On 1.21 to
1.23 you have to set it yourself. Confirm your driver, then size the pool to
the server’s capacity, not your client count.
Why does AI-generated code cause connection storms?
Section titled “Why does AI-generated code cause connection storms?”Your AI coding agent may write code that opens a connection, runs a query, and moves on. The code can work in isolation while still causing problems in production. The agent cannot see that the function runs in a serverless environment scaling to 500 concurrent instances, with each instance opening its own connection, or that no pool sits in front of the database. “Connect and query” is locally correct; the connection storm depends on the deployment and its concurrency.
How do I keep connections under control?
Section titled “How do I keep connections under control?”- Put a pooler (PgBouncer) in front of PostgreSQL and point the app at the pooler.
- Prefer transaction pooling for web workloads, and verify session-state compatibility.
- Size the pool to the database, and cap the app-side pool too.
- Watch the connection count against
max_connectionsbefore it becomes an outage.
What does "FATAL: sorry, too many clients already" mean?
Your application tried to open more connections than max_connections allows, so PostgreSQL refused the new connection. It usually means connections aren't being pooled or reused, each request or worker is opening its own.
Why not just raise max_connections?
Because each PostgreSQL connection is a separate backend process with its own memory. Thousands of them cost a lot of RAM and add context-switching overhead, which often makes performance worse. A pooler serves many clients from a few real connections instead.
What is the difference between session and transaction pooling in PgBouncer?
In session pooling a client keeps a server connection for its whole session. In transaction pooling the server connection returns to the pool after each transaction, so far more clients share a small pool, but features that rely on session state can break, so the application must be compatible.
How big should my connection pool be?
Small, sized to the database server's CPU and disk capacity, not the number of clients. A pool of a few dozen real connections can serve thousands of application clients. Oversizing the pool just recreates the too-many-connections problem behind the pooler.