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

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.

Two failure modes make this worth monitoring:

1. OOM kills terminate PgBouncer silently. If RSS creeps toward the system memory limit, the OOM killer removes the process and all database traffic through it stops. If PgBouncer vanishes without a crash log, check dmesg for OOM evidence first.
2. Abnormal RSS growth under stable connection count signals a bug, not a capacity issue. Knowing the expected number lets you distinguish “working as designed” from “something is leaking.”

How the slab allocator and pkt_buf interact

Pre-allocated structures at startup

At startup, PgBouncer creates slab allocator caches for its core object types:

The client_cache is sized based on max_client_conn. PgBouncer pre-allocates these at startup, which is why RSS stabilizes quickly. The server_cache is sized based on the total server connection budget across all pools. This pre-allocation is why SHOW LISTS reports free_clients and free_servers as fixed numbers that do not grow at runtime.

pkt_buf and lazy buffer allocation

The pkt_buf setting (default 4096 bytes) controls the packet buffer size for reading and writing PostgreSQL protocol data. Each connection has a pair of socket buffers (sbuf) for this purpose. When a result set exceeds pkt_buf, PgBouncer streams it in chunks, pausing the server read when the client write buffer fills.

Packet buffers are allocated lazily from the iobuf_cache slab and reused across connections. They are not permanently bound to a single connection. An idle connection may not have an active iobuf allocation; an active connection streaming a result set will. This lazy allocation is why the “2KB per idle connection” figure holds even though active connections with full buffers cost more.

The expected RSS formula:

(max_client_conn + total_server_connections) x pkt_buf x 2 + base_overhead

Base overhead is approximately 5-10MB. The x 2 factor accounts for the read and write buffers per connection. Total server connections is the sum of all pools’ pool_size plus reserve_pool_size across all databases.

The “2KB per idle connection” figure covers connection metadata and socket bookkeeping only. Active connections that stream large result sets allocate additional buffer space; the config documentation notes that prepared statement buffers can grow to 2–4× pkt_buf per connection. The RSS formula below is most accurate for idle-dominant workloads.

TLS memory overhead

When PgBouncer terminates TLS, each encrypted connection carries OpenSSL session state. Expected overhead is 20-50KB per TLS connection instead of the ~2KB base cost for plaintext. This applies to both client-side TLS (application to PgBouncer) and server-side TLS (PgBouncer to PostgreSQL).

PgBouncer 1.7.1 added SSL_MODE_RELEASE_BUFFERS to reduce memory usage of inactive TLS connections. This helps when many connections are idle, but overhead remains significant at scale. A deployment with 5,000 TLS client connections should expect roughly 100-250MB of RSS just for TLS session state, before buffer overhead.

Historical note: PgBouncer 1.7.1 documented that Debian/wheezy’s libssl build had approximately 600KB overhead per TLS connection instead of the expected 20-30KB. This was a distro-specific libssl issue, not a PgBouncer bug. Modern OpenSSL builds should not exhibit this, but TLS memory cost depends on the linked libssl build, not just PgBouncer’s configuration.

Calculating and validating expected RSS

Working through the formula

Deployment with max_client_conn = 5000, total server connections of 200 (sum of all pool sizes plus reserve), and pkt_buf = 4096 (default):

• Buffer cost: (5000 + 200) x 4096 x 2 = approximately 42MB
• Base overhead: approximately 5-10MB
• Expected RSS: approximately 47-52MB

With TLS enabled on client connections only (5000 TLS client connections):

• TLS session state: 5000 x 20-50KB = approximately 100-250MB
• Buffer cost: approximately 42MB
• Base overhead: approximately 5-10MB
• Expected RSS: approximately 147-302MB

The TLS overhead dominates. The first question when RSS is higher than expected should always be: is TLS enabled?

When to investigate

Investigate if RSS is 3x or more above the expected calculation. The following decision tree covers the most common causes:

flowchart TD
    A["RSS is 3x+ expected"] --> B{"Connection count growing?"}
    B -->|Yes| C["Expected: RSS scales
with connection count"]
    B -->|No| D{"TLS enabled?"}
    D -->|Yes| E["TLS adds 20-50KB
per connection vs 2KB base"]
    D -->|No| F{"pkt_buf > 4096?"}
    F -->|Yes| G["pkt_buf inflates
per-connection buffers"]
    F -->|No| H["Run SHOW MEM.
Check version-specific leak"]
    H --> I["memtotal growing
over weeks with stable
connection count?"]
    I -->|Yes| J["Likely leak.
Check changelog for fixes"]
    I -->|No| K["Investigate libc heap
and OpenSSL state
outside slab allocator"]

Reading SHOW MEM

SHOW MEM exposes the internal slab allocator state. Each row shows: Name, Size (object size in bytes), Used (currently allocated objects), Free (objects in the free list), MemTotal (total memory for this slab).

# Inspect slab allocator state
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW MEM;"

Diagnostic patterns:

• Used growing without corresponding traffic increase: objects are being allocated but not returned. Could indicate a leak in a specific code path.
• MemTotal growing unboundedly over weeks with stable connection count: the signature of a memory leak. Under stable load, MemTotal should plateau.
• Free is high: not a problem. The slab retains freed objects for reuse. This memory is not returned to the OS, which is why RSS may not decrease when connections close.

Two caveats:

1. Before PgBouncer 1.20.0, SHOW MEM had a bug where peer_cache was incorrectly labeled as db_cache. If you are on an older version and the db_cache row seems unexpectedly large, it may actually represent peer connection cache.
2. SHOW MEM shows the slab allocator only, not the total process RSS. RSS includes slab allocations plus the libc heap, OpenSSL session state, and the binary itself.

# Check actual process RSS
grep VmRSS /proc/$(pgrep pgbouncer)/status

Tradeoffs: pkt_buf sizing and TLS decisions

pkt_buf too large

The default pkt_buf of 4096 was increased from 2048 in PgBouncer 1.7 because the larger buffer improved TLS throughput. There is rarely a reason to raise it further.

Setting pkt_buf to 64KB or higher increases per-connection buffer cost linearly. The formula (max_client_conn + server_connections) x pkt_buf x 2 makes this explicit: doubling pkt_buf doubles buffer cost. Large pkt_buf may reduce syscall count for large result sets, but the memory tradeoff is rarely worth it at scale.

TLS termination placement

If TLS is required between the application and PgBouncer but not between PgBouncer and PostgreSQL (common when they share a host or private network), disable server-side TLS. This eliminates the 20-50KB per server connection overhead.

If TLS is required at high client connection counts, consider terminating TLS at a load balancer or sidecar proxy in front of PgBouncer. This moves the per-connection OpenSSL overhead out of the PgBouncer process, reducing both memory and CPU pressure on the single-threaded event loop.

Version-specific leak fixes

Several PgBouncer releases have shipped memory leak fixes. If you are on an older version and experiencing unbounded growth, check the changelog before deep investigation:

The COPY FROM STDIN leak (fixed in 1.22.1) is relevant for workloads that use bulk loading through PgBouncer. If your application uses COPY ... FROM STDIN and you are on a version before 1.22.1, that is a likely source of unbounded growth.

Signals to watch in production

How Netdata helps

• Per-second RSS tracking for the PgBouncer process reveals slow growth trends invisible in manual point-in-time checks. A linear creep over days is the pattern that precedes an OOM kill; per-second resolution makes it visible early.
• Connection count correlation distinguishes expected growth (RSS rising because more clients connected) from abnormal growth (RSS rising while connection count is flat). Correlating RSS with used_clients from SHOW LISTS makes this immediate.
• Anomaly detection on RSS flags sustained growth that deviates from the established baseline, even when the absolute value is below any static threshold.
• Host memory pressure metrics (available memory, swap usage) provide context for OOM risk. If RSS is growing and available memory is shrinking, the OOM kill is predictable.
• Process liveness alerts detect the silent disappearance the OOM killer causes. Correlating a process-down event with dmesg OOM evidence confirms the cause quickly.

Related guides

• PgBouncer advisory locks in transaction mode: orphaned locks and mysterious contention
• 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
• PgBouncer idle in transaction: the silent pool killer in transaction mode
• PgBouncer LISTEN/NOTIFY not working: why pub/sub needs session pooling