Runstack
    databases/Artigo

    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();"
    Dica
    Se o container está em estado "Exit" ou "Restarting", o problema é na inicialização — não na conexão. Leia os logs para identificar a causa antes de continuar.

    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
    Atenção
    Alterar POSTGRES_PASSWORD no .env só tem efeito se o volume do banco for recriado. Para bancos existentes, use ALTER USER dentro do psql — não altere apenas o .env.

    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();"
    Dica
    Contêineres Docker em bridge network usam IPs no range 172.16.0.0/12. Para liberar conexões de qualquer origem (apenas em ambiente interno): host all all 0.0.0.0/0 scram-sha-256 — nunca use em banco exposto à internet.

    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
    Atenção
    Expor o PostgreSQL diretamente na internet (porta 5432 pública) é um risco de segurança sério. Prefira conexão via SSH tunnel: ssh -L 5432:localhost:5432 root@IP_DA_VPS e conecte em localhost:5432.

    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"

    $ runstack deploy --plan starter

    Não quer configurar manualmente?

    Não quer configurar manualmente? Implante o PostgreSQL em menos de 3 minutos com a Runstack. Infraestrutura da OPEN DATACENTER, com servidores no Brasil.

    Começar agoraVer planos e preços

    Perguntas frequentes

    Conteúdos relacionados

    VPS para PostgreSQL no Brasil →Como instalar o PostgreSQL →Backup do PostgreSQL com DockerPostgreSQL em produção com DockerPostgreSQL lento: como otimizar queries