Skip to content

PostgreSQL connection pooling and "too many connections"

Last updated

View as Markdown

Quick answer: FATAL: sorry, too many clients already means you hit max_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 already

Why 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.

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:

ModeA server connection is held…Trade-off
Sessionfor the client’s whole sessionSafest; least reuse
Transactiononly for the duration of each transactionHighest reuse; most common, but session-state features can break
Statementonly for a single statementMost 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.

  • 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_connections before 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.