PgBouncer wait time vs query time: is it the pool or the database?

Your application is slow. PgBouncer sits between the application and PostgreSQL, so the first question is always the same: is the latency coming from the pool itself, or from the database behind it? Operators routinely get this split wrong. They see high end-to-end latency, blame PostgreSQL, spend an hour in pg_stat_statements, and then discover avg_query_time was 5ms the whole time while avg_wait_time was 2000ms. The database was fast. The pool was too small.

PgBouncer exposes exactly the two numbers needed to answer this question, and they measure different things. avg_wait_time is queuing delay injected by PgBouncer: time clients spend in the wait queue before a server connection is assigned. avg_query_time is PostgreSQL execution time as seen by PgBouncer: from sending the query to the backend until the complete response comes back. Reading only one of them guarantees a wrong diagnosis. Reading them together, plus avg_xact_time, resolves the attribution in one command.

This article is the working reference for that split: what each metric actually measures, the decision matrix for assigning blame, and the checks to confirm before you touch pool_size or start hunting slow queries.

What this means

Every request through PgBouncer has two latency phases:

1. Queue phase. The client has sent a query but no server connection is free. It waits in a FIFO queue until one becomes available. PgBouncer accumulates this as wait time. In a healthy deployment this phase is effectively zero.
2. Execution phase. The client has a server connection and its query runs on PostgreSQL. This is query time, and it includes the network round trip between PgBouncer and the backend.

The two phases are causally linked but owned by different components:

• High wait time + low query time. The database is executing fast, but all server connections are busy so clients queue. The pool is undersized, or connections are being held too long. Fix on the PgBouncer side: raise pool_size, or find what is holding connections.
• Low wait time + high query time. Clients get a server connection immediately, then sit waiting on PostgreSQL. The pool is fine. Fix on the PostgreSQL side: slow queries, lock contention, I/O saturation.
• Both high. Usually a cascade: slow queries hold connections longer, the pool saturates, and queuing begins. The root cause is PostgreSQL, but the visible symptom includes queue depth. Fix PostgreSQL first; do not raise pool_size to absorb a backend problem, that just moves the queue into the database.
• avg_xact_time much larger than avg_query_time. The gap is idle-in-transaction time: clients hold a server connection between statements while doing application work. This looks like “pool too small” but the fix is application behavior, not pool size.

