PgBouncer Operations Guides on Netdata

How PgBouncer actually works in production: a mental model for operators

Mon, 01 Jan 0001 00:00:00 +0000

Most PgBouncer incidents are the predictable consequence of a handful of internal mechanisms interacting under load: a single-threaded event loop, per-pool FIFO wait queues, fixed-size socket buffers, a small set of server connection states, and a pool mode that decides when server connections change hands. Hold these in your head and the alert thresholds stop being arbitrary numbers.

This article is the model, not the triage. It explains what PgBouncer is doing internally so that when cl_waiting spikes or sv_login won’t drain, you already know which part of the machine is hurting and why.

PgBouncer advisory locks in transaction mode: orphaned locks and mysterious contention

Mon, 01 Jan 0001 00:00:00 +0000

Your application takes an advisory lock with pg_advisory_lock(), does its work, releases it, and moves on. Except under load, other parts of the application start blocking on that same lock, or timing out waiting for it. The application is sure it released the lock. PostgreSQL’s lock views, looked at from the wrong place, show nothing. PgBouncer’s metrics are completely healthy: no waiting clients, no queue, normal wait times.

This is not a saturation problem and not a bug in PgBouncer. It is a semantic mismatch between how advisory locks work in PostgreSQL and how transaction pooling reassigns server connections.

PgBouncer and PostgreSQL max_connections: when pool_size outruns the backend limit

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer exists to reduce the number of connections PostgreSQL has to hold, so it is easy to assume that adding PgBouncer makes the connection limit problem go away. It does not. PgBouncer is itself a consumer of PostgreSQL connection slots, and its worst-case demand is arithmetic you control in config files: one pool per (database, user) pair, each pool allowed to open pool_size server connections, plus reserve_pool_size overflow, multiplied by every PgBouncer instance pointing at the same backend.

PgBouncer auth failed / password authentication failed: client login rejected

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer logs closing because: auth failed when a client fails to authenticate against the pooler itself. This is client-side authentication: the connection between your application and PgBouncer, not between PgBouncer and PostgreSQL. The connection is rejected before it enters any pool.

These events are log-only. PgBouncer exposes no SHOW command counter for authentication failures. There is no auth_failed_count in SHOW STATS, no per-user rejection tally, no rate metric. If you are not parsing the log, you are blind to auth failures.

PgBouncer auth_query failures: the authentication dependency loop on PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

Clients cannot connect. The PgBouncer log fills with “password authentication failed” and “S: login failed” messages. SHOW POOLS shows sv_login connections stuck in the login state, cl_waiting climbing. If you use auth_query to authenticate clients against PostgreSQL, the root cause may be neither a wrong password nor a down database: it may be the circular dependency that auth_query creates between the pooler and the backend.

auth_query tells PgBouncer to authenticate each connecting client by running a SQL query against PostgreSQL to look up that user’s password hash. You still need auth_file (userlist.txt) for auth_user credentials, but you do not need to sync every application user’s password into it. The cost: every new client connection requires a working PostgreSQL connection before the client can be pooled. When PostgreSQL is healthy, this is invisible. When PostgreSQL is under load, or when PgBouncer restarts and hundreds of clients re-authenticate simultaneously, auth_query becomes the bottleneck that amplifies the outage.

PgBouncer avg_query_time high: reading backend slowdown through the pooler

Mon, 01 Jan 0001 00:00:00 +0000

avg_query_time in PgBouncer’s SHOW STATS output just doubled, and now cl_waiting is starting to flicker above zero. This is the classic early-warning sequence for a pool exhaustion cascade: queries take longer, server connections are held longer, pool utilization climbs, and clients begin to queue. Catching the rise at the avg_query_time stage, before cl_waiting climbs, is the difference between a quiet Tuesday fix and a paged incident.

