PgBouncer Pool Sizing: A Runbook Before Your Next Deploy Storm

Session pooling assigns one database connection per client connection for its whole session, which is safe but doesn't save you much. Transaction pooling returns the connection to the pool between transactions, which is where most of the efficiency gain lives, but it breaks anything that depends on session state persisting across transactions: prepared statements, session-level advisory locks, `SET` commands meant to persist. Statement pooling is the most aggressive and breaks multi-statement transactions outright. Most production setups want transaction pooling, but only after an audit of what session-level features the application actually relies on, since the failures it introduces are often intermittent rather than immediate.

The pool size should be set relative to your database's `max_connections` and how many other things share it, other services, background workers, a read replica's own connections, not to your peak concurrent request count. A common mistake is sizing the pool to match expected concurrency and discovering the database itself can't sustain that many active connections under load. Start from `max_connections` minus headroom for admin and replication connections, divide across the services that share the database, and size each pool from there, revisiting the split whenever a new service starts sharing the same cluster.

A rolling deploy that restarts every application instance within a short window means every instance tries to reconnect to the pooler at roughly the same moment. If your pooler's own connection limit isn't sized for that burst, or your deploy doesn't stagger restarts, you get a thundering herd against the pooler itself, which then queues or rejects connections right when the new version needs them most. Staggering instance restarts and giving the pooler headroom above steady-state usage specifically for this burst is the fix most teams learn about during an incident instead of before one, usually the first time a deploy coincides with an already-busy traffic period.

Run through this before your next deploy:

• Size the pooler's own connection limit for a burst where every application instance reconnects at the same moment.
• Stagger restarts during a rolling deploy instead of restarting every instance within a short window.
• Keep thirty to fifty percent headroom above steady-state connections, adjusted for how many instances restart together.
• Disable server-side prepared statement caching in your driver or ORM before switching to transaction pooling.
• Alert on pool wait time, since queuing behind an exhausted pool shows up as latency before errors.

ORMs and drivers that use server-side prepared statements assume the same connection persists across queries, which transaction pooling doesn't guarantee. The failure shows up as intermittent, hard-to-reproduce errors about a prepared statement that "doesn't exist," because the client prepared it on one backend connection and PgBouncer handed the next query to a different one. The fix is usually disabling server-side prepared statement caching in the driver configuration when running behind a transaction-mode pooler, not abandoning pooling entirely; most modern drivers expose this as a single connection option once you know to look for it.

Total connections in use tells you less than wait time for a connection: if requests are queuing behind pool exhaustion, that shows up as latency before it shows up as errors. Alert on pool wait time crossing a threshold, and separately on the ratio of active to idle connections trending toward saturation, so you catch the problem building during a traffic ramp instead of after requests start timing out waiting on the pool. A dashboard that only shows total connections in use will look healthy right up until it doesn't.

Some teams run a pooler per application instance in addition to a shared one in front of the database, to reduce connection count at each hop; this adds real value at scale but also adds a second layer where a misconfiguration can hide. Before adding a layer, confirm the problem is actually connection count rather than query latency or lock contention upstream of pooling entirely, since a second pooler won't fix a slow query, it will just queue more requests behind the same underlying bottleneck.