PgBouncer capacity planning: runway for pools, clients, and PostgreSQL slots

PgBouncer capacity planning fails in a specific way: operators size one resource, usually default_pool_size, and forget the other three. Then a deployment doubles the app fleet, or a config change raises max_client_conn without touching the OS file descriptor limit, and the first sign of trouble is an incident rather than a dashboard trend.

There are four independent ceilings in any PgBouncer deployment, each with its own runway. The server pool determines how many queries can execute concurrently. Client slots determine how many application connections PgBouncer will accept. File descriptors determine what the operating system will let PgBouncer open. PostgreSQL backend slots determine whether the database has room for every pool PgBouncer might fill. Exhausting any one of them takes traffic down, and they degrade differently: some are cliffs, some are walls.

This guide walks through each resource: how to measure current usage, how to project runway, and how much headroom to keep. It assumes you already know how PgBouncer multiplexes connections; if not, read how PgBouncer actually works in production first.

The four ceilings and how they fail

flowchart LR
  subgraph App fleet
    A1[app instances x ORM pool size]
  end
  subgraph PgBouncer
    CS[client slots: max_client_conn]
    FD[file descriptors: ulimit -n]
    SP[server pools: pool_size per db,user]
  end
  subgraph PostgreSQL
    MC[max_connections minus reserved minus direct clients]
  end
  A1 -->|consumes| CS
  CS -->|each client is 1 FD| FD
  SP -->|each server conn is 1 FD| FD
  SP -->|each server conn is 1 backend slot| MC

The failure shapes differ, and that drives how much headroom each resource needs:

Plan against the knee, not the wall. For cliff-edge resources you need enough headroom that normal burst traffic never reaches 100%, because there is no gradual warning zone. For hard walls you need margin for planned growth, because there is no queue to absorb overshoot.

All measurements below come from the admin console:

psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW POOLS;"

Runway 1: server pool capacity

This resource saturates first in almost every deployment, and has the nastiest degradation curve. Below 100% utilization, pool-induced latency is approximately zero. At 100%, the next client request enters a FIFO queue and latency becomes unbounded. There is no graceful middle.

What to measure. For each pool, sv_active from SHOW POOLS against the configured pool_size from SHOW DATABASES. Track the peak ratio per pool, not the average. Averages hide the daily peak that actually determines when queuing starts.

Runway estimation. If peak sv_active / pool_size sits at ratio R and grows at rate G per week:

weeks to saturation = (1.0 - R) / G

At 0.7 utilization growing 0.05 per week, you have roughly six weeks before peak traffic hits persistent queuing. Use your own growth interval; the formula is just linear extrapolation of peak utilization.

Headroom. Keep at least 20% of pool_size idle during peak traffic. Practical bands: below 70% is healthy, 70-85% means monitor closely, above 85% sustained means act now. Because the curve is a cliff, “act now” means raising pool_size or reducing backend hold times before the next traffic peak, not scheduling it for next quarter.

Leading indicators that the runway is shrinking:

• Peak sv_active / pool_size trending upward over weeks.
• Brief cl_waiting appearances during peaks that did not happen before.
• avg_wait_time creeping above zero during peaks.
• avg_xact_time growing, which means each server connection is held longer and effective capacity shrinks even at constant pool size.
• Reserve pool being drawn regularly, if reserve_pool_size > 0. Reserve connections activate only after a client has waited longer than reserve_pool_timeout (default 5s), so sustained reserve usage means the base pool is chronically undersized.

Two things commonly distort this measurement. First, in transaction pooling mode, avg_xact_time includes idle-in-transaction time: if the application opens a transaction and does non-database work, it holds a server connection while doing nothing. When avg_xact_time is much larger than avg_query_time, the pool looks undersized but the real fix is application behavior. Second, in session pooling mode, sv_active tracks connected sessions rather than concurrent work, so utilization reads high by design and the runway math is less meaningful.