The trap is that avg_query_time is an average, and PgBouncer exposes no percentiles. A workload of 95% 1ms queries and 5% 500ms queries averages to a harmless-looking 26ms while the slow tail is already wrecking pool utilization. This article covers what the metric actually measures, how to diagnose a real rise versus an artifact, and how to trace the slowdown through to PostgreSQL.

PgBouncer avg_wait_time high: the latency the pool itself is injecting

Mon, 01 Jan 0001 00:00:00 +0000

Your application latency is up, PostgreSQL looks fine, and then PgBouncer’s stats show avg_wait_time at tens or hundreds of milliseconds. That number answers “where did the latency come from”: it is time clients spent queued inside PgBouncer waiting for a server connection, before their query even reached PostgreSQL.

avg_wait_time is purely PgBouncer-induced latency. A direct connection to PostgreSQL would not have it. When it is high, the pool is not keeping up with demand, and every queued client pays that delay on top of normal query execution time.

PgBouncer backend unreachable: PostgreSQL down and the pool draining

Mon, 01 Jan 0001 00:00:00 +0000

Clients are queueing in PgBouncer, wait times are climbing, and SHOW POOLS shows fewer server connections than there were an hour ago. Nobody changed the config. The likely cause: PostgreSQL is down, network-partitioned, or rejecting connections, and PgBouncer cannot establish new server connections to replace the ones it is losing.

This failure mode is deceptive because it degrades slowly. Existing server connections keep serving queries until they expire (server_lifetime, default 3600s), go idle past server_idle_timeout (default 600s), or error out. The pool drains gradually rather than failing all at once. Meanwhile clients pile into the wait queue and eventually get disconnected at query_wait_timeout (default 120s).

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

Mon, 01 Jan 0001 00:00:00 +0000

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.

PgBouncer client connection leak: idle clients that never disconnect

Mon, 01 Jan 0001 00:00:00 +0000

used_clients keeps climbing. Traffic is flat, cl_waiting is zero, queries are fast, and yet the client count creeps toward max_client_conn day after day. When it gets there, PgBouncer starts rejecting new connections with no more connections allowed (max_client_conn), even though the database itself is completely healthy.

This is a client-side connection leak: application instances open connections to PgBouncer and never close them. PgBouncer is doing exactly what it is told to do, holding those sockets open. The pooler just makes the leak visible earlier and more painfully, because it has a hard front-door limit.

PgBouncer database paused or disabled: maintenance state that looks like an outage

Mon, 01 Jan 0001 00:00:00 +0000

cl_waiting is climbing, sv_active just dropped to zero, maxwait is ticking upward. The pattern looks identical to pool exhaustion or a backend failure. But if someone is running planned PostgreSQL maintenance with PAUSE, the metrics are behaving as designed: PAUSE stops new query routing, existing transactions finish, server connections close, and every pending client queues. From the client’s perspective, it looks like an outage. The difference is that it is planned and reversible with RESUME.

PgBouncer event loop stall: the single thread that freezes every pool at once

Mon, 01 Jan 0001 00:00:00 +0000

Every client connection, server connection, DNS lookup, and admin command runs on a single libevent thread inside PgBouncer. When something blocks that thread, every pool on every database freezes at the same time. Clients queue everywhere. The admin console itself becomes slow or unresponsive. This is not pool exhaustion; it is the entire process stalled.

The signature is simultaneity. In normal pool exhaustion, one (database, user) pool saturates while others stay healthy. In an event loop stall, all pools degrade together, and the SHOW LISTS command you run to diagnose the problem takes seconds to return. That admin console latency is the tell.

PgBouncer high CPU: single-core saturation, TLS, and connection churn

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer is consuming a disproportionate share of one CPU core. The process sits at 70%, 90%, or 100% of a single core while system-wide CPU looks normal. Application queries slow down and the admin console feels sluggish.

PgBouncer is a single-threaded, event-driven process built on libevent. It runs on exactly one CPU core regardless of how many cores the machine has. A busy PgBouncer looks nearly idle on a multi-core box because system-wide CPU averages dilute the one saturated core. Measure per-process or per-core CPU, not system-wide averages.

