Modos de PgBouncer
El pool_mode de PgBouncer decide cuándo una conexión de servidor regresa al pool. La agrupación por transacción maximiza la densidad; la agrupación por sesión maximiza la compatibilidad en PostgreSQL 18.4.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
; pgbouncer.ini
[databases]
appdb = host=127.0.0.1 port=5432 dbname=appdb
[pgbouncer]
pool_mode = transaction
default_pool_size = 50
max_client_conn = 2000Cuándo usar esto: Al elegir el modo de pool para un nuevo servicio o al depurar errores de prepared statement already exists.
Ejemplo de Trabajo
-- Modo de sesión: SET y tablas temporales persisten durante la vida útil de la conexión del cliente
SET search_path = app, public;
CREATE TEMP TABLE staging (id int);
-- OK en la agrupación por sesión hasta la desconexión
-- Modo de transacción: el servidor de conexión puede cambiar después de COMMIT
BEGIN;
SET LOCAL statement_timeout = '5s';
SELECT count(*) FROM orders;
COMMIT;
-- SET LOCAL es seguro; SET a nivel de sesión sin LOCAL es arriesgadoVerifica el modo con el administrador de PgBouncer: SHOW CONFIG; -> pool_mode.
Lo que esto demuestra:
SET LOCALcon ámbito de transacción frente aSETde sesión- Las tablas temporales requieren modo de sesión (o evitarlas)
- Por qué las suposiciones predeterminadas de los ORM importan
Análisis Profundo
Cómo Funciona
- session - Backend de servidor anclado al cliente hasta la desconexión. Máxima compatibilidad, menor multiplexación.
- transaction - Backend asignado por transacción; devuelto en COMMIT/ROLLBACK. Predeterminado para OLTP web.
- statement - Backend por sentencia (raro); rompe transacciones de múltiples sentencias y la mayoría de los ORM.
Comparación de Modos
| Modo | Multiplexación | Tablas temporales | Sentencias preparadas |
|---|---|---|---|
| session | Baja | Sí | Sí |
| transaction | Alta | No | Complicado |
| statement | La más alta | No | Roto |
Notas SQL
-- Patrón seguro en agrupación por transacción
BEGIN;
SET LOCAL lock_timeout = '2s';
SELECT * FROM orders WHERE id = 1 FOR UPDATE;
COMMIT;Trampas
- LISTEN/NOTIFY en modo de transacción - Poco fiable entre cambios de backend. Solución: Pool de sesión o conexión de escucha dedicada.
- Bloqueos de asesoría entre solicitudes - Deben usar modo de sesión. Solución: Pool separado para workers de trabajos que necesitan bloqueos.
- Migraciones de esquema a través del pooler - DDL puede necesitar persistencia de sesión. Solución: Conexión de administración directa que omite el pooler.
- Modo de sentencia con Hibernate - Transacciones rotas. Solución: Nunca usar modo de sentencia para ORM.
DEALLOCATE ALLolvidado al retirar - Algunos drivers necesitanserver_reset_query. Solución: Configurarserver_reset_query = DISCARD ALLcuando sea apropiado.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Agrupación por sesión | ETL intensivo de tablas temporales en la aplicación | Miles de clientes inactivos |
| RDS Proxy | Multiplexación administrada por AWS | K8s on-premise |
| Conexión directa (sin pool) | Solo desarrollo local | Flota de producción |
Preguntas Frecuentes
Modo predeterminado para APIs web?
transaction con SET LOCAL y sin tablas temporales.
El modo de transacción rompe SET de RLS?
Usar SET LOCAL dentro de la transacción o inicialización de conexión a través de parámetros de inicio.
server_reset_query?
DISCARD ALL limpia el estado de la sesión entre transacciones en modo de transacción.
sentencias preparadas?
Ver página dedicada; a menudo deshabilitar en ORM para modo de transacción.
múltiples bases de datos?
Sección de base de datos de PgBouncer por destino; pools aislados por db/usuario.
TLS a Postgres?
El pooler se conecta a TLS upstream; los clientes TLS al pooler.
consulta de autenticación?
userlist.txt o auth_query para SCRAM con PostgreSQL 18.
agrupación por transacción y COPY?
COPY en transacción generalmente OK dentro de un único bloque de transacción.
failover?
Actualización de configuración del pooler o DNS al nuevo primario; las aplicaciones se reconectan al pooler.
Siguiente?
Trampas de sentencias preparadas en modo de transacción.
Relacionado
- Sentencias Preparadas y Agrupación - Correcciones de ORM
- Conceptos Básicos de Agrupación - Por qué agrupar
- Rol y Tiempo de Espera por Pool - Separación de pools
- Mejores Prácticas de Agrupación - Operaciones
Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.