PgBouncer reserve pool activation: overflow capacity that hides an undersized pool

PgBouncer’s reserve pool is overflow capacity: extra server connections beyond pool_size that PgBouncer may open when clients have waited too long. Used as designed, it absorbs a short traffic spike and goes quiet. Used as a crutch, it hides a chronically undersized pool for months, until the day both base pool and reserve are exhausted and the queuing cliff is steeper than it would have been otherwise.

This article covers the activation mechanism, how to detect reserve usage, how to tell healthy burst absorption from chronic undersizing, and what to change when it is the latter.

For the broader saturation picture, see PgBouncer pool utilization high: sv_active approaching pool_size before clients queue. For the pooling model, see How PgBouncer actually works in production: a mental model for operators.

What the reserve pool is

Two settings control it:

• reserve_pool_size: how many additional server connections a pool may open beyond its pool_size. Default is 0, so the reserve pool is disabled entirely. If you have never set this, nothing in this article is happening on your system.
• reserve_pool_timeout: how long a client must wait in the queue before PgBouncer may draw from the reserve. Default is 5 seconds. This is a global setting, not per-database.

The total server connection ceiling for a pool is pool_size + reserve_pool_size, capped further by max_db_connections (per database) and max_user_connections (per user). If max_db_connections is lower than pool_size + reserve_pool_size, the reserve connections you think you have may never be created.

A version note that matters for monitoring: in PgBouncer 1.24.0, the per-database parameter was renamed from reserve_pool to reserve_pool_size, and the SHOW DATABASES output column changed with it. The old name is still accepted as a config alias. If you parse SHOW DATABASES by column name (or use an exporter that does), check which column your version emits; tooling written against the old name silently stopped reporting this value on 1.24.0 and later. Also in 1.24.0, reserve_pool_size became settable per user, in addition to globally and per database.

How activation works

The trigger is not pool fullness. The trigger is a waiting client. The sequence:

1. A client sends a query and no server connection is free, so the client enters the pool’s FIFO wait queue.
2. The client waits. While the wait is shorter than reserve_pool_timeout (default 5 seconds), PgBouncer does nothing special.
3. Once the client has waited longer than reserve_pool_timeout, PgBouncer may open an additional server connection from the reserve, up to reserve_pool_size extra connections, subject to the max_db_connections and max_user_connections caps.
4. When load subsides, those extra connections return to normal lifecycle rules and the pool shrinks back toward pool_size.

flowchart TD
  A[Client sends query] --> B{Free server connection in pool?}
  B -- yes --> C[Assign and execute]
  B -- no --> D[Client enters FIFO wait queue]
  D --> E{Waited longer than reserve_pool_timeout?}
  E -- no --> D
  E -- yes --> F{reserve_pool_size > 0 and reserve slots free?}
  F -- yes --> G[Take connection from reserve_pool]
  G --> C
  F -- no --> H[Keep waiting]
  H --> I{Wait exceeds query_wait_timeout?}
  I -- no --> D
  I -- yes --> J[Client disconnected with error]

Two consequences follow:

• Activation implies waiting already happened. Reserve connections only appear after at least one client has been blocked for more than reserve_pool_timeout. If you see reserve usage, you also had cl_waiting > 0 and maxwait above the timeout. The reserve pool does not prevent queuing; it responds to it.
• The reserve is a delay, not a cure. When pool_size + reserve_pool_size is fully in use, clients queue again and eventually hit query_wait_timeout (default 120 seconds) and are disconnected. The reserve buys headroom for a spike; it does not change the shape of the failure when demand keeps climbing.

How to detect reserve pool activation

There is no dedicated “reserve pool in use” counter. Detection is a comparison plus a log signal.

# 1. Per-pool server connection totals
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW POOLS;"

# 2. Configured pool_size per database
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW DATABASES;"

# 3. Confirm the reserve settings actually in effect
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW CONFIG;" | grep -E "reserve_pool|pool_size"

# 4. Log evidence of reserve draws
grep -ic "taking connection from reserve_pool" /var/log/pgbouncer/pgbouncer.log

For each pool, sum sv_active + sv_idle + sv_used + sv_tested + sv_login from SHOW POOLS. Compare it with that pool’s effective pool_size: SHOW DATABASES shows the database override/default, while SHOW USERS shows a user-level pool_size override when one is set. If the total exceeds the effective base size, the excess came from the reserve. Equivalently, an sv_active / pool_size ratio above 100% is only possible with reserve connections in play.