Note also that sv_idle is inventory, not waste. A pool showing 5 idle connections out of 20 at peak is a pool with burst absorption. Do not shrink pool_size because idle connections look unused; that removes exactly the headroom this calculation depends on.

Runway 2: client connection slots

max_client_conn (default 100) caps how many client connections PgBouncer will accept. At 100%, new connections are refused immediately with "no more connections allowed (max_client_conn)" in the log. There is no queue and no degradation period. The refusal is only visible in the log; no SHOW command exposes a refusal counter.

What to measure. used_clients from SHOW LISTS against max_client_conn from SHOW CONFIG:

# Client slot usage and limit
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW LISTS;"
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW CONFIG;" | grep max_client_conn

free_clients from SHOW LISTS is the same signal from the other direction: when it hits zero, refusals are happening.

Runway estimation. Track peak_used_clients weekly and extrapolate linearly:

days to limit = (max_client_conn - peak_used_clients) / daily_growth

The input most teams miss is planned deployments. Every new application instance adds its ORM pool size in client connections: an ORM pool of 20 across 50 instances is 1,000 client connections. The capacity question is not “what is our growth rate” but “what ships next sprint, and does max_client_conn cover (ORM pool size x instance count) after it lands.” Load balancer health checks also consume client slots; count them.

Headroom. Keep at least 30% of max_client_conn free at peak. Client connections are cheap (~2KB of memory each), so over-provisioning here is nearly free. Bands: below 80% healthy, above 80% plan an increase, above 95% urgent.

One nuance: admin console connections to the pgbouncer database are exempt from max_client_conn, so your monitoring connection still works during a client-slot exhaustion event. Convenient for diagnosis, but it means the outage will not show up as a monitoring failure.

Runway 3: file descriptors

File descriptors are the ceiling operators most often set incorrectly, because the limit lives outside PgBouncer entirely. PgBouncer needs one FD per client connection, one per server connection, plus listening sockets, the log file, pipe FDs, and admin sockets. When the OS limit is hit, accept() fails and the process can crash-loop.

What to measure. The actual limit and current usage from the running process (reading /proc/<pid>/fd may require root or the pgbouncer user):

# FD limit and current usage for the PgBouncer process
PGBPID=$(pgrep -f pgbouncer)
grep "Max open files" /proc/$PGBPID/limits
ls /proc/$PGBPID/fd | wc -l

Sizing rule. Set the FD limit to at least:

max_client_conn x 2 + 500

The doubling covers one server connection per client at full multiplexing; the 500 covers listening sockets, DNS, logging, pipes, and admin sockets with margin. Reserve at least 20% of the FD limit for non-connection overhead. If you raise max_client_conn, the FD limit must move first, in the same change. A classic failure is max_client_conn = 10000 with a default ulimit -n of 1024: PgBouncer does not lower the configuration value at startup; it logs the kernel limit and its maximum expected FD use, then can exhaust descriptors once the connection load exceeds that limit.

The systemd trap. The FD limit is captured at process start. For systemd-managed PgBouncer, the effective limit comes from LimitNOFILE in the unit or an override file, not from /etc/default/pgbouncer or the PgBouncer user’s shell limits. If you changed ulimit in a defaults file and the limit in /proc/<pid>/limits did not move, this is why. Changing the limit requires a process restart, which means a planned connection drain, not a reload.

Runway estimation. FD usage grows with total connections:

runway = (fd_limit - current_fds) / connection_growth_rate

In practice this resource should never be the binding constraint. Setting the limit far above need (tens of thousands is routine) costs nothing, so size it generously at deploy time and re-check it whenever max_client_conn or pool sizes change.

Runway 4: PostgreSQL backend slots

Every server connection PgBouncer opens consumes one slot from PostgreSQL’s max_connections. This ceiling is shared across everything that talks to the database: every PgBouncer instance, every pool within each instance, plus direct clients, replication, monitoring, and superuser access. It is also the ceiling most often miscalculated, because the demand side lives in multiple config files on multiple hosts.

The budget. The invariant to maintain:

