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.
TLS also changes PgBouncer’s resource profile. Every encrypted connection costs 20-50KB of memory instead of approximately 2KB, and every handshake burns CPU on the single-threaded event loop. Certificate expiry is a third concern: PgBouncer does not expose it as a metric, and an expired certificate on either leg causes total, silent login failure.
The two-leg TLS model
PgBouncer sits between application clients and PostgreSQL. Each direction of TLS is controlled by a separate set of parameters in the [pgbouncer] section of the configuration file.
flowchart LR
App["Application clients"] -->|"client_tls_sslmode\ndefault: disable"| PGB["PgBouncer\n(single-thread event loop)"]
PGB -->|"server_tls_sslmode\ndefault: prefer"| PG["PostgreSQL"]Client leg
The client_tls_sslmode parameter controls whether PgBouncer accepts encrypted connections from applications. It defaults to disable (plain TCP, no TLS). To enable TLS, set it to require, verify-ca, or verify-full:
disable: no TLS (default)allow: TLS if the client requests it, plaintext otherwise; client certificates not validatedrequire: TLS required, certificates not validatedverify-ca: TLS required, client certificates verified against a configured CAverify-full: TLS required, client certificates verified including hostname
Accompanying parameters include client_tls_key_file, client_tls_cert_file, client_tls_ca_file (needed for verify-ca and verify-full), client_tls_protocols, and client_tls_ciphers. The ECDH curve and DH parameter defaults are controlled by client_tls_ecdhcurve (default: auto) and client_tls_dheparams (default: auto).
PgBouncer 1.25.0 reportedly added support for client-side direct TLS connections, the faster TLS setup introduced in PostgreSQL 17. The server leg does not yet support this optimization.
Server leg
The server_tls_sslmode parameter controls whether PgBouncer encrypts its own connections to PostgreSQL. It defaults to prefer:
disable: no TLSprefer: use TLS if the server supports it, fall back to plaintext silently (default)require: TLS required, no certificate validationverify-ca: TLS required, server certificate verified againstserver_tls_ca_fileverify-full: TLS required, certificate and hostname verified
The prefer default means PgBouncer uses TLS opportunistically on the backend leg but does not validate PostgreSQL’s certificate. This provides encrypted transport but no protection against MITM on the backend leg. If you need authenticated backend connections, set server_tls_sslmode to verify-ca or verify-full and configure server_tls_ca_file.
Auditing encryption: the tls column
The tls column in SHOW CLIENTS and SHOW SERVERS is the ground truth for whether connections are actually encrypted. It shows the TLS version and cipher for each connection, or is empty for plaintext.
# Check client-side TLS status across all connections
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW CLIENTS;"
# Check server-side TLS status across all connections
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW SERVERS;"
The tls column format includes the TLS version, cipher suite, and key length, for example TLSv1.2/ECDHE-RSA-AES256-GCM-SHA384/256bits. An empty value means the connection is plaintext.
Key audit questions:
- Are all client connections showing a TLS version? Empty values indicate plaintext client connections. This may be expected if
client_tls_sslmodeisdisable. - Are all server connections showing a TLS version? If
server_tls_sslmodeispreferand PostgreSQL does not support TLS, connections silently fall back to plaintext. Thetlscolumn will be empty and no error is logged. - Is the TLS version consistent? Mixed TLS versions may indicate client library differences or a misconfigured
client_tls_protocols/server_tls_protocols. - Are TLS versions downgraded unexpectedly? A shift from TLSv1.3 to TLSv1.2 across many connections may indicate a certificate renewal changed key types or an intermediary is interfering.
The cost of TLS: CPU and memory
TLS is not free in PgBouncer. It affects two resources already constrained by the single-threaded event loop design.
Memory
A plaintext connection costs approximately 2KB of memory (socket buffers plus connection metadata). A TLS connection costs 20-50KB due to OpenSSL session state. With 5,000 TLS connections, the difference between plaintext and TLS is roughly 90-240MB of additional resident memory.
This means max_client_conn capacity calculations that assume 2KB per connection will significantly underestimate memory when TLS is enabled. Recalculate using the higher per-connection cost. PgBouncer pre-allocates client structures at startup, so RSS jumps immediately after enabling TLS with a high max_client_conn.
If your per-TLS-connection memory is far above 50KB, suspect the OpenSSL build. Older or misconfigured library builds have shown 600KB overhead per connection.
CPU
TLS handshakes are the single biggest CPU consumer in PgBouncer. Each handshake involves asymmetric cryptographic operations (key exchange, certificate verification) that are orders of magnitude more expensive than the symmetric encryption of established sessions.
Under high connection churn (many connects and disconnects per second), the event loop spends most of its CPU budget on TLS handshakes rather than query proxying. This manifests as:
- PgBouncer process CPU approaching 100% of a single core
- Admin console responsiveness degrading (the meta-health signal for event loop health)
cl_waitingrising across all pools simultaneously (event loop stall pattern, not pool-specific saturation)
If TLS is driving CPU saturation, the standard mitigation is to terminate TLS at a load balancer or proxy in front of PgBouncer (HAProxy, Envoy, a cloud TLS terminator), letting PgBouncer handle only plaintext connections. This moves the handshake CPU cost off the single-threaded event loop.
TLS and the event loop
A slow TLS handshake with an unresponsive client can block the event loop. Because PgBouncer is single-threaded, one stuck handshake freezes all pools, all clients, and the admin console simultaneously. TLS handshakes are one of the common triggers for this failure pattern. For more on the failure mode, see PgBouncer event loop stall.
Certificate expiry: the silent outage
PgBouncer does not expose certificate expiry as a metric. There is no SHOW CERTIFICATES command, no countdown to expiry, and no warning when a certificate is about to expire. When a certificate expires:
- Client leg: New client connections fail immediately with TLS errors. Existing connections may continue until they disconnect.
- Server leg: New server connections to PostgreSQL fail. The pool drains as existing connections expire and cannot be replaced.
Both scenarios produce total login failure with no advance warning from PgBouncer itself. The failure shows up in logs as TLS errors, but by then the outage is already in progress.
Checking certificate expiry
Use openssl to inspect certificate end dates directly:
# Check a certificate's expiry date
openssl x509 -enddate -noout -in /etc/pgbouncer/client.crt
# Output: notAfter=Sep 15 23:59:59 2026 GMT
# Check if a certificate expires within 30 days (exit code 1 = expiring soon)
openssl x509 -checkend 2592000 -noout -in /etc/pgbouncer/client.crt
The -checkend flag exits with code 0 if the certificate is valid for the specified number of seconds, and non-zero if it will expire sooner. This makes it suitable for scripted monitoring and alerting pipelines.
A practical expiry-check loop covering both legs:
# Certificate expiry check for client and server certificates plus CA
for cert in /etc/pgbouncer/client.crt /etc/pgbouncer/server.crt /etc/pgbouncer/ca.crt; do
if [ -f "$cert" ]; then
if ! openssl x509 -checkend 2592000 -noout -in "$cert" 2>/dev/null; then
echo "WARNING: $cert expires within 30 days"
openssl x509 -enddate -noout -in "$cert"
fi
fi
done
Also check the CA certificate file referenced by server_tls_ca_file or any client-side CA configuration. An expired CA causes the same total failure as an expired end-entity certificate. When using verify-ca or verify-full, both the end-entity certificate and the CA chain must be valid.
Set alerting thresholds at 30 and 7 days before expiry. The 30-day warning gives time for certificate procurement and deployment. The 7-day warning is the last-call alert.
Common pitfalls
sslmode=require and client certificates. When client_tls_sslmode is set to require (not verify-ca or verify-full), clients that present certificates may encounter unexpected behavior depending on the PgBouncer version. If clients present certificates by default (some PostgreSQL libraries do), test the behavior or use verify-ca / verify-full instead.
-R (online restart) does not work with TLS. The -R flag performs an online restart by passing socket ownership to the new process. TLS connections cannot be transferred this way and are dropped. Plan for connection loss during any restart of a TLS-enabled PgBouncer instance.
RELOAD behavior changed in 1.24.0. Before PgBouncer 1.24.0, RELOAD recycled all TLS connections even if the TLS configuration was unchanged, causing temporary performance degradation. In 1.24.0 and later, TLS connections are preserved when TLS config is unchanged. On versions before 1.24.0, expect a brief connection churn after any RELOAD.
Changing TLS settings triggers RECONNECT. Any change to TLS parameters triggers an automatic reconnection of all server connections. Existing client connections using TLS are not closed, but new connections use the new configuration. Plan TLS changes during low-traffic windows.
server_tls_sslmode=prefer silently falls back. The prefer default means PostgreSQL connections may run in plaintext if the backend does not support TLS. No error is logged. If you require encrypted backend connections, set server_tls_sslmode to require or stronger and audit via SHOW SERVERS.
“tlsv1 alert unknown ca” on the server leg. This error appears in PgBouncer logs when server_tls_ca_file is misconfigured, missing, or the PostgreSQL server certificate is not signed by the configured CA. Verify the CA file contains the correct root certificate and that the PostgreSQL server is configured to present a certificate signed by that CA.
verify-full with multi-host connections. PgBouncer 1.25.0 reportedly fixed a bug (issue #1303) where multi-host connections failed when using server_tls_sslmode=verify-full. If you are on an older version and using verify-full with multiple backend hosts, upgrade or use verify-ca as a workaround.
Signals to monitor
| Signal | Why it matters | Warning sign |
|---|---|---|
tls column in SHOW CLIENTS | Confirms client-side encryption is active | Empty values where TLS is expected |
tls column in SHOW SERVERS | Confirms backend encryption is active | Empty values indicate plaintext fallback from prefer |
| PgBouncer process CPU | TLS handshakes consume event loop CPU | Sustained above 70% of one core |
| PgBouncer process RSS | TLS connections cost 20-50KB each | RSS exceeding max_client_conn x 50KB + overhead |
| Admin console latency | Proxy for event loop health | Above 200ms response time suggests TLS-induced stall |
| Certificate expiry (external) | Expired certs cause total login failure | Less than 30 days to expiry |
cl_waiting across all pools | Event loop stall from TLS affects all pools | Simultaneous rise across unrelated pools |
How Netdata helps
Netdata’s PgBouncer collector scrapes SHOW CLIENTS, SHOW SERVERS, and related admin commands at per-second resolution. For TLS-specific operations:
- CPU correlation. Per-process CPU metrics let you correlate PgBouncer CPU spikes with connection churn. If CPU rises when new connections spike, TLS handshakes are the likely consumer.
- Admin console latency. Netdata tracks the latency of its own admin queries to PgBouncer. Increasing latency is an early indicator of event loop strain, which TLS handshakes can trigger.
- Connection count trends. Per-second connection metrics help distinguish gradual growth (capacity planning) from sudden bursts (retry storms that amplify TLS handshake load).
- Memory tracking. RSS trending against connection count reveals whether TLS per-connection overhead matches expectations (20-50KB) or is leaking.
- Anomaly detection. Anomaly flags on CPU, connection rates, and admin latency surface TLS-induced event loop stalls that might otherwise look like generic slowdowns.
Certificate expiry monitoring requires an external check (such as openssl x509 -checkend) since PgBouncer does not expose it. Wire this into your alerting pipeline alongside Netdata’s PgBouncer metrics to cover the full TLS operational surface.
Related guides
- PgBouncer advisory locks in transaction mode: orphaned locks and mysterious contention
- PgBouncer auth failed / password authentication failed: client login rejected
- PgBouncer auth_query failures: the authentication dependency loop on PostgreSQL
- PgBouncer avg_query_time high: reading backend slowdown through the pooler
- PgBouncer avg_wait_time high: the latency the pool itself is injecting
- PgBouncer backend unreachable: PostgreSQL down and the pool draining
- PgBouncer capacity planning: runway for pools, clients, and PostgreSQL slots
- PgBouncer client connection leak: idle clients that never disconnect
- PgBouncer database paused or disabled: maintenance state that looks like an outage
- PgBouncer event loop stall: the single thread that freezes every pool at once
- PgBouncer high CPU: single-core saturation, TLS, and connection churn
- How PgBouncer actually works in production: a mental model for operators