PgBouncer idle in transaction: the silent pool killer in transaction mode

Mon, 01 Jan 0001 00:00:00 +0000

Your PgBouncer pool looks busy: sv_active is pinned at pool_size, cl_waiting is climbing, and applications are timing out. But PostgreSQL is barely doing anything. CPU is low, avg_query_time is a few milliseconds, and there are no slow queries to kill. The pool is full of connections that are “active” yet running nothing at all.

This is the idle-in-transaction pattern, and it is the most common silent killer in transaction-mode PgBouncer deployments. An application runs BEGIN, gets assigned a server connection, runs a query, then goes off to do non-database work (HTTP calls, serialization, computation, waiting on another service) before coming back to COMMIT. In transaction pooling mode, that server connection stays assigned to the client for the entire transaction, including every second the client spends not talking to the database. Enough clients doing this and every server connection is checked out but idle. Everyone else queues.

PgBouncer LISTEN/NOTIFY not working: why pub/sub needs session pooling

Mon, 01 Jan 0001 00:00:00 +0000

Your application issues LISTEN job_events, the command succeeds, and PostgreSQL’s logs show NOTIFY firing on schedule. But the listener never receives anything. No error in the application. No error in PgBouncer. No metric anywhere that moves. The feature worked in staging, worked before you put PgBouncer in front of the database, and now it silently does nothing.

This is the pool mode mismatch failure pattern, and LISTEN/NOTIFY is its most confusing variant because the failure is completely silent. Unlike prepared statements (which at least produce “prepared statement does not exist” errors), a lost LISTEN registration produces no error at all. The notification is delivered to a backend connection your client no longer holds, or to whichever client happens to hold that connection next.

PgBouncer max_client_conn tuning: setting the client limit against real FD headroom

Mon, 01 Jan 0001 00:00:00 +0000

Applications fail with connection errors, but PgBouncer’s pools look healthy: sv_active is well below pool_size, cl_waiting is zero, and PostgreSQL is idle. The log tells the real story: no more connections allowed (max_client_conn) or accept failed: Too many open files. Clients are being refused before they ever reach a pool.

The usual root cause is a mismatch between two limits operators treat as one. max_client_conn is a configuration value. The OS file-descriptor limit (ulimit -n) is a hard kernel ceiling. PgBouncer cannot accept more client connections than it has file descriptors for, no matter what the config says. If you set max_client_conn = 10000 while the process runs with the default 1024 FD limit, PgBouncer lowers the value at startup or hits the FD ceiling under load and refuses connections long before you expect it to.

PgBouncer maxwait high: the oldest client waiter and how close it is to timing out

Mon, 01 Jan 0001 00:00:00 +0000

You opened SHOW POOLS because an application is slow, and one column stands out: maxwait is 8, 20, maybe 90 seconds. That number is the age of the oldest client sitting in PgBouncer’s FIFO wait queue, computed from the query_start of the first waiter. It is the worst-case queuing latency any client is experiencing right now, before its query even reaches PostgreSQL.

maxwait is more actionable than the cl_waiting count. cl_waiting tells you how many clients are blocked; maxwait tells you how much it hurts. A queue of 50 clients that drains in 200ms is a burst. A queue of 3 clients where the oldest has waited 45 seconds is an incident.

PgBouncer memory growth: RSS, pkt_buf, and the slab allocator

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer’s RSS is bounded by configuration: max_client_conn plus the total server connection budget. The process pre-allocates connection structures at startup, so RSS stabilizes after warmup and should not grow monotonically under stable load. When it does, the cause is usually one of: pkt_buf set too high, TLS session overhead, or a version-specific leak.

Why RSS matters for PgBouncer

