PostgreSQL: entendendo e resolvendo o erro "peer authentication failed"

PostgreSQL: entendendo e resolvendo o erro "peer authentication failed"#

1) Entendendo o erro e quando ele acontece#

Durante configuração de PostgreSQL em Linux, esse erro aparece com frequência em ambiente de produção e homologação:

psql -U domain_user -d app_database -W -c "\dt"

Retorno:

FATAL:  Peer authentication failed for user "domain_user"

A senha está correta, o usuário existe, mas o acesso falha. O problema quase sempre é política de autenticação aplicada na conexão errada, não credencial inválida.

2) Onde isso é definido: pg_hba.conf#

No Linux, o arquivo de controle de acesso baseado em host (pg_hba.conf) varia de acordo com a distribuição:

# Debian / Ubuntu (pacote postgresql-common)
/etc/postgresql/{VERSION}/main/pg_hba.conf

# RHEL / CentOS / AlmaLinux / Rocky Linux
/var/lib/pgsql/{VERSION}/data/pg_hba.conf

Para descobrir o caminho exato do arquivo no seu servidor sem depender de adivinhações:

sudo -u postgres psql -tAc 'SHOW hba_file;'

Linha típica responsável pelo comportamento:

# TYPE  DATABASE        USER            METHOD
local   all             all             peer

Tradução operacional:

• local = socket Unix (conexão sem -h);
• peer = valida por identidade do SO (o usuário que executa o comando no shell precisa ter o mesmo nome do usuário do banco), não por senha.

3) Confirmando o diagnóstico no log do servidor#

Para auditar a rejeição nos logs do sistema e verificar qual regra foi acionada:

# Visualizar logs recentes do PostgreSQL
sudo journalctl -u postgresql --no-pager -n 20

Se a linha indicar FATAL: Peer authentication failed for user "domain_user", a conexão bateu em uma regra local com método peer onde o UID do sistema não confere com o role solicitado.

4) Estratégias de correção (com prós e contras)#

Opção 1 - executar como usuário Linux correspondente#

Se o modelo do ambiente for execução local controlada, a correção mais direta é alinhar usuário SO com usuário DB:

sudo -u domain_user psql -d app_database

Quando uso: scripts internos, automações locais, operação root->service account.

Opção 2 - forçar conexão TCP (bypass de diagnóstico)#

Para separar rapidamente um problema de identidade do SO de uma senha incorreta, force a avaliação das regras host em vez de local:

psql -h 127.0.0.1 -U domain_user -d app_database -W

Quando uso: diagnóstico rápido; ignora o socket Unix e valida a senha via regras host.

Opção 3 - migrar regra para scram-sha-256 (recomendado produção)#

Para aplicações fullstack e serviços que exigem senha forte localmente via socket Unix, a correção definitiva é ajustar o método no pg_hba.conf.

1. Atualizar o hash da senha no banco para garantir compatibilidade com SCRAM:

-- Executar conectado como superusuário postgres
SET password_encryption = 'scram-sha-256';
ALTER ROLE domain_user PASSWORD 'sua_senha_segura';

1. Editar o arquivo pg_hba.conf:

sudo nano $(sudo -u postgres psql -tAc 'SHOW hba_file;')

Atenção à ordem das regras: O pg_hba.conf avalia as regras de cima para baixo e aplica a primeira correspondência. Se você adicionar a nova linha no final do arquivo, a regra genérica local all all peer continuará sendo aplicada antes. Insira a regra específica ACIMA da regra genérica:

# Regra específica para o usuário da aplicação (ACIMA do padrão)
local   all   domain_user   scram-sha-256

# Regra padrão de sistema (abaixo)
local   all   all           peer

1. Recarregar o PostgreSQL sem derrubar conexões ativas:

# Recarga segura (sem downtime)
sudo systemctl reload postgresql
# Ou diretamente via SQL:
# sudo -u postgres psql -c 'SELECT pg_reload_conf();'

1. Testar login:

psql -U domain_user -d app_database -W -c "SELECT current_user;"

5) O que evitar em produção#

1. Nunca use trust em produção: Embora trust remova o erro imediatamente, ele permite que qualquer processo ou usuário local acesse qualquer banco sem validação.
2. Evite md5 em instalações novas: O algoritmo MD5 é vulnerável a colisões e ataques de dicionário offline. O padrão moderno no PostgreSQL 14+ é scram-sha-256.

6) Comparativo técnico dos métodos#

Considerações práticas#

Peer authentication failed não é bug, é proteção funcionando.

O que resolve de forma definitiva é entender a hierarquia do pg_hba.conf, alinhar o método de autenticação ao tipo de conexão e aplicar padrão moderno (scram-sha-256) quando a aplicação depende de senha.

Esse é o ponto que separa "fazer funcionar" de operar PostgreSQL com previsibilidade e segurança em produção.

Veja também

Desenvolvimento Do erro de módulo ao Bun-only: o guia real de troubleshooting do prisma no Linux

Desenvolvimento PostgreSQL não inicia: `could not create lock file "/var/run/postgresql/.s.PGSQL.5432.lock"`

Desenvolvimento Migrando ferramentas para o Python 3.13 no Kali Linux: do handshake TLS às mudanças na c-API

Este post está licenciado sob CC BY-NC.