Skip to main content

​
Overview

PgBouncer sits between clients and PostgreSQL, multiplexing many client connections onto fewer backend connections. Every database created through DBHost gets a PgBouncer pool entry automatically.

​
Configuration files

FilePurpose
/etc/pgbouncer/pgbouncer.iniMain config: database entries, pool settings
/etc/pgbouncer/userlist.txtUser credentials (plaintext, format: "user" "pass")

​
How the agent manages PgBouncer

The agent performs four operations on PgBouncer:
  1. Add database — Appends a line to [databases] in pgbouncer.ini: 
    my_app = host=localhost port=5432 dbname=my_app
  2. Remove database — Removes the line from pgbouncer.ini
  3. Add/update user — Appends or replaces entry in userlist.txt: 
    "my_app" "password-here"
  4. Reload — Sends SIGHUP to the PgBouncer process (found via pgrep). This reloads config without dropping existing connections.

​
Pool settings

Default pool configuration in pgbouncer.ini: 
[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 200
default_pool_size = 20
admin_users = postgres
max_prepared_statements = 100
SettingValueWhy
pool_modetransactionBest for multi-tenant (releases backend conn after each transaction)
auth_typescram-sha-256Matches PostgreSQL’s default auth method
max_client_conn200Total client connections across all databases
default_pool_size20Backend connections per database
max_prepared_statements100Needed for ORMs like Drizzle that use prepared statements

​
Troubleshooting

Check PgBouncer status: 
sudo systemctl status pgbouncer
View PgBouncer logs: 
sudo journalctl -u pgbouncer -f
Manually reload config: 
sudo kill -SIGHUP $(pgrep -x pgbouncer)
Connect to PgBouncer admin console: 
psql -p 6432 -U pgbouncer pgbouncer
SHOW POOLS;
SHOW STATS;