PostgreSQL: connection refused

Error del lado del cliente (sin SQLSTATE del servidor) · Actualizado 9 de julio de 2026

psql: error: connection to server at "db.example.com" (10.0.0.12), port 5432 failed: Connection refused
        Is the server running on that host and accepting TCP/IP connections?

Este error no viene de PostgreSQL — nunca vio la conexión. "Connection refused" es el sistema operativo del host de destino diciendo que nada está escuchando en esa dirección y puerto (o un firewall rechazó activamente el paquete). Esa distinción reduce inmediatamente la búsqueda.

Qué significa este error

Tres modos de fallo en el momento de conectar parecen similares pero significan cosas distintas:

Síntoma	Significado
`Connection refused`	El TCP llegó al host, nada escuchando en ese puerto (o firewall REJECT). PostgreSQL no está implicado.
Connection timeout	Paquetes descartados silenciosamente — típicamente un firewall o security group, o el host incorrecto.
`no pg_hba.conf entry for host ...`	Sí llegaste a PostgreSQL; ahora es un problema de configuración de autenticación, otra página del manual.

Así que "Connection refused" significa: lugar incorrecto, puerto incorrecto, o ningún servidor ejecutándose ahí.

Causas comunes

PostgreSQL no está ejecutándose — se cayó, falló al arrancar tras un cambio de configuración, o el host se reinició y el servicio no está habilitado.
Solo escucha en localhost. El valor por defecto listen_addresses = 'localhost' no acepta ninguna conexión TCP remota.
Puerto incorrecto. El servidor puede estar en un puerto no predeterminado — en Debian/Ubuntu, un segundo clúster en el mismo host normalmente recibe el 5433.
Red de Docker: el puerto del contenedor no está publicado (-p 5432:5432), o estás usando localhost desde dentro de otro contenedor en vez del nombre del servicio.
Un firewall configurado para rechazar (en vez de descartar) en ese puerto.

Cómo diagnosticarlo

Desde el cliente:

pg_isready -h db.example.com -p 5432

En el host del servidor:

# ¿El servicio está corriendo?
systemctl status postgresql

# ¿Algo escucha, y en qué dirección/puerto?
ss -lntp | grep -E '5432|postgres'

Si el servicio está caído, la razón del arranque fallido está en los logs (journalctl -u postgresql o el directorio de log de PostgreSQL) — un error tipográfico en postgresql.conf tras una edición es un clásico. Si está corriendo pero enlazado solo a 127.0.0.1, es listen_addresses.

Cómo solucionarlo

Servicio caído → lee el error de arranque en el log, arréglalo, systemctl start postgresql (y enable).
Se necesita acceso remoto → configura listen_addresses en postgresql.conf (requiere un reinicio), añade una regla pg_hba.conf que coincida, y abre el firewall — solo a las redes de cliente específicas. Exponer el 5432 a internet invita a tráfico de ataque constante; restringe por CIDR y exige autenticación fuerte (scram-sha-256) y TLS.
Puerto incorrecto → comprueba port en postgresql.conf (o el listado de clústeres en sistemas de la familia Debian) y corrige la cadena de conexión.
Docker → publica el puerto, o desde otro contenedor conéctate al nombre del servicio de compose, no a localhost.