PgBouncer
1.21+Summary
Lightweight PostgreSQL connection pooler that multiplexes many client connections onto a smaller pool of server connections, reducing PostgreSQL's connection overhead and enabling workloads with thousands of concurrent application connections to share a pool of 20–100 server connections.
Primary Use Case
Connection pool management for PostgreSQL: typically deployed between application servers and PostgreSQL to handle thousands of short-lived application connections (e.g., from serverless functions or many application server instances) without exhausting PostgreSQL's max_connections.
Consistency & Transactions
Scaling
Read scalability
PgBouncer itself is single-threaded but handles thousands of client connections efficiently via libevent-based async I/O. Multiple PgBouncer instances can be deployed in parallel for horizontal scaling of the proxy layer.
Write scalability
PgBouncer is transparent to write operations: writes pass through to PostgreSQL unchanged. No write scaling benefit; all writes still go to the PostgreSQL primary.
Failure Behavior
Known failure modes
- ·Transaction mode breaks SET configuration parameters and session-level state (search_path, timezone)
- ·Prepared statement caching must be disabled or handled via protocol-level workaround in transaction mode
- ·Server connection leaks: application code that does not close connections causes pool depletion
- ·Restarting PgBouncer terminates all active server connections, causing brief database reconnect storm
Degradation patterns
- ·Pool exhaustion when server pool size is too small relative to concurrent transaction demand
- ·Latency increase when all server connections are busy and clients queue for a connection
- ·OOM if client connection count far exceeds expectation (PgBouncer is single-threaded; extreme client counts add memory)
Recovery considerations
- ·PgBouncer state is volatile: restart loses all pool state; PostgreSQL server connections are re-established automatically
- ·PAUSE command drains the pool gracefully before maintenance; RESUME restores traffic
- ·Online restart: use RELOAD to reload config without dropping connections
Architecture Guidance
Common topology roles
Migration notes
- ·Verify the application does not use session-level features incompatible with transaction pooling mode: SET config parameters, advisory locks, LISTEN/NOTIFY, cursors spanning transactions, and prepared statements without disabling pgx's cache
- ·pg_pool and Odyssey are alternatives with multi-threaded architectures for very high connection counts (>100k clients)
- ·In Kubernetes, deploy PgBouncer as a sidecar or dedicated deployment; health check via the admin console SHOW STATS query
Advisor Guidance
When: scenario has many application servers connecting to PostgreSQL directly
Add PgBouncer in transaction mode between application and PostgreSQL to limit server connections to max_connections / 2 or less
When: scenario uses serverless functions or ephemeral workers connecting to PostgreSQL
Serverless workloads create a new connection per invocation; PgBouncer is mandatory to prevent connection exhaustion
Comparison Factors
operational complexity
Low: simple configuration, single binary, widely understood
latency
Adds <1ms overhead; reduces connection establishment cost significantly
durability
Not a storage system: no durability dimension
cost
Essentially free: open source, minimal resource requirements
Basis
PgBouncer is the standard PostgreSQL connection pooler with extensive production deployment history; its architecture, pooling modes, and limitations are thoroughly documented in official documentation and PostgreSQL community resources
Related Architecture Knowledge
Outbound: this entity affects
PgBouncer is the standard companion to PostgreSQL for connection pooling; deployed between the application and PostgreSQL to multiplex thousands of short-lived connections onto a bounded server connection pool.
Full relationship →PgBouncer multiplexes many client connections onto a small pool of PostgreSQL server connections, directly preventing connection exhaustion by bounding the number of server connections regardless of client count.
Full relationship →PgBouncer is the standard PostgreSQL connection pooler, implementing the connection pooling pattern by multiplexing many client connections onto a smaller pool of server connections.
Full relationship →