Elección de pool_mode en PgBouncer y dimensionamiento básico

Comando

; /etc/pgbouncer/pgbouncer.ini
[databases]
appdb = host=<primary_host> port=5432 dbname=appdb pool_mode=transaction
reportdb = host=<primary_host> port=5432 dbname=appdb pool_mode=session

[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 = 5000
default_pool_size = 20
reserve_pool_size = 5
max_prepared_statements = 200
query_wait_timeout = 120

Qué hace

El modo session vincula un cliente a una conexión de servidor durante toda la vida de su conexión; el modo transaction asigna una conexión de servidor solo mientras dura una transacción y atiende a miles de clientes con decenas de conexiones de PostgreSQL; el modo statement devuelve la conexión tras cada consulta y no permite transacciones de varias sentencias. pool_mode también se puede sobrescribir por base de datos.

Cuándo usarlo

Modo transaction para aplicaciones OLTP/microservicios que abren muchas conexiones de corta duración; modo session para trabajos que dependen del estado de la sesión (informes, migraciones, servicios que usan LISTEN).

Precaución

En el modo transaction el estado de la sesión no se conserva entre transacciones: SET (salvo SET LOCAL), los advisory locks a nivel de sesión, LISTEN, los cursores WITH HOLD, las tablas temporales entre transacciones y el PREPARE a nivel de SQL no son fiables. Los prepared statements a nivel de protocolo solo están soportados con PgBouncer 1.21+ y max_prepared_statements > 0 (200 por defecto desde 1.24, 0 antes). default_pool_size multiplicado por el número de pares (base de datos, usuario) no debe superar el max_connections de PostgreSQL (menos el margen de superuser_reserved_connections).