PgBouncer logs the lowercase warning taking connection from reserve_pool each time it opens a reserve connection. The trigger checks the age of the first (oldest) waiter, not every queued client. A large pileup can therefore still produce many lines if PgBouncer repeatedly opens reserve slots, and log volume can become a secondary problem during an incident.

One caveat on PgBouncer 1.24.0 or later: setting default_pool_size to 0 means an unlimited base pool. In that mode PgBouncer bypasses the normal base-pool/reserve-pool branch, so reserve_pool_size does not create a distinct overflow tier; only database and user connection caps still apply.

Brief activation vs sustained activation

This is the decision the whole article exists for.

Brief activation is informational. Reserve connections in use for more than 5 minutes sustained is a ticket-level signal that the pool is undersized.

Why sustained reserve usage is dangerous

The reserve pool masks the real number. If your dashboards and capacity reviews look at sv_active / pool_size and mentally cap at 100%, a pool that routinely runs at 130% of pool_size (because the reserve quietly covers the gap) never shows up as a sizing problem. Growth continues, the reserve absorbs it, and the first visible symptom arrives only when demand exceeds pool_size + reserve_pool_size, at which point:

• Clients queue with no further overflow to draw on.
• maxwait climbs toward query_wait_timeout (default 120 seconds), after which clients are disconnected. See PgBouncer query_wait_timeout: clients disconnected after waiting too long for a connection.
• Applications with shorter timeouts than query_wait_timeout give up and retry, adding new waiters and new client connections: the retry cascade described in PgBouncer pool exhaustion: clients queue, wait times climb, and the retry cascade.

The queuing behavior at that point is cliff-edge, and the cliff is taller than it would have been for a correctly sized base pool, because you deferred the resize decision for as long as the reserve held.

Pooling mode changes the risk calculus. In session mode, server connections are held for the entire client session, so reserve connections are returned slowly and reserve exhaustion is much more likely under the same client count. In transaction mode, connections turn over per transaction, so a small reserve stretches much further. If you run session mode with a reserve pool, treat any reserve activation as more serious than the same event in transaction mode.

Signals to watch in production

What to do when reserve usage is sustained

The fix is to size the base pool for the load you actually have, not to grow the reserve.

1. Measure real demand. Look at peak sv_active including reserve connections over a representative week. That peak, plus burst headroom, is your target pool_size. Utilization below 70% is healthy, 70-85% watch closely, above 85% act.
2. Check the PostgreSQL budget first. Every additional server connection consumes a max_connections slot on the backend. Sum pool_size (plus reserve) across all pools and all PgBouncer instances targeting the same PostgreSQL, and keep the total comfortably below max_connections minus reserved superuser slots. Raising pool_size past what PostgreSQL can serve trades queuing at the pooler for login failures at the backend.
3. Check max_db_connections and max_user_connections. If these caps are below your intended pool_size + reserve_pool_size, raising pool_size alone does nothing.
4. Increase pool_size and RELOAD. Pool size changes apply on reload; no restart needed.
5. Verify latency attribution before and after. Compare avg_wait_time against avg_query_time. If avg_query_time is high, the backend is slow and a bigger pool mostly buys you more concurrent slow queries; fix the queries first. If avg_query_time is fine and avg_wait_time carries the latency, the resize is the right call. See PgBouncer avg_wait_time high: the latency the pool itself is injecting.
6. Keep the reserve small and in place. After resizing, the reserve returns to its intended role: absorbing the next genuine spike, not carrying daily peak.

Do not respond to sustained reserve usage by increasing reserve_pool_size. That deepens the masking effect and makes the eventual cliff worse.

How Netdata helps

• Netdata’s PgBouncer collector queries the admin console continuously, so per-pool sv_active, sv_idle, and the other server connection states are captured as time series. “Total connections above pool_size” becomes a trend, not a snapshot you had to be watching.
• Per-pool breakdown matters here: one pool living in its reserve while nine others idle looks fine in any aggregate. Netdata charts split by pool so the chronic offender stands out.
• Correlating cl_waiting, maxwait, and avg_wait_time on the same dashboard shows the full activation chain: clients waited, maxwait crossed reserve_pool_timeout, the reserve opened, and wait time either recovered (healthy spike) or stayed elevated (undersized pool).
• Baseline views of avg_query_time next to avg_wait_time let you confirm whether reserve events are a sizing problem (wait high, query time normal) or a backend problem (both high) before you touch pool_size.
• Alerting on duration, not just presence, of reserve usage maps directly to the brief-versus-sustained decision: a few minutes of reserve draw during a deploy should not page anyone; 30 minutes every evening should open a ticket.

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