PgBouncer allocates memory proportional to connection count. The base cost is roughly 2KB per idle connection for socket buffer bookkeeping and connection metadata. For 10,000 clients, that is approximately 30-50MB of RSS at default settings. Active connections cost more because packet buffers are allocated to handle I/O.

PgBouncer monitoring checklist: the signals every connection pooler needs

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer is not a database. It is a single-threaded, event-driven proxy that multiplexes many client connections onto a smaller set of PostgreSQL connections, and it should be monitored the way you monitor HAProxy or nginx: queueing, connection exhaustion, and process health. The teams that get burned monitor PgBouncer with their PostgreSQL playbook (replication lag, WAL, bloat) and never check whether clients are actually waiting for connections.

This checklist is organized by maturity level. Start at Level 1, get it alerting correctly, then work down. Every signal below comes from the admin console, the process table, or the PgBouncer log. There is no other source.

PgBouncer monitoring maturity model: from survival to expert

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer usually fails as a proxy, not as a process: it is alive, the port is open, the dashboards are green, and clients are still waiting two minutes for a server connection because nobody watched the wait queue. Its important failure modes are queueing, connection exhaustion, event loop stalls, and stale DNS. Most default database checks do not see them.

This model has four levels, from “is it alive” to “correlate pool behavior with PostgreSQL and the application.” Each level answers a specific operational question. The goal is not to reach Level 4. The goal is to know which level you are actually at, and what you are blind to because of it.

PgBouncer no more connections allowed (max_client_conn): the front door is full

Mon, 01 Jan 0001 00:00:00 +0000

Your application logs fill with connection errors, and every new connection attempt to PgBouncer fails immediately with:

ERROR: no more connections allowed (max_client_conn)

This is not pool exhaustion. The client never gets in the door. There is no queue, no wait, no query_wait_timeout. PgBouncer counts the client connection, sees it would exceed max_client_conn, and refuses it on the spot. Existing clients keep working; only new ones are turned away.

The confusing part is that the pool itself may be completely healthy. sv_active can be well below pool_size, cl_waiting can be zero, and avg_wait_time can be flat. PostgreSQL is fine, the pools are fine, and yet applications cannot connect. The bottleneck is the front door, not the backend.

PgBouncer pool exhaustion: clients queue, wait times climb, and the retry cascade

Mon, 01 Jan 0001 00:00:00 +0000

Every server connection in a pool is busy. sv_active equals pool_size, sv_idle is zero, and cl_waiting is climbing. Clients that were getting sub-millisecond connection assignment are now sitting in a FIFO queue, and the oldest waiter (maxwait) is old enough that application timeouts are firing. This is PgBouncer pool exhaustion, the most common PgBouncer incident, and it has a nasty property: it feeds itself.

The cascade works like this. Server connections are held too long, so new client requests queue. Application-side timeouts are almost always shorter than PgBouncer’s query_wait_timeout (default 120 seconds), so the application gives up first, retries, and adds a fresh waiter to the queue behind the one that never left. Retries arrive faster than the queue drains. cl_waiting snowballs until max_client_conn (default 100) is reached, at which point new connections are refused outright with "no more connections allowed (max_client_conn)" in the log. What started as one slow query becomes a full outage.

PgBouncer pool utilization high: sv_active approaching pool_size before clients queue

Mon, 01 Jan 0001 00:00:00 +0000

Your alert fired on sv_active / pool_size > 85%, or you spotted the ratio creeping up on a dashboard. No clients are waiting yet. cl_waiting is zero. Latency looks normal. This is exactly the moment this signal exists for: it is the last cheap warning you get before the pool goes over the cliff.

PgBouncer pool saturation is not a gradual degradation. Below 100% utilization, client wait time is approximately zero because server connection assignment is instant. At 100%, the next client request has nowhere to go and enters a FIFO queue with unbounded wait. There is no “slow but working” middle state. The ratio of sv_active to pool_size tells you how close you are to that edge, and it moves before cl_waiting, maxwait, and avg_wait_time show anything.

