PgBouncer in production · PostgreSQL

Adding a pooler solves the connection problem and introduces a component. That component sits in the request path of every query, has its own failure modes, and is frequently deployed once and never thought about again.

The version this course targets is PgBouncer 1.25.2, released 2026-05-08. That release is itself a security release addressing several CVEs, which is the first point worth making: a pooler is software in the data path and needs patching like anything else.

Where to put it

flowchart TD
    subgraph A["Sidecar: one pooler per application instance"]
      A1["app replica + pooler"] --> DB1["PostgreSQL"]
      A2["app replica + pooler"] --> DB1
    end
    subgraph B["Shared tier: a pooler service"]
      B1["app replicas"] --> BP["pooler (HA pair)"] --> DB2["PostgreSQL"]
    end
    subgraph C["On the database host"]
      C1["app replicas"] --> CP["pooler on DB host"] --> DB3["PostgreSQL"]
    end

Sidecar, one per application instance. No single point of failure and no extra network hop. The drawback is arithmetic: each pooler has its own pool, so the database sees replicas multiplied by pool size, and the multiplication the pooler was meant to provide is diluted. It works when replica count is small and stable.

A shared pooler tier. Achieves the full multiplication, because one pool serves everything. It is a component that must itself be highly available, and it adds a network hop to every query. This is the common production choice.

On the database host. Removes the network hop between pooler and database and ties the pooler’s availability to the database’s, which is reasonable since one is useless without the other. It does mean the pooler competes for the database host’s CPU, and PgBouncer is single-threaded per process, so a busy pooler can saturate one core while the host looks idle.

Authentication with something in the middle

The pooler terminates the client connection and opens its own to PostgreSQL, so there are two authentication events and they can use different credentials.

The consequences worth planning for:

PostgreSQL sees the pooler’s address, not the client’s. Every client_addr in pg_stat_activity becomes the pooler’s, which is why the earlier lesson insisted on application_name. Your pg_hba.conf rules now describe the pooler rather than the applications, so address-based restrictions move to the pooler’s own configuration.

The pooler needs credentials for every role it proxies. PgBouncer supports looking these up from PostgreSQL through auth_query, which avoids maintaining a parallel credential file, and that lookup itself needs a role with permission to read the authentication catalogue. Granting that carefully matters, because it is a role that can read password hashes.

TLS terminates at the pooler unless deliberately configured otherwise, so the client-to-pooler and pooler-to-database legs are separate TLS decisions. A deployment that encrypts the first and leaves the second in clear has encrypted the leg that was probably already inside the trust boundary and left the one crossing it.

Leaving pooler-to-database traffic unencrypted because the client leg uses TLS

The client connects to the pooler over TLS, the certificate validates, and the connection is reported as encrypted. The second leg is a separate connection with its own configuration, and it defaults to whatever that configuration says rather than inheriting anything.

If the pooler runs on a different host from the database, that second leg carries every query and every result across the network in clear, including the credentials the pooler presents. The client’s TLS says nothing about it.

Configure both legs deliberately and verify the second one from the database side, where pg_stat_ssl reports whether the connection PostgreSQL actually received is encrypted:

SELECT a.pid, a.application_name, a.client_addr, s.ssl, s.version, s.cipher
  FROM pg_stat_activity a
  JOIN pg_stat_ssl s USING (pid)
 WHERE a.backend_type = 'client backend';

That query answers the question about the leg that matters, from the end that cannot be fooled by the other leg’s configuration.

Monitoring the pooler as its own component

PgBouncer’s admin console is a pseudo-database reached with an ordinary PostgreSQL client, and it answers the question no PostgreSQL metric can: is the wait happening before the database or inside it?

-- Connect to the pgbouncer pseudo-database, then:
SHOW POOLS;      -- per database and user: waiting clients, active servers, maxwait
SHOW SERVERS;    -- the connections to PostgreSQL and their state
SHOW CLIENTS;    -- the connections from applications
SHOW STATS;      -- request rates and average query and wait times

