// Referencia de errores de PostgreSQL

PostgreSQL 08001: no se puede establecer la conexión

El cliente no pudo abrir conexión con el servidor: no hay nada a la escucha en ese host y puerto, o hay un firewall, un problema de DNS o se agotó el tiempo de espera.

SQLSTATE
08001
Nombre
sqlclient_unable_to_establish_sqlconnection
Categoría
Excepción de conexión
Mensaje de error
connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

Qué significa

08001 es un SQLSTATE del lado del cliente: controladores como PgJDBC y Npgsql lo reportan cuando no pueden establecer una conexión, y las herramientas basadas en libpq imprimen mensajes como el anterior. El servidor nunca vio un intento de inicio de sesión, por lo que el problema es la ruta de red o que el servidor no esté escuchando, no las credenciales.

El error del sistema operativo al final indica cuál: Connection refused significa que el host respondió pero no hay nada escuchando en ese puerto; timeout expired o Operation timed out suele significar que un firewall descartó los paquetes; could not translate host name es DNS.

Causas comunes

  • El servidor PostgreSQL no está en ejecución, o está escuchando en otro puerto.
  • listen_addresses es localhost (el predeterminado), así que el servidor solo acepta conexiones locales.
  • Un firewall, grupo de seguridad o mapeo de puertos de Docker bloquea el puerto 5432.
  • Nombre de host incorrecto o un nombre de host que no se resuelve desde el cliente.
  • Conectándose a localhost desde dentro de un contenedor, que apunta al propio contenedor.

Cómo solucionarlo

  1. En el servidor, verifica que PostgreSQL esté en ejecución y a qué direcciones y puerto escucha.

    SHOW listen_addresses;
    SHOW port;
  2. Permitir conexiones de red: establecer listen_addresses = '*' (o la dirección del servidor) en postgresql.conf y reinicia, luego añade una pg_hba.conf regla para los clientes.

  3. Prueba la ruta de red desde el cliente, por ejemplo pg_isready -h db.example.com -p 5432, y abre el puerto en el firewall o el grupo de seguridad.

  4. Desde un contenedor, conéctate al nombre del servicio del contenedor de la base de datos o a la dirección del host en lugar de localhost.

Errores relacionados

El código y el texto del mensaje son de documentación de PostgreSQL, Apéndice A: Códigos de error de PostgreSQL. Explora la lista completa de Lista de errores de PostgreSQL o buscar cada error de base de datos.

// menos errores, correcciones más rápidas

Trabajar con PostgreSQL en SQLly

Un cliente SQL nativo para macOS, Windows y Linux con IntelliSense que conoce el esquema, protecciones para las instrucciones de riesgo y mensajes de error claros, para PostgreSQL y las demás bases de datos que uses.