PostgreSQL sin conexiones disponibles: diagnóstico y connection pooling con PgBouncer

Publicado el 2026-11-14 por frfrand

Identifica agotamiento de conexiones en PostgreSQL, investiga pg_stat_activity y decide cuándo configurar pooling y PgBouncer.

Tu aplicación empieza a responder con errores de conexión a PostgreSQL justo cuando crecen las visitas. Aumentar max_connections parece una solución inmediata, pero puede agravar la presión de memoria. Antes de hacerlo identifica quién abre conexiones, cuánto tiempo duran y si realmente trabajan.

1. Verifica el problema

Consulta el límite y la actividad con una cuenta autorizada:

SHOW max_connections;
SHOW superuser_reserved_connections;
SELECT state, count(*) AS conexiones
FROM pg_stat_activity
GROUP BY state
ORDER BY conexiones DESC;

Revisa errores de la aplicación, número de instancias, procesos, conexiones por worker y el histórico de picos. No todas las conexiones visibles son consultas simultáneamente activas: puede haber sesiones idle que ocupan recursos sin hacer trabajo.

2. Encuentra conexiones bloqueadas o abandonadas

Una consulta básica de observación:

SELECT pid, usename, application_name, state,
       now() - state_change AS tiempo_en_estado,
       wait_event_type
FROM pg_stat_activity
WHERE backend_type = 'client backend'
ORDER BY tiempo_en_estado DESC
LIMIT 30;

Evita terminar procesos sin investigar: podrías interrumpir transacciones legítimas. Revisa idle in transaction porque mantiene transacciones abiertas que pueden afectar a bloqueos y mantenimiento.

3. Calcula conexiones máximas de tu arquitectura

Una regla orientativa es:

conexiones potenciales = instancias de API × pool por instancia
                       + workers × pool de cada worker
                       + tareas administrativas

No confundas el tamaño máximo del pool con su uso constante. Si escalas de dos a diez instancias y cada una abre 20 conexiones, el techo potencial salta de 40 a 200 antes de contar otros servicios.

4. Qué hace PgBouncer

PgBouncer recibe conexiones de clientes y reutiliza conexiones de servidor. En modo transaction pooling presta una conexión de PostgreSQL por transacción, lo que permite muchos clientes lógicos con menos backends físicos. Sin embargo, funciones que dependen de estado de sesión, tablas temporales, prepared statements u otros comportamientos pueden requerir configuración o cambios. Consulta la compatibilidad de tu driver y versión.

No actives transaction pooling a ciegas: prueba migraciones, transacciones explícitas, sesiones y tareas de larga duración. Para algunos casos conviene session pooling o un pool dentro de la propia aplicación.

5. No escondas consultas lentas detrás de un pool

Si todas las conexiones ejecutan consultas costosas, PgBouncer solo encola más trabajo. Revisa tiempo de consultas, índices, bloqueos y p95; agrega límites de espera y métricas de saturación. Un pool debe controlar concurrencia y estabilidad, no reemplazar optimización de SQL.

6. Plan seguro

1. Mide conexiones y estados en horas pico. 2. Corrige fugas, transacciones abiertas y pools mal dimensionados. 3. Prueba PgBouncer con tráfico representativo. 4. Despliega gradualmente con alertas y posibilidad de reversión.

Complementa con EXPLAIN ANALYZE para PostgreSQL, túnel SSH para PostgreSQL y PostgreSQL en ArduMaker.

Preguntas frecuentes

### ¿Es suficiente aumentar max_connections? No si la causa es una fuga, escalado sin control o consultas bloqueadas.

¿PgBouncer hace las consultas más rápidas?

No directamente: reduce la presión de conexiones y puede mejorar estabilidad.

¿Necesito pooling si tengo pocos usuarios?

Depende del número de procesos, tamaño del pool y patrón de uso.

Referencias: pg_stat_activity, PgBouncer.