---
title: "Use PgBouncer when many app servers share · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/databases-and-storage/pgbouncer
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Use PgBouncer when many app servers share PostgreSQL

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Databases and storage](https://agentwranglers.se/playbook/stack/databases-and-storage.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: STK-93
- Level: Recommended
- Chapter: [Databases and storage](https://agentwranglers.se/playbook/stack/databases-and-storage)
- Rule: Put PgBouncer in transaction mode between your app servers and PostgreSQL when their pools together could pass the database's connection limit.
- Cost: Open source. ISC licence, free to run on your own servers.
- How: 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](https://agentwranglers.se/playbook/data/operations/connection-pooling) 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](https://agentwranglers.se/playbook/data/operations/database-scram-auth) says. Choose something else when one app server with its driver's own pool stays under the limit, and add nothing.
- 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`.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### INI example

```ini
; 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

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

## Sources

- [PostgreSQL connection settings](https://www.postgresql.org/docs/current/runtime-config-connection.html)

## Related rules

- [Pool database connections](https://agentwranglers.se/playbook/data/operations/connection-pooling) in Data
- [Log in to the database with SCRAM instead of MD5](https://agentwranglers.se/playbook/data/operations/database-scram-auth) in Data
- [Fit the connection budget to the autoscaling maximum](https://agentwranglers.se/playbook/scaling/growing-the-database/connection-budget) in Scaling

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Use SQLite for a small or embedded database](https://agentwranglers.se/playbook/stack/databases-and-storage/sqlite)
- Next: [Use Redis 8 or Valkey for caches and queues](https://agentwranglers.se/playbook/stack/databases-and-storage/redis-or-valkey)
- [Databases and storage](https://agentwranglers.se/playbook/stack/databases-and-storage)