SHOW POOLS carries the two columns that matter most:

cl_waiting — clients that have work and no server connection. Any sustained non-zero value means the pool is the constraint.
maxwait — how long the longest-waiting client has been waiting. This is the pooler-side latency contribution, in seconds, and it is invisible from PostgreSQL entirely.

A maxwait of eight seconds with a healthy database means the application’s latency is being created by the pool size, not by query performance. Nobody looking only at PostgreSQL would ever see it, and the natural conclusion from database metrics alone — everything looks fine — is actively misleading.

The diagnostic split that makes a pooler worth its complexity

With a pooler in place, application latency divides cleanly:

Evidence	Means
`cl_waiting` high, `maxwait` high, database idle	The pool is too small, or transactions are held too long
`cl_waiting` zero, database sessions active and waiting	The database is the constraint; use `pg_stat_activity`
Both high	The database is slow and the pool is queuing behind it
Pooler CPU at 100% on one core	The pooler process is the constraint

Without the pooler’s own metrics, the first and second rows are indistinguishable, and they call for opposite actions.

Availability

A shared pooler tier is in the path of every query, so its availability becomes the database’s availability from the application’s point of view.

The patterns that work are the ordinary ones: two or more pooler instances behind a virtual IP or a load balancer, with health checks that verify the pooler can actually reach PostgreSQL rather than merely that its port is open. A pooler accepting connections while unable to reach the database is worse than one that is down, because it accepts work it cannot serve.

The failover interaction matters too, and Part XV returns to it: when the database fails over, the pooler’s existing server connections point at the old primary. Whether the pooler notices, how quickly, and whether it drops client connections in the process are properties to establish by testing rather than by reading, because they determine what the application experiences during a promotion.

Why the pooler cannot make an unhealthy database healthy

A pooler bounds the concurrency the database sees, which is genuinely valuable, and it is worth being clear about what that does not do.

If the database is slow because of a missing index, a lock, or storage latency, the pooler changes where the queue forms rather than whether one forms. Work waits at the pooler instead of arriving as backends. The total throughput is unchanged, because throughput is set by how fast the database completes transactions, and the pooler does not make transactions faster.

What it does buy in that situation is threefold, and each is substantial. The database is not additionally burdened with hundreds of backends while it is already struggling, so it degrades gracefully rather than collapsing. The queue is visible and measurable at the pooler, which is diagnostic information you would not otherwise have. And the system remains in a state it can recover from once the underlying problem is fixed, rather than crossing into the self-reinforcing storm from the previous lesson.

That is the honest claim for a pooler: it converts a collapse into a queue. It does not convert a slow database into a fast one, and a team that adopts one expecting the latter will conclude it did not work.

Production discipline

Patch the pooler. It is software in the data path; 1.25.2 is itself a security release.
Monitor cl_waiting and maxwait from SHOW POOLS. They are the only evidence distinguishing pool-side latency from database latency.
Watch per-process CPU. PgBouncer is single-threaded, so one saturated core on a many-core host is invisible in host averages.
Configure both TLS legs deliberately and verify the pooler-to-database leg from the database with pg_stat_ssl.
Health-check the pooler’s ability to reach PostgreSQL, not just its listening port. Accepting work it cannot serve is worse than being down.
Test what a database failover does to the pooler before you need to know.

Cross-course references

Secrets, PKI & Certificate Management — Part VII (TLS for operators) covers the two-leg TLS question, and Part XIII (Dynamic credentials) covers issuing the credentials the pooler presents.
Kubernetes for Production Sysadmins — Part XXXVIII (Services) and Part XXXIV (PDB) cover running a pooler tier with availability guarantees.
Observability for Production Sysadmins — Part IX (Exporters) covers scraping the pooler’s admin console into metrics so the diagnostic split above is available on a dashboard.