Agent Wranglers

STK-93Recommended Open source

Use PgBouncer when many app servers share PostgreSQL

Put PgBouncer in transaction mode between your app servers and PostgreSQL when their pools together could pass the database's connection limit.

By Agent Wranglers. Updated .

How to do it

Every PostgreSQL connection is a separate server process, and max_connections defaults to 100. PgBouncer 1.0 came out in March 2007, and 1.26.1 shipped on 14 October 2026. Its edoburu/pgbouncer image alone had about 43 million pulls on Docker Hub in October 2026. PgBouncer starts in session mode, which saves few connections, so set pool_mode = transaction. Since 1.24 in January 2025, it keeps prepared statements working in that mode by default. Read Pool database connections for the session state that transaction mode breaks. Let clients log in with SCRAM, as Log in to the database with SCRAM instead of MD5 says. Choose something else when one app server with its driver's own pool stays under the limit, and add nothing.

Examples

INI example

; pgbouncer.ini
[databases]
shop = host=db.internal.example.com dbname=shop

[pgbouncer]
listen_port = 6432
pool_mode = transaction
default_pool_size = 20
auth_type = scram-sha-256

Shell example

psql "postgres://admin@pgbouncer.internal.example.com:6432/pgbouncer" -c "SHOW POOLS"

How to check

SHOW POOLS in the PgBouncer console shows cl_waiting at 0 during a load test. PostgreSQL's open connections stay below 80 percent of max_connections.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/stack/databases-and-storage/pgbouncer">Agent Wranglers software choices playbook</a>. In code you write, add a comment next to it with the same link.