PgBouncer, Pgpool-II y otros: gestores de conexiones para PostgreSQL

Pool de conexiones para PostgreSQL — es un programa entre la aplicación y la base de datos que mantiene un pequeño número de conexiones reales al servidor y las reparte entre los clientes por turno. Los más conocidos son PgBouncer y Pgpool-II; entre los nuevos están Odyssey y PgCat.

¿Para qué un pooler en PostgreSQL?

Cada conexión a PostgreSQL la atiende un proceso servidor separado. Cuando la aplicación abre cientos de conexiones — muchos workers, funciones sin servidor, varios servicios — el servidor gasta memoria y tiempo en procesos, y no en las consultas. El pool acepta miles de conexiones de clientes y las pasa a través de unas pocas decenas de conexiones servidoras. Las configuraciones básicas de PostgreSQL y el lugar del pool en el panorama general están descritos en la tercera parte del ciclo; aquí están los detalles.

PgBouncer

PgBouncer es un pooler ligero y monohilo, la elección estándar para la mayoría de proyectos. La rama actual es 1.25 (la versión 1.25.2 se publicó en mayo de 2026). No conoce la estructura de la base de datos y solo gestiona conexiones.

Modos de pool

• session (por defecto) — la conexión servidor se asigna al cliente hasta que éste se desconecta. Compatible con todo, pero apenas ahorra recursos.
• transaction — la conexión se devuelve al pool después de terminar la transacción. Modo principal para ahorro: cientos de clientes atendidos por decenas de conexiones.
• statement — la conexión se devuelve después de cada consulta; las transacciones que incluyan varias consultas están prohibidas.

Qué deja de funcionar en el modo transaction

Entre transacciones el cliente puede caer en otra conexión servidor, por lo que no funciona nada que guarde estado de sesión. Según la documentación, PgBouncer es incompatible en modo transaction con:

• SET y RESET a nivel de sesión;
• LISTEN;
• cursores WITH HOLD;
• comandos SQL PREPARE y DEALLOCATE;
• tablas temporales con PRESERVE o DELETE ROWS;
• LOAD;
• locks recomendacionales (advisory locks) a nivel de sesión.

Las sentencias preparadas a nivel de protocolo — las usan drivers como JDBC y asyncpg — PgBouncer las soporta en versiones nuevas incluso en modo transaction: él mismo las prepara en las conexiones servidor. Esto lo controla el parámetro max_prepared_statements (en la documentación actual el valor por defecto es 200; el valor 0 desactiva el soporte).

Configuración mínima

[databases]
app = host=127.0.0.1 port=5432 dbname=app

[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

La aplicación se conecta al puerto 6432 en lugar de 5432. default_pool_size — cuántas conexiones servidor se mantienen por par «usuario — base» (por defecto 20), max_client_conn — cuántos clientes pueden conectarse al propio PgBouncer (por defecto 100).

Pgpool-II

Pgpool-II no es solo un pooler, sino un eslabón de unión para el clúster: balanceo de lecturas entre réplicas, conmutación automática ante la caída del servidor principal, proceso vigilante (watchdog) para la tolerancia a fallos del propio Pgpool. La rama actual es 4.7 (versión 4.7.2, junio de 2026), se soportan las ramas de la 4.3 a la 4.7.

El precio por las funcionalidades es la complejidad: Pgpool-II analiza SQL para decidir a dónde enviar la consulta, tiene más ajustes y más puntos de fallo. Su pool funciona con el modelo «proceso por cliente», por lo que, para ahorrar conexiones, suele ser más sencillo y eficaz en combinación con un PgBouncer que gestione el pooling.

PgBouncer o Pgpool-II

Si solo necesitas un pool — PgBouncer. Si necesitas distribuir lecturas entre réplicas y conmutar automáticamente ante fallos y estás dispuesto a mantener una configuración compleja — Pgpool-II. Para un clúster tolerante a fallos hoy en día a menudo se usa Patroni, y delante de él — PgBouncer y HAProxy (más sobre HAProxy en el ciclo sobre proxies).

Odyssey

Odyssey es un pooler multihilo, creado por Yandex, licencia BSD-3-Clause; el proyecto está en desarrollo activo (versión 1.5.2 — septiembre de 2026). Está pensado para cargas altas, donde el PgBouncer monohilo choca con un solo núcleo de CPU. Para la mayoría de proyectos es excesivo, pero con decenas de miles de conexiones merece la pena compararlo con varios instancias de PgBouncer.

PgCat

PgCat es un pooler en Rust con sharding y balanceo, licencia MIT. El proyecto ha ralentizado notablemente: la última versión 0.2.5 se publicó en noviembre de 2024, los últimos cambios en el repositorio son de febrero de 2025. Para nuevas instalaciones en producción conviene elegirlo con cautela.

Errores típicos

• Modo transaction sin verificar la aplicación. SET search_path, LISTEN o locks de sesión empiezan a comportarse de forma impredecible.
• El pool como único punto de fallo. Despliega instancias junto a cada servidor de aplicación o en dos réplicas.
• La suma de pools supera max_connections del servidor. Calcula default_pool_size × número de pares «usuario — base» más reserva para el administrador.
• Dos pools en fila. Un pool en la aplicación con tamaño grande encima de PgBouncer no ahorra conexiones y solo complica el diagnóstico.

Enlaces útiles

• PgBouncer: настройки
• PgBouncer: совместимость режимов
• Pgpool-II
• Odyssey на GitHub