One version caveat that changes how you read avg_wait_time: before PgBouncer 1.23.0 the calculation did not divide by the number of clients, so it reported something closer to “wait time per second” than a true average. Values could be absurdly large and were not comparable across deployments. The fix shipped in 1.23.0 (PR #727), which also added total_server_assignment_count and avg_server_assignment_count to SHOW STATS as the denominator. On versions older than 1.23.0, treat avg_wait_time with suspicion and use maxwait from SHOW POOLS as your primary wait signal.

A second caveat on avg_query_time: PgBouncer does not parse SQL, so BEGIN and COMMIT count as separate queries. A transaction of BEGIN, one 30ms SELECT, COMMIT is counted as three queries, which inflates query count and deflates avg_query_time. When the numbers do not line up with what PostgreSQL reports, check avg_xact_time instead. Confirmed by GitHub issue #959.

Common causes

Quick checks

All read-only. Run against the admin console:

# The core split: averages per database (stable column layout)
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW STATS_AVERAGES;"

# Current queue state per pool: cl_waiting, sv_active, sv_idle, maxwait
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW POOLS;"

# Which server connections are held and for how long (request_time on active)
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW SERVERS;"

# Confirm the database is not administratively paused or disabled
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW DATABASES;"

# PgBouncer version: avg_wait_time semantics changed in 1.23.0
psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -Atc "SHOW VERSION;"

# Event loop health: admin console should answer in well under 50ms
time psql -h /var/run/postgresql -p 6432 -U pgbouncer pgbouncer -c "SHOW LISTS;" > /dev/null

Notes on reading the output:

• Values in SHOW STATS_AVERAGES are per-second rates (counts) and microseconds (times), averaged over stats_period (default 60s). Short spikes get smoothed.
• Reference SHOW STATS columns by name, not position. Column positions shift across versions (1.23 added server_assignment_count, 1.24 added prepared statement counters). SHOW STATS_AVERAGES has a simpler, more stable layout.
• Total counters (total_query_time, total_wait_time, total_xact_count) are cumulative since startup and reset on restart. Prefer the avg_* columns, or compute deltas between two samples yourself, e.g. delta(total_query_time) / delta(total_query_count).

How to diagnose it

1. Rule out administrative state first. Check SHOW DATABASES for paused = 1 or disabled = 1. During PAUSE, cl_waiting spikes and sv_active drops to zero by design. Every other signal is meaningless until you confirm normal operation.
2. Check PgBouncer itself. Time an admin console command. If SHOW LISTS takes more than about 200ms, the single-threaded event loop is strained and every metric downstream is suspect. Check process CPU: PgBouncer pinned at 100% of one core distorts both wait and query time. Normal is under 5%.
3. Pull the three averages. From SHOW STATS_AVERAGES, compare wait_time, query_time, and xact_time per database. Convert microseconds to milliseconds before comparing; mixing units is a common source of wrong conclusions.
4. Apply the decision matrix below to assign the latency to pool, database, or transaction shape.
5. Confirm on the second component. If the matrix says “pool,” verify with SHOW POOLS: sv_active at pool_size, sv_idle at zero, cl_waiting above zero, maxwait climbing. If it says “database,” verify on PostgreSQL with pg_stat_activity and pg_stat_statements. If it says “idle in transaction,” run the pg_stat_activity query in the Fixes section and correlate with SHOW SERVERS request_time.
6. Check which pool. Stats are per database; pools are per (database, user). One saturated pool can hide inside a healthy aggregate. Look at SHOW POOLS row by row, not at a global rollup.

flowchart TD
    A[App latency high] --> B{paused or disabled?}
    B -- yes --> Z[Expected maintenance behavior]
    B -- no --> C{Admin console fast?
CPU below 100% of one core?}
    C -- no --> D[PgBouncer event loop is the problem]
    C -- yes --> E{avg_wait_time high?}
    E -- yes --> F{avg_query_time also high?}
    F -- no --> G[Pool too small or
connections held too long]
    F -- yes --> H[Backend slow, pool saturated
as consequence: fix PostgreSQL first]
    E -- no --> I{avg_query_time high?}
    I -- yes --> J[Database is slow:
pg_stat_statements, locks, I/O]
    I -- no --> K{avg_xact_time much
greater than avg_query_time?}
    K -- yes --> L[Idle-in-transaction:
fix application behavior]
    K -- no --> M[Latency is outside PgBouncer:
check network and app tier]

Metrics and signals to monitor

Fixes

Pool undersized: high wait, low query time

The database is fast but there are not enough server connections. Raise default_pool_size or the per-database pool_size, then RELOAD. Sizing guidance from the pool’s own math: required_pool_size is roughly transactions_per_second x avg_xact_time_in_seconds. Leave headroom for bursts; keep sv_idle above zero at peak. If reserve_pool_size is configured and regularly drawn from, the base pool is chronically undersized: the reserve is for spikes, not steady state. Keep the sum of all pool sizes under roughly 80% of PostgreSQL max_connections, accounting for superuser_reserved_connections and other PgBouncer instances targeting the same backend.

Backend slow: low wait, high query time

Do not touch pool_size; adding connections against a slow database just adds load. Work the PostgreSQL side: pg_stat_statements for the slowest calls, pg_stat_activity for lock waits, disk I/O on the database host. Also check server_reset_query: the default DISCARD ALL runs on connection return in session mode, and if the backend is slow to execute it (for example, many temp tables to clean), that overhead shows up inside avg_query_time and masquerades as “the database being slow.”

Idle in transaction: avg_xact_time » avg_query_time

The gap between the two averages is the time applications hold server connections while doing non-database work. No pool size fixes this; it only buys time. Confirm on PostgreSQL:

# Find connections holding transactions open without running queries
psql -h <postgres-host> -U <user> -d <db> -c \
"SELECT pid, state, now() - xact_start AS xact_duration, query
 FROM pg_stat_activity
 WHERE state = 'idle in transaction'
 ORDER BY xact_duration DESC;"

Trace offenders back through PgBouncer: SHOW SERVERS gives the link column for active connections, SHOW CLIENTS maps it to a source address. The durable fix is application-side (commit promptly, do not span transactions across application work). As a guardrail, consider PostgreSQL’s idle_in_transaction_session_timeout to auto-terminate the worst offenders; coordinate with the application team, since terminating a transaction rolls it back.

Both high: cascade

Slow queries hold connections, the pool saturates, and the queue grows. Killing the right query frees the pool faster than any config change. Identify long-running backends and cancel them with pg_cancel_backend or pg_terminate_backend. This is disruptive: the client through PgBouncer receives an error and the transaction rolls back. Coordinate before terminating anything in production.

Event loop saturation

If PgBouncer itself is the bottleneck (one core at 100%, slow admin console), the split metrics will mislead you. Usual drivers are TLS handshakes at high connection churn, excessive logging, or extremely high query rates. Options: offload TLS to a proxy in front, or scale out with multiple PgBouncer processes via so_reuseport, aggregating stats across processes when you monitor.

Prevention

• Alert on the pair, never one metric. A wait-time alert without a query-time check will send you to the wrong component. Include paused/disabled state as a suppression condition so maintenance windows do not page.
• Alert on sustained maxwait, not on cl_waiting > 0. Brief queuing during bursts is normal in transaction mode. maxwait above a threshold that reflects your application timeout separates “burst” from “stuck.”
• Track the xact-to-query gap as a standing ratio. A rising avg_xact_time / avg_query_time ratio is idle-in-transaction developing weeks before it exhausts the pool.
• Upgrade past 1.23.0 for trustworthy avg_wait_time. On older versions, build dashboards and alerts around maxwait instead.
• Watch headroom, not just incidents. sv_idle trending toward zero, or sv_active/pool_size trending up over weeks, is the queue forming before it exists. That is the time to resize, not during the incident.

How Netdata helps

• Netdata collects SHOW POOLS, SHOW STATS, and SHOW STATS_AVERAGES per database, so avg_wait_time, avg_query_time, and avg_xact_time are graphed on the same timeline and the split is visible at a glance.
• Per-pool cl_waiting and maxwait are captured at high resolution, catching short queuing bursts that a 60-second polling loop would smooth away.
• The avg_xact_time vs avg_query_time gap is visible as two diverging series, surfacing idle-in-transaction before it exhausts the pool.
• sv_active against configured pool_size gives the utilization ratio that leads cl_waiting, so you see saturation forming rather than arriving.
• Host-level CPU for the PgBouncer process sits next to the pooler metrics, which makes the “is it the event loop?” check a one-screen correlation instead of a separate SSH session.

Related guides

• PgBouncer avg_wait_time high: the latency the pool itself is injecting
• PgBouncer maxwait high: the oldest client waiter and how close it is to timing out
• PgBouncer capacity planning: runway for pools, clients, and PostgreSQL slots
• PgBouncer backend unreachable: PostgreSQL down and the pool draining
• PgBouncer client connection leak: idle clients that never disconnect
• PgBouncer monitoring checklist: the signals every connection pooler needs
• How PgBouncer actually works in production: a mental model for operators