PgBouncer pool_size sizing: matching pool capacity to transaction time and throughput

Mon, 01 Jan 0001 00:00:00 +0000

pool_size decides how many queries can execute at once through PgBouncer. It is also the setting most teams guess at: leave the default, raise it when something breaks, lower it when PostgreSQL complains about connections. The correct value falls out of two numbers you can measure in a minute: peak transactions per second, and how long the average transaction holds a server connection.

This article gives you the sizing relationship, shows how to measure its inputs from PgBouncer’s own stats, works through concrete examples, and covers the constraints that bound the answer: per-database overrides, cold start behavior, and the hard ceiling imposed by PostgreSQL’s max_connections.

PgBouncer prepared statement does not exist: transaction pooling and lost session state

Mon, 01 Jan 0001 00:00:00 +0000

Your application starts throwing prepared statement "..." does not exist errors in production. PgBouncer is healthy: no queuing, no wait time, pools well under capacity, PostgreSQL is fast. Single-user testing never reproduces it. Restarting the app makes it go away for a while, then it comes back under load.

This is the pool mode mismatch failure pattern, and it is one of the nastier PgBouncer failure modes because every infrastructure signal looks green. The error is a SQL-level error from PostgreSQL, not a connectivity error from PgBouncer. Nothing in SHOW POOLS or SHOW STATS points at it. The only place it shows up is application error logs.

PgBouncer process down: the single point of failure in front of PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer is one process on one host. Its single-threaded libevent loop handles every client socket, server socket, DNS lookup, and admin command on one CPU core. This gives it low overhead (roughly 2KB per idle connection) but makes it a hard single point of failure. When the PID disappears, the event loop stalls, or the process crash-loops, all database traffic through that instance is severed at once.

Failure modes range from clean process death (OOM kill, segfault) to states where the process is alive, the port is open, but the event loop is frozen. A pgrep check or port probe misses the latter. The correct health check is functional: connect to the admin console and run SHOW VERSION. If it hangs or fails, PgBouncer is operationally down regardless of what systemd reports.

PgBouncer query rate drop: throughput falling without a traffic change

Mon, 01 Jan 0001 00:00:00 +0000

Your PgBouncer dashboard shows queries per second falling off a cliff, but the application team insists nothing changed: no deploy, no traffic shift, no feature flag. The avg_query_count from SHOW STATS (or the delta of total_query_count) is down 40, 60, maybe 90 percent from baseline, and it is not coming back.

A query rate drop with stable inbound traffic is almost never a PgBouncer bug. It is a symptom of something downstream or upstream: queries are taking longer so fewer complete per second, clients are queued instead of executing, the backend is unreachable, or the application itself has stopped sending work. The query rate is the smoke; your job is to find which fire is producing it.

PgBouncer query_wait_timeout: clients disconnected after waiting too long for a connection

Mon, 01 Jan 0001 00:00:00 +0000

Your PgBouncer log is filling with pooler error: query_wait_timeout lines and application teams are reporting intermittent database errors. The error string sounds like a query problem. It is not. query_wait_timeout fires when a client has been sitting in PgBouncer’s wait queue, blocked on getting a server connection, for longer than the configured timeout. The client never reached PostgreSQL.

The default is 120 seconds. When this error appears, the pool has been exhausted for at least that long. query_wait_timeout is a lagging indicator: it tells you an incident happened, not that one is starting.

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

Mon, 01 Jan 0001 00:00:00 +0000

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.

PgBouncer SCRAM / auth_type mismatch: md5 vs scram-sha-256 login failures

Mon, 01 Jan 0001 00:00:00 +0000

Clients cannot log in through PgBouncer. Authentication fails with errors that look like wrong passwords, but the passwords are correct and PostgreSQL accepts them on direct connection.

