// Referência de erro do PostgreSQL

PostgreSQL 08001: não foi possível estabelecer conexão

O cliente não conseguiu abrir uma conexão com o servidor: nada escutando nesse host e porta, um firewall, DNS ou um timeout.

SQLSTATE
08001
Nome
sqlclient_unable_to_establish_sqlconnection
Categoria
Exceção de conexão
Mensagem de erro
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?

O que significa

08001 é um SQLSTATE do lado do cliente: drivers como PgJDBC e Npgsql relatam isso quando não conseguem estabelecer uma conexão, e ferramentas baseadas em libpq exibem mensagens como a acima. O servidor nunca viu uma tentativa de login, então o problema está no caminho da rede ou no servidor não escutando, não nas credenciais.

O erro do sistema operacional no final indica qual: Connection refused significa que o host respondeu, mas nada está escutando nessa porta; timeout expired ou Operation timed out geralmente significa que um firewall descartou os pacotes; could not translate host name é DNS.

Causas comuns

  • O servidor PostgreSQL não está em execução ou está escutando em outra porta.
  • listen_addresses é localhost (o padrão), então o servidor só aceita conexões locais.
  • Um firewall, grupo de segurança ou mapeamento de porta do Docker bloqueia a porta 5432.
  • Nome de host errado ou um nome de host que não resolve a partir do cliente.
  • Conectando-se a localhost dentro de um contêiner, que se refere ao próprio contêiner.

Como corrigir

  1. No servidor, verifique se o PostgreSQL está em execução e em quais endereços e porta ele escuta.

    SHOW listen_addresses;
    SHOW port;
  2. Permitir conexões de rede: defina listen_addresses = '*' (ou o endereço do servidor) em postgresql.conf e reinicie, depois adicione uma pg_hba.conf regra para os clientes.

  3. Teste o caminho de rede a partir do cliente, por exemplo pg_isready -h db.example.com -p 5432, e abra a porta no firewall ou grupo de segurança.

  4. De dentro de um contêiner, conecte-se ao nome de serviço do contêiner do banco de dados ou ao endereço do host em vez de localhost.

Erros relacionados

O código e o texto da mensagem são de documentação do PostgreSQL, Apêndice A: Códigos de erro do PostgreSQL. Veja toda a Lista de erros do PostgreSQL ou pesquise todos os erros do banco de dados.

// menos erros, correções mais rápidas

Trabalhe com PostgreSQL no SQLly

Um cliente SQL nativo para macOS, Windows e Linux com IntelliSense que conhece o esquema, proteções para instruções arriscadas e mensagens de erro claras, para o PostgreSQL e os outros bancos de dados que você usa.