sum over ALL PgBouncer instances of:
    sum over all pools of (pool_size + reserve_pool_size)
  + direct application connections
  + headroom for admin, replication, monitoring
  < max_connections - superuser_reserved_connections

Keep total PgBouncer pool capacity below 80% of PostgreSQL’s max_connections. The remainder covers direct connections, replication, monitoring, and emergency superuser access (PostgreSQL reserves superuser_reserved_connections slots, default 3, but those are for actual superusers in a crisis, not for your capacity plan). Count per (database, user) pool: two databases times three users times default_pool_size 20 is 120 potential backend connections from one PgBouncer instance, before reserve pools. Multiple PgBouncer instances fronting the same PostgreSQL multiply demand, and per-database pool_size overrides replace the default, so build the sum from SHOW DATABASES on each instance rather than from the ini files you remember writing.

Failure shape. When PostgreSQL is at max_connections, PgBouncer cannot establish new server connections, but existing ones keep working. The pool drains gradually as connections expire via server_lifetime or close on error. You will see sv_login elevated, sv_idle declining toward zero, and eventually cl_waiting growing. Slower than the other three failures, which makes it easy to miss until the pool is nearly empty.

Runway estimation. This is a static budget more than a trend: recompute the sum every time a pool size changes, a database or user is added (which creates new pools), a PgBouncer instance is added, or the app fleet gains a direct-connection path. The trend component is current_connections per database from SHOW DATABASES, which tells you how much of the theoretical pool capacity is actually instantiated.

A working review cadence

Capacity planning only works if someone recomputes it on a schedule. A monthly review that takes twenty minutes:

• Peak pool utilization. Pull peak sv_active / pool_size per pool for the month. Recompute weeks-to-saturation for any pool above 70%.
• Peak client usage. Pull peak used_clients / max_client_conn. Above 80%, schedule an increase and verify the FD limit first.
• FD margin. Check ls /proc/<pid>/fd | wc -l against the limit in /proc/<pid>/limits. Confirm the limit still satisfies max_client_conn x 2 + 500 after any config changes.
• Backend budget. Recompute the sum of all pools plus reserve across all PgBouncer instances against PostgreSQL max_connections. Flag any new databases, users, or instances added since last review.
• Deployment pipeline check. Ask what ships before the next review: new services, instance count changes, ORM pool changes. Translate into client slots and pool demand.
• Reserve pool review. If reserve_pool_size > 0, check whether reserve connections were drawn and for how long. Sustained use means raise the base pool.

How Netdata helps

Capacity planning depends on peak values over weeks, which is exactly what point-in-time SHOW POOLS snapshots cannot give you. Netdata collects PgBouncer admin console metrics every second and retains them, so the review cadence above becomes reading charts instead of reconstructing history:

• Per-pool sv_active, sv_idle, and cl_waiting time series, so peak pool utilization and its growth trend are visible without manual sampling.
• used_clients against max_client_conn over time, making client-slot runway a trend line rather than a spreadsheet exercise.
• avg_wait_time and avg_xact_time alongside utilization, so you can tell whether shrinking headroom comes from traffic growth or from connections being held longer.
• Host-level file descriptor usage for the PgBouncer process, correlated with connection counts in the same dashboard.
• Alerts on utilization ratios crossing headroom bands (85% pool, 80% client slots) so the runway conversation starts before the cliff, not during the incident.

Related guides

• PgBouncer avg_wait_time high: the latency the pool itself is injecting
• How PgBouncer actually works in production: a mental model for operators
• PgBouncer maxwait high: the oldest client waiter and how close it is to timing out
• PgBouncer monitoring checklist: the signals every connection pooler needs
• PgBouncer monitoring maturity model: from survival to expert
• PgBouncer pool exhaustion: clients queue, wait times climb, and the retry cascade
• PgBouncer pool utilization high: sv_active approaching pool_size before clients queue
• PgBouncer query_wait_timeout: clients disconnected after waiting too long for a connection