The root cause is a mismatch between PgBouncer’s auth_type and PostgreSQL’s password_encryption or pg_hba.conf method. PostgreSQL 12+ defaults to scram-sha-256 for password_encryption. Deployments that upgrade PostgreSQL without updating PgBouncer’s auth configuration break silently because the authentication mechanisms are incompatible, not the credentials.

This article covers how to identify the specific mismatch, align auth_type with PostgreSQL’s password method, store SCRAM verifiers correctly, and migrate from md5 to scram without breaking existing connections.

PgBouncer server DNS lookup failed: stale cache and failed failover

Mon, 01 Jan 0001 00:00:00 +0000

You see server DNS lookup failed in the PgBouncer log, usually right after a PostgreSQL failover, a DNS change, or a network event. New server connections cannot be established. Depending on timing, you may instead see the nastier variant: no error at all, just a pool quietly draining because PgBouncer’s DNS cache still points at the old primary IP.

PgBouncer maintains its own DNS cache, independent of the TTL your DNS records publish. The cache lifetime is controlled by dns_max_ttl (default: 15 seconds). After a failover, up to dns_max_ttl can pass before PgBouncer even becomes eligible to re-resolve the backend hostname. Cached results are only re-queried when a new server connection is needed, so existing connections to the old IP keep running (against a dead or read-only host) while nothing forces a fresh lookup.

PgBouncer server login failed: PgBouncer cannot authenticate to PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

Your PgBouncer log is filling with closing because: server login failed (or server login timed out), and application latency is climbing. PgBouncer accepts client connections fine. It can even reach PostgreSQL over the network. But every attempt to complete the backend login handshake fails, so no new server connections enter the pool.

The symptom pattern is distinctive: sv_login stays elevated while sv_idle drains toward zero and cl_waiting grows. Existing server connections keep working until they expire or are recycled, but nothing replaces them. The pool shrinks from the inside while clients pile up in the wait queue. If nothing is fixed, the pool empties completely and every client waits until query_wait_timeout (default 120s) fires.

PgBouncer server_lifetime recycling waves: synchronized reconnects and capacity dips

Mon, 01 Jan 0001 00:00:00 +0000

Your dashboards show a repeating pattern: every hour (or whatever server_lifetime is set to), sv_login spikes, sv_idle drops, and there is a brief bump in cl_waiting or avg_wait_time. It lasts seconds to a couple of minutes, then everything is green again. Application latency ticks up at the same moment. It looks like a flaky backend, but PostgreSQL is fine and the timing is suspiciously regular.

This is the server_lifetime recycling wave. PgBouncer closes each server connection once it has been connected longer than server_lifetime (default 3600 seconds) and opens a replacement. If a large share of your server connections were created at roughly the same moment, which is exactly what happens after a PgBouncer restart, a PostgreSQL failover, or a cold start under load, they all hit the lifetime limit together and reconnect in lockstep. The pool briefly runs short on backend connections while the replacements authenticate.

PgBouncer server_reset_query and DISCARD ALL: the hidden per-return overhead

Mon, 01 Jan 0001 00:00:00 +0000

Every time PgBouncer returns a server connection to the pool in session pooling mode, it runs a cleanup query on that connection before anyone else can use it. By default that query is DISCARD ALL, which wipes every piece of session state PostgreSQL is holding: temp tables, prepared statements, SET variables, advisory locks, cursors, LISTEN subscriptions. The reset is what makes connection sharing safe. It is also a backend round trip you pay for on every connection return, and it is rarely accounted for.

PgBouncer SET search_path lost between queries: session variables in transaction mode

Mon, 01 Jan 0001 00:00:00 +0000

Your application sets search_path (or timezone, or role, or statement_timeout) after connecting, and everything works in staging. In production, under concurrent load, queries intermittently hit the wrong schema, run with the wrong role context, or fail with “relation does not exist” for tables that clearly exist. Restarting the app “fixes” it briefly. Nothing in PgBouncer’s metrics looks wrong.

