pgbouncer Deployment

Tactical setup.

Pooling modes

The pool mode decides what kind of multiplexing pgbouncer does. Each mode trades application compatibility against connection efficiency.

• Session pooling. One connection per client session; lowest application impact, smallest multiplexing factor.
• Transaction pooling. One connection per transaction; higher multiplexing, clients cannot use prepared statements across transactions.
• Statement pooling. One connection per statement; highest multiplexing, most application restrictions.
• Per-app pool mode. Per-app the right mode; matches application reality, not vendor recommendation.

Configuration essentials

The config file is the contract between pgbouncer and Postgres. Get the math right or pgbouncer will exhaust the database while telling clients everything is fine.

• max_client_conn. Max client connections to pgbouncer; set higher than database max_connections.
• default_pool_size. Connections to database per (user, database) pair; match to actual database max_connections.
• pool_mode. Session, transaction, or statement; per-app the match.
• server_idle_timeout. Per-pool idle timeout; supports resource use by closing idle backend connections.
• reserve_pool_size. Per-pool burst reserve; matches reality of spikes without exceeding database limits.

Deployment patterns

How pgbouncer is deployed shapes its blast radius. Sidecar isolates failure to one pod; centralized concentrates it.

• Sidecar per app pod. Local connectivity; failure isolated; scales with the application.
• Centralized pgbouncer cluster. Shared across applications; lower total cost; failure shared.
• Hybrid. Centralized primary plus sidecar fallback; resilience and efficiency together.
• Per-deployment failure mode. Per-deployment explicit failure mode; the chosen pattern shapes the blast radius.

Monitoring

Without monitoring, pgbouncer is opaque until it fails. The admin console exposes the metrics that matter; ship them to your normal stack.

• SHOW POOLS. Per-pool statistics from the pgbouncer admin console; supports investigation.
• Active vs idle connections. Per-pool active and idle counts; connection wait time is the leading saturation signal.
• The math always balances. Database max_connections vs pgbouncer total connections; per-cluster reconciliation.
• Per-pool wait-time alerting. Per-pool wait-time threshold alert; catches saturation early before backend exhaustion.