Skip to content

CONCEPT Cited by 1 source

query_wait_timeout

Definition

query_wait_timeout is the PgBouncer configuration that governs admission-control behaviour when the pool is exhausted: how long a client waits for a connection before being disconnected with an error.

Default: 120 seconds.

When all pool connections are in use, PgBouncer queues the client rather than rejecting it; if the wait exceeds query_wait_timeout, the client is disconnected.

(Source: sources/2026-04-21-planetscale-scaling-postgres-connections-with-pgbouncer: "When all pool connections are in use, PgBouncer queues the client until one becomes available rather than rejecting it. If the wait exceeds query_wait_timeout (default: 120 seconds), the client is disconnected with an error.")

The two admission-control regimes

PgBouncer's default is queue-then-disconnect, not fail-fast:

  • Queue phase (0 - 120 s default): client waits in a bounded queue for a server connection to become available.
  • Disconnect phase (> 120 s): client is disconnected with an error. Application sees a connection-reset; must retry or fail.

This contrasts with poolers that fail-fast (reject immediately when the pool is full) and with poolers that have no timeout (hang until a connection is available, potentially indefinitely).

Why queue-then-disconnect matters

  • 120 s absorbs most operational bursts: a transient spike in load usually resolves within seconds; queuing until a connection is available is cheaper than rejecting and forcing the caller to retry.
  • 120 s bounds the worst case: a genuinely stuck pool — caused by a deadlock, a stuck long-running query, or a downstream Postgres freeze — eventually disconnects rather than accumulating an unbounded queue.
  • 120 s is long enough to mask recovery: if PgBouncer restarts, a failover completes, or a stuck query returns within the window, the client resumes transparently.
  • 120 s is short enough to surface real problems: if the pool stays saturated for more than two minutes, the application should see errors — it's a genuine production problem requiring intervention.

Pairing with pool exhaustion

query_wait_timeout is the temporal companion to concepts/connection-pool-exhaustion:

  • Exhaustion is the spatial condition (pool at 100% utilisation).
  • query_wait_timeout is the temporal bound on how long the exhaustion can persist without surfacing.

Without query_wait_timeout, a saturated pool would either fail fast (no graceful absorption of bursts) or hang forever (no backpressure signal). The default 120 s is the compromise.

When to tune

Common tuning patterns:

  • Lower (e.g. 5 - 30 s): latency-sensitive applications where a 120 s hang is intolerable; operators prefer fast failure + retry.
  • Higher (e.g. 300 - 600 s): batch / analytics workloads where long waits are acceptable and retry storms are undesirable.
  • Leave at default: most OLTP applications; the default is tuned for the common case.

Dicken's post presents the default as the canonical number without discussing tuning, but the default is tuned for typical application workloads.

Seen in

Last updated · 470 distilled / 1,213 read