This is pool mode mismatch: the application depends on session-level state, but PgBouncer is running in transaction pooling mode, where a client is assigned a different server connection for every transaction. Session state set on one server connection is not present on the next one. The failure is silent, load-dependent, and looks exactly like an application logic bug. PgBouncer itself reports nothing.

PgBouncer sv_idle at zero: no headroom and one slow query from a cascade

Mon, 01 Jan 0001 00:00:00 +0000

Your PgBouncer dashboards look green. cl_waiting is zero, maxwait is zero, no clients are queuing, no errors in the log. But SHOW POOLS tells a different story: sv_idle is 0 and sv_active equals pool_size. Every server connection in the pool is checked out. Nothing is waiting yet, but nothing is available either.

This is the “looks green, is actually yellow” state, and it is one of the most dangerous steady states a connection pooler can sit in. The next request that arrives while all connections are busy queues immediately. There is no buffer, no graceful degradation. PgBouncer’s saturation curve is cliff-edge: below 100% utilization, assignment latency is effectively zero; at 100%, latency jumps to unbounded FIFO queuing.

PgBouncer thundering herd after restart: a login storm against PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer just restarted. Maybe you pushed a config change that required it, maybe the process crashed, maybe the OOM killer took it out and systemd’s Restart=always brought it right back. Within seconds, your dashboards light up: clients are queueing, wait times spike, and PostgreSQL is suddenly absorbing hundreds of simultaneous connection attempts. Then, usually, it calms down on its own within 10 to 60 seconds.

This is a structural property of how PgBouncer works, not a bug. PgBouncer holds all of its server connections in process memory. When the process dies, every cached backend connection dies with it. The moment the new process starts accepting clients, every incoming query needs a brand new server connection, and every pool tries to build them all at once.

PgBouncer TLS: encrypted client and server connections, and certificate expiry

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer terminates or initiates TLS on two independent legs: the client leg (application to PgBouncer) and the server leg (PgBouncer to PostgreSQL). Each leg has its own configuration, certificate chain, and failure modes. Enabling TLS on one tells you nothing about the other.

This independence is the source of most TLS operational surprises. A deployment can have fully encrypted client connections while the backend leg runs in plaintext, and nothing in PgBouncer’s metrics flags the discrepancy. The only reliable audit is the tls column in SHOW CLIENTS and SHOW SERVERS.

PgBouncer Too many open files: file descriptor exhaustion and refused connections

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer is logging Too many open files and clients are being turned away, or connections to PostgreSQL are failing with the same OS error. The confusing part: used_clients is nowhere near max_client_conn, the pools look healthy, and yet new connections are refused. The front door is not full. The kernel is out of file descriptors.

PgBouncer is FD-hungry by design. Every proxied connection consumes roughly two file descriptors, one for the client socket and one for the server socket, plus a baseline of listening sockets, admin console sockets, DNS resolver sockets, and the log file. When the process hits its Max open files limit, three things break at once: accept() on the listen socket fails so new clients cannot connect, new server connections to PostgreSQL cannot be opened so existing clients start queuing, and log writes can fail so diagnostics disappear exactly when you need them.

PgBouncer transaction vs session pooling: what each mode breaks and when to use it

Mon, 01 Jan 0001 00:00:00 +0000

pool_mode is the most consequential setting in pgbouncer.ini. It decides when a server connection is returned to the pool, which in turn decides how many PostgreSQL backends you need and which PostgreSQL features your application is no longer allowed to use.

The failure pattern that brings people to this page is consistent: someone switches from session to transaction for efficiency, deploys, and hours or days later the application starts throwing intermittent “prepared statement does not exist” errors, losing temp tables mid-request, or leaking advisory locks. Every PgBouncer metric looks healthy. The breakage only shows up under concurrency, because single-user testing keeps landing on the same backend.

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

Mon, 01 Jan 0001 00:00:00 +0000

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.