Why do app replicas exhaust Postgres max_connections?

Each application process holds its own connection pool, so total demand is the product replicas × processes per replica × pool size per process. Take an illustrative estimate with assumed inputs: 20 replicas, each running 4 worker processes, each worker with a pool of 10. That is 800 potential connections. Rolling deploys and autoscaling make it worse. While new replicas start before old ones drain, both sets hold connections. With five extra replicas during a rollout, the ceiling becomes 1,000.

Postgres cannot do that much work at once. Every connection is a separate backend process. Useful concurrency is bounded by CPU cores and disk throughput. On a 16-core server, a few dozen actively running queries is often the practical limit. Most of those 800 connections sit idle, but they are still reserved.

Raising max_connections to absorb the demand looks like the easy fix, and it causes harm. Each backend has its own memory overhead, and sorts or hashes can allocate work_mem per operation. When many backends are active, memory can spike past what the host has. More backends also add contention on shared structures such as locks and snapshot bookkeeping. Throughput can therefore fall as connection count rises.

PgBouncer is worth introducing when you have many replicas or workers and mostly short transactions. Those connections spend most of their time idle and can share a small set of server connections. If you run a few long-lived processes whose total connections already fit comfortably under the limit, a pooler adds a moving part without solving a real problem.

Who should use PgBouncer in front of a monolith?

PgBouncer fits teams whose connection demand grows with deployment shape rather than with database work. Typical signs:

  • A horizontally scaled monolith. One codebase runs as many identical replicas, often with several worker processes each. Every replica you add multiplies connections, even if request volume stays flat.
  • Autoscaling or frequent rolling deploys. Replica counts change during the day and overlap during releases, so the peak connection count is hard to predict and higher than the steady state.
  • Short, request-scoped transactions. Web requests that open a transaction, run a few queries and commit get the most from transaction pooling, because each one holds a server connection only briefly.
  • Connection errors that appear at scale-out, not under heavy query load. If "too many clients" errors show up when pods are added while the database CPU has headroom, the problem is connection count, not capacity.

It is a weaker fit for workloads dominated by long sessions: data pipelines that hold a connection for minutes, apps that rely heavily on session state, or a small fixed set of processes that already fit under max_connections. Those teams can still use PgBouncer, but mostly in session mode, which removes much of the benefit. The roles involved also matter. Platform or SRE engineers usually own the PgBouncer deployment and its server budget. Application engineers own per-replica pool settings and the session-state audit described later. Both groups need to agree on the numbers.

How does PgBouncer work?

PgBouncer is a lightweight proxy that speaks the Postgres wire protocol. Applications connect to it exactly as they would connect to Postgres. Usually only the host and port in the connection string change, for example to port 6432. PgBouncer runs as a single event-driven process, so one instance can hold a large number of mostly idle client connections cheaply.

The request path looks like this:

  1. A client connects. PgBouncer authenticates it, using its own auth_file or by looking up credentials in Postgres with auth_query. It then maps the client to a pool based on the requested database and user.
  2. The client starts work. PgBouncer needs a server connection from that pool. If an idle one exists, it is assigned. If the pool is below its size limit, PgBouncer opens a new server connection. Otherwise the client waits in a queue.
  3. The work finishes. Depending on pool_mode, PgBouncer releases the server connection when the client disconnects (session), when the transaction ends (transaction), or after each statement (statement). The released connection serves the next queued client.
  4. Idle server connections age out. Unused server connections are closed after configurable idle and lifetime limits, so the pool shrinks when traffic drops.

PgBouncer does not parse or rewrite your SQL to make pooling safe. It only decides which client gets which server connection and when. Any session state a client leaves on a server connection stays there, which is why the pool mode and the application code have to agree. Operators manage PgBouncer through an admin console, a special pgbouncer database that accepts commands such as SHOW POOLS, SHOW STATS, RELOAD, PAUSE and RESUME.

The following sections cover the two halves of this model: the client and server sides of the pool, and how to size each.

How does PgBouncer separate client connections from server connections?

PgBouncer holds two independent sets of connections. Client connections run from your app replicas to PgBouncer. Each one costs PgBouncer only a small amount of memory, so thousands are fine. Server connections run from PgBouncer to Postgres. Each one is a full backend process with its own memory and its own share of lock and snapshot overhead. That cost is why the server side has to stay small.

 replica-1 ─┐
 replica-2 ─┤   many client conns    ┌───────────┐   few server conns   ┌──────────┐
 replica-3 ─┼──────────────────────▶ │ PgBouncer │ ───────────────────▶ │ Postgres │
    ...     │                        └───────────┘                      └──────────┘
 replica-N ─┘
Setting Side What it limits
max_client_conn Client Total client connections this PgBouncer accepts
default_pool_size Server Server connections per database/user pair
reserve_pool_size Server Extra connections a pool may open when clients have waited too long
max_db_connections Server Server connections per database, across all users

Pools are keyed by database/user pair, and every PgBouncer instance keeps its own pools. Two users on one database get two pools. Three PgBouncer instances give you three times the server connections. Both multipliers matter when you size against max_connections.

The pool mode decides when a server connection goes back to the pool:

  • Session mode returns the connection only when the client disconnects. This gives you no fan-in beyond what your client pool already provides.
  • Transaction mode returns the connection at the end of each transaction. An idle replica connection then holds no server connection at all. Hundreds of mostly idle replica connections can share a few dozen backends, and that is what makes high replica counts workable.
  CLIENT SIDE (cheap, many)          SERVER SIDE (expensive, few)
  limit: max_client_conn             limits: default_pool_size,
                                     reserve_pool_size, max_db_connections

 ┌───────────┐
 │ replica-1 │──┐
 └───────────┘  │     ┌─────────────────────────┐
 ┌───────────┐  │     │        PgBouncer        │
 │ replica-2 │──┤     │                         │      ┌──────────────┐
 └───────────┘  │     │ ┌─────────────────────┐ │      │   Postgres   │
 ┌───────────┐  ├────▶│ │ pool: appdb/app_rw  │─┼─────▶│              │
 │ replica-3 │──┤     │ └─────────────────────┘ │      │ backend proc │
 └───────────┘  │     │ ┌─────────────────────┐ │      │ backend proc │
      ...       │     │ │ pool: appdb/app_ro  │─┼─────▶│ backend proc │
 ┌───────────┐  │     │ └─────────────────────┘ │      │     ...      │
 │ replica-N │──┘     └─────────────────────────┘      └──────────────┘
 └───────────┘
   hundreds of client conns   transaction mode:     a few dozen server
   (mostly idle)              server conn returned  conns, bounded by
                              at end of each txn    max_connections

Many mostly idle replica connections fan into one PgBouncer instance, which keeps a separate pool per database/user pair and, in transaction mode, shares a small set of Postgres backends across them.

How do you size the PgBouncer server pool from database capacity?

Start from what Postgres can execute at once, not from how many clients you have. A query that is actively running needs a CPU core or is waiting on I/O. Past a certain point, extra backends only add context switching, lock contention and memory pressure. A common starting point is two to four times the core count. The low end suits CPU-bound workloads. The high end suits workloads that spend real time waiting on disk.

Then set aside part of max_connections that PgBouncer never touches. This covers superuser access, replication slots and WAL senders, migration jobs, backups and monitoring agents. Split what remains across PgBouncer instances, and then across each database/user pair, because PgBouncer keeps a separate pool for each pair.

Illustrative estimate. Assume these inputs:

  • A 16-core primary.
  • One database with two roles: app and reporting.
  • Three PgBouncer instances.

At three times the core count, the target is about 48 active backends. Reserve 20 more for operations, so max_connections is about 70.

Each PgBouncer instance gets 16 backends:

  • default_pool_size = 12 for app.
  • A per-user override of 4 for reporting.
  • max_db_connections = 16 as a hard ceiling.
  • A small reserve_pool_size for bursts. Count it inside the 16, not on top of it.

The core-count formula is only a first guess. Workloads that wait on locks, such as hot rows, queue tables or long UPDATEs, gain nothing from more backends. Workloads with heavy random I/O on slow storage may tolerate more. Sessions that are idle in transaction, or slow transactions, each hold a server connection the whole time. Ten of them in a 12-connection pool leave two connections for everyone else.

; pgbouncer.ini on each of the 3 PgBouncer instances (illustrative estimate)
; Postgres primary: 16 cores, target ~48 active backends (3 x cores)
; postgresql.conf: max_connections = 70  -> 48 for PgBouncer + ~20 for ops
; 48 / 3 instances = 16 server connections per instance

[databases]
; Cap all server connections to appdb from this instance at 16
appdb = host=10.0.0.10 port=5432 dbname=appdb max_db_connections=16

[users]
; reporting gets its own pool for the appdb/reporting pair; hold it to 4
reporting = max_user_connections=4

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt

; Transaction pooling: a server connection is held only for one transaction
pool_mode = transaction

; Applies to the appdb/app pair: 12 of the 16 per-instance budget
default_pool_size = 12

; Short burst allowance. max_db_connections still caps the total at 16,
; so this comes out of the budget, not on top of it
reserve_pool_size = 2
reserve_pool_timeout = 3

; Many app replicas can connect; they queue for the 16 server connections
max_client_conn = 2000

; Drop clients sitting idle in a transaction so they stop pinning
; server connections and shrinking the effective pool
idle_transaction_timeout = 60

; Fail queued clients instead of letting them wait indefinitely
query_wait_timeout = 30

A per-instance pgbouncer.ini fragment for the worked example, where 12 app connections, 4 reporting connections and a reserve pool all fit under a 16-connection max_db_connections ceiling.

Right-sizing per-replica application pools behind PgBouncer

Once the server budget is fixed, work backward to the client side. If PgBouncer holds 40 server connections for the database, 30 replicas each opening a 20-connection pool does not give you 600 connections of throughput. It gives you 40 working connections and up to 560 clients waiting in PgBouncer's queue. A per-replica pool of 3–5 is usually enough to keep a replica's share of the server pool busy (illustrative estimate: 40 server connections ÷ 30 replicas ≈ 1.3 active each, plus headroom for uneven load).

Set max_client_conn for the worst case, not the steady state. During a rolling deploy, old and new pods overlap, and an autoscaling burst adds pods before old ones drain. With 30 replicas at 5 connections each, a full surge to 60 pods means 300 clients. Add a margin above that, because every client connection costs PgBouncer only a small amount of memory and one file descriptor.

Order the timeouts so each failure has one clear cause. The app pool's acquire timeout should be shorter than PgBouncer's query_wait_timeout. If it is, the app reports "pool exhausted" locally. If it is longer, the app sees a disconnect from PgBouncer and may retry, which adds more load to an already full queue. Keep query_timeout or a Postgres statement_timeout above your slowest legitimate query.

Small server pools protect Postgres, but the cost shows up as queueing latency. A traffic spike can look like slow queries when the database is idle and the delay is in the wait queue. Track PgBouncer's wait-time metrics alongside query latency so you can tell the two apart.

There is an operational benefit as well. Engineers no longer need to recalculate every service's pool against max_connections each time the replica count changes.

; pgbouncer.ini: server budget is fixed first, client side is derived from it
[databases]
; One logical database for the monolith. Host and credentials are placeholders.
appdb = host=10.0.0.12 port=5432 dbname=appdb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction

; Server side: the budget Postgres actually sees.
; default_pool_size applies per user/database pair, so max_db_connections
; caps the database total even if more roles connect later.
default_pool_size = 40
max_db_connections = 40

; Client side: sized for the worst-case surge, not steady state.
; 60 pods during a full rolling surge x 5 conns per app pool = 300 clients.
; Margin on top is cheap: a little memory and one fd per client.
; Raise the process fd limit (ulimit -n) to cover this.
max_client_conn = 500

; Seconds a client may wait in the queue for a server connection.
; Keep this LONGER than the app pool acquire timeout (5s below),
; so the app reports "pool exhausted" itself instead of being
; disconnected by PgBouncer and retrying into a full queue.
query_wait_timeout = 10

; Leave query_timeout off here and enforce statement_timeout in Postgres,
; set above the slowest legitimate query, e.g.:
;   ALTER ROLE app_user SET statement_timeout = '30s';
query_timeout = 0

; App side, per replica (expressed in your driver's pool settings):
;   max pool size   = 5    (40 server conns / 30 replicas ~ 1.3, plus headroom)
;   acquire timeout = 5s   (shorter than query_wait_timeout above)

A pgbouncer.ini that fixes the server budget at 40 connections, sizes max_client_conn for a rolling-deploy surge, and sets query_wait_timeout above the app pool's acquire timeout so queue exhaustion surfaces in the application first.

When should you avoid transaction pooling in a monolith?

Transaction pooling has a development cost. Any code that assumes the same server connection across transactions can break, because PgBouncer returns the server to the pool at COMMIT and the next transaction may run on a different one.

Feature Behavior in transaction mode
SET / session variables Leaks to whichever client gets that server next
Advisory locks across transactions Lock stays on a server the client no longer holds
LISTEN/NOTIFY Notifications arrive on a connection nobody is listening on
Temporary tables Disappear or appear to unrelated clients
Prepared statements Depends on driver and PgBouncer configuration

The worst bugs are silent. A request runs SET statement_timeout or SET search_path outside a transaction. That value persists on the server connection, and later an unrelated endpoint times out or queries the wrong schema. The failure shows up far from its cause and only under load. SET LOCAL inside a transaction avoids this.

To audit a monolith, grep for SET , pg_advisory_lock, LISTEN, CREATE TEMP, and raw PREPARE. Then check the driver's prepared-statement mode and any ORM hooks that run on connect.

Do not force migrations, batch jobs, reporting queries, or session-dependent code through the transaction pool. Give them a second [databases] entry, for example app_session, pointing at the same database with pool_mode=session and a small pool_size. Count that pool against max_connections too. This way long-running work cannot exhaust the web tier's pool, and session semantics stay correct for the code that needs them.

; pgbouncer.ini: two pools in front of the same Postgres database

[databases]
; Web tier: short transactions, many app replicas share few server connections
app = host=10.0.0.5 port=5432 dbname=app pool_mode=transaction pool_size=40

; Migrations, batch jobs, reporting, and code that needs session state
; (session SET, advisory locks across transactions, LISTEN, temp tables).
; Same database, separate pool, so long-running work cannot take the web pool's
; connections and session semantics stay intact.
app_session = host=10.0.0.5 port=5432 dbname=app pool_mode=session pool_size=8

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt

; Default for any entry that does not set pool_mode itself
pool_mode = transaction
max_client_conn = 2000

; Clear session state when a server connection is reused. This is the default
; and only applies in session mode. Transaction mode does not run it, so code
; on the 'app' pool must use SET LOCAL instead of plain SET.
server_reset_query = DISCARD ALL

; Budget check (illustrative estimate): pools are per (database entry, user),
; so one app user uses up to 40 + 8 = 48 server connections from this
; PgBouncer. Multiply by the number of PgBouncer instances, add superuser and
; monitoring headroom, and keep the total below Postgres max_connections.

; App configuration then selects the pool by database name:
;   web:  postgresql://app_user@pgbouncer:6432/app
;   jobs: postgresql://app_user@pgbouncer:6432/app_session

A pgbouncer.ini with a transaction-mode pool for the web tier and a small session-mode pool, both pointing at the same database, for migrations, batch jobs, reporting and session-dependent code.

Sidecar PgBouncer vs a central tier: what are the alternatives?

Where PgBouncer runs matters as much as how its pools are sized, because topology determines how many times your server-side budget is multiplied.

A sidecar next to each replica keeps networking simple: the app connects to localhost, and a PgBouncer failure takes out only one pod. The cost is that every sidecar owns its own server pool. Forty replicas with a default_pool_size of 10 can open 400 server connections. That stays safe only if each sidecar pool is tiny, which leaves no headroom for bursts on any single replica.

A central tier turns the problem into one shared budget, so the arithmetic from section 3 applies directly. In exchange, you add a network hop, a component that must be highly available, and a throughput ceiling. PgBouncer does most of its work on a single thread, so a busy tier often needs several processes or instances. Each one has its own pools, and the budget gets split again.

Option Server-connection math Failure domain Latency Operational overhead
Sidecar per replica replicas × pool size One replica Loopback only Low per pod, but drift across many configs
Central tier Instances × pool size Every replica Extra network hop HA, scaling, monitoring
App-side pooling only replicas × workers × pool One replica None added Lowest
Fewer workers per replica Shrinks the multiplier One replica Possible queueing in app Low
Reads to replicas Splits load across servers Per database Replication lag risk Routing logic in app

The last three options are not mutually exclusive with PgBouncer. They reduce how much it has to absorb.

How can PgBouncer pool sizing save engineering time?

The main saving is that connection limits stop being a per-deploy calculation spread across every team. Without a pooler, each change to replica count, worker count or per-process pool size has to be checked against max_connections, and the check is easy to skip. With a central budget in PgBouncer, the server-side numbers are set once, in one place, from database capacity. Scaling the monolith from 20 to 60 replicas becomes a change to max_client_conn headroom, not a renegotiation of the Postgres connection limit.

Specific places where time is saved:

  • Fewer connection-exhaustion incidents during deploys and autoscaling. Surges queue in PgBouncer instead of hitting "too many clients" errors in Postgres. Engineers deal with bounded wait time rather than failed requests and a scramble to find which service opened too many connections.
  • Fewer Postgres restarts for capacity changes. Changing max_connections requires a Postgres restart. Most PgBouncer pool settings can be changed and applied with RELOAD from the admin console, without dropping client connections.
  • Simpler maintenance windows. PAUSE lets in-flight transactions finish and then holds new client work in the queue while you restart or fail over the database. RESUME releases it. Applications see a delay instead of a burst of connection errors, which reduces the retry and reconnect handling each service has to get right.
  • Faster diagnosis. SHOW POOLS and SHOW STATS show in one place whether latency comes from queueing or from the database, as described in the next section. That replaces correlating pool metrics from dozens of replicas.
  • Smaller per-service pool tuning. Application teams can use small, uniform per-replica pools, as in the earlier section, instead of each team tuning pool sizes against a shared limit they cannot see.

The time is not free. Someone has to run PgBouncer, keep it highly available if it is a central tier, and audit the code for session-state assumptions before turning on transaction mode. For a monolith with a handful of processes, that upfront work can outweigh the savings. For one with many replicas and frequent deploys, the recurring work it removes is usually the larger cost.

Illustrative estimate. Assume a team does 10 deploys a week and that, without a pooler, each deploy needs about 15 minutes of manual checking of replica overlap against max_connections. That is about 2.5 engineer-hours a week, before counting any incident caused by a missed check. The inputs here are assumptions to show how to reason about the trade-off, not measured results. Substitute your own deploy frequency and review time.

How do you tell whether your PgBouncer pool sizing is right?

Sizing is a hypothesis until you measure it. Start with the PgBouncer admin console. In SHOW POOLS, watch cl_waiting (clients queued for a server connection), sv_active against your configured pool size, and maxwait (how long the oldest waiting client has been queued). SHOW STATS adds cumulative wait time, which shows whether queueing is occasional or sustained.

A waiting client does not tell you the cause by itself. Check it against Postgres. In pg_stat_activity, count sessions by state. Many active sessions with CPU near saturation means the database is the bottleneck. Many idle in transaction sessions mean server connections are held by application code that is not doing database work.

Signal Likely cause Action
Clients waiting, Postgres CPU has headroom, few idle-in-transaction Pool too small Grow the pool in small steps
Clients waiting, many idle in transaction Long or leaky transactions Shorten transactions, set timeouts
Clients waiting, active sessions slow, CPU saturated Expensive queries Fix queries or indexes. Do not grow the pool
No waiting, sv_idle consistently high Pool oversized Shrink to free max_connections

Growing the pool when CPU is already saturated makes latency worse, because more queries compete for the same cores.

Two moments confirm your numbers. The first is a load test at expected peak traffic. The second is a rolling deploy, when old and new replicas overlap and client counts briefly spike. If cl_waiting stays flat through both, the sizing holds. Dashboard these metrics before an incident. When pool pressure and database state are on one screen, the cause of a latency spike is visible immediately, and you avoid long sessions spent guessing.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to pgbouncer pool sizing, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.