Pular para o conteúdo
EntrarCriar minha VPS

PostgreSQL não conecta: erros comuns e como resolver

Quando o PostgreSQL recusa uma conexão, a mensagem de erro já indica a causa: "FATAL: password authentication failed" é senha errada; "could not connect to server" é porta bloqueada ou processo parado; "no pg_hba.conf entry" é permissão de rede ausente. Cada diagnóstico tem um comando específico, veja abaixo.

Diagnóstico: verificar se o PostgreSQL está rodando

Antes de qualquer outra coisa, confirme que o processo está ativo e escutando na porta correta:

bash
# Status do container PostgreSQL
docker compose ps postgres

# Logs recentes do container
docker compose logs postgres --tail=30

# Verificar se a porta 5432 está sendo escutada
ss -tlnp | grep 5432

# Testar conexão local (de dentro da VPS)
docker compose exec postgres psql -U postgres -c "SELECT version();"

Causa 1: autenticação falhou (senha incorreta)

"FATAL: password authentication failed for user" significa que o usuário existe mas a senha está errada. Redefina a senha sem precisar parar o banco:

bash
# Conectar como superusuário (de dentro do container)
docker compose exec postgres psql -U postgres

-- Dentro do psql, redefinir a senha
ALTER USER meu_usuario WITH PASSWORD 'nova_senha_segura';
\q

# Confirmar com a nova senha
docker compose exec postgres psql -U meu_usuario -d meu_banco -c "SELECT 1;"

# Se a variável de ambiente no .env for POSTGRES_PASSWORD,
# recrie o container após alterar — o init só roda no primeiro boot:
# docker compose down && docker compose up -d

Causa 2: pg_hba.conf não permite a conexão

"FATAL: no pg_hba.conf entry for host" significa que a origem da conexão não está autorizada. Edite o pg_hba.conf para permitir o host ou a rede:

bash
# Ver o pg_hba.conf atual
docker compose exec postgres cat /var/lib/postgresql/data/pg_hba.conf

# Adicionar permissão para uma rede Docker (ex: 172.16.0.0/12)
# Editar via docker cp ou montar o arquivo via volume

# Linha a adicionar no pg_hba.conf:
# host    all             all             172.16.0.0/12           scram-sha-256

# Recarregar configuração sem reiniciar o banco
docker compose exec postgres psql -U postgres -c "SELECT pg_reload_conf();"

Causa 3: porta 5432 não acessível externamente

Por padrão, o PostgreSQL no Docker não expõe a porta no host. Se você precisa conectar de fora da VPS (ex.: DBeaver no seu computador), mapeie a porta:

bash
# No docker-compose.yml, adicionar exposição da porta:
services:
  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"   # expõe no host (acessível externamente)
    # Sem "ports:", a porta só é acessível dentro da rede Docker

# Verificar regras de firewall da VPS
ufw status
ufw allow 5432/tcp   # liberar apenas se necessário

# Testar conexão externa (do seu computador)
psql -h IP_DA_VPS -p 5432 -U usuario -d banco

Causa 4: banco ou usuário não existe

"FATAL: database does not exist" ou "FATAL: role does not exist", o banco ou usuário não foi criado. Crie manualmente:

bash
# Criar usuário e banco
docker compose exec postgres psql -U postgres << 'EOF'
CREATE USER meu_usuario WITH PASSWORD 'senha_segura';
CREATE DATABASE meu_banco OWNER meu_usuario;
GRANT ALL PRIVILEGES ON DATABASE meu_banco TO meu_usuario;
EOF

# Listar bancos existentes
docker compose exec postgres psql -U postgres -c "\l"

# Listar usuários existentes
docker compose exec postgres psql -U postgres -c "\du"

Não quer configurar manualmente?

Implante o PostgreSQL em menos de 5 minutos com a Runstack. Infraestrutura da OPEN Datacenter, com servidores em São Paulo.

Criar minha VPSVer apps prontos

Perguntas frequentes

Somente de dentro do container como usuário postgres do sistema. docker compose exec postgres psql -U postgres usa autenticação "peer" (processo no mesmo OS), não requer senha. De fora do container, sempre é necessária autenticação por senha ou certificado.

scram-sha-256 é o padrão desde PostgreSQL 14 e é mais seguro. Use md5 apenas para compatibilidade com clientes muito antigos (PostgreSQL < 10 ou drivers desatualizados). Configure em postgresql.conf: password_encryption = scram-sha-256.

docker compose exec postgres psql -U postgres -c "SELECT pid, usename, application_name, client_addr, state FROM pg_stat_activity WHERE state = 'active';", mostra conexões ativas. Para matar uma conexão específica: SELECT pg_terminate_backend(pid) WHERE pid = <número>.

O padrão do PostgreSQL é 100 conexões simultâneas. Aumente em postgresql.conf: max_connections = 200. Mas a solução mais robusta é usar connection pooling com PgBouncer, ele multiplexia centenas de conexões de aplicação em poucas conexões reais ao banco, reduzindo drasticamente o consumo de memória.

Adicione um container temporário na mesma rede Docker: docker run --rm --network nome_da_rede postgres:16 psql -h nome_do_servico_postgres -U usuario -d banco -c "SELECT 1;". Se a conexão falhar de dentro da rede Docker, o problema é senha ou pg_hba.conf, não firewall.

Continue lendo