PostgreSQL: Entendendo e Resolvendo o Erro “Peer authentication failed”

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.

---

1) O que o erro realmente significa

Quando o PostgreSQL retorna Peer authentication failed, ele está ignorando a senha por design. Isso acontece porque a conexão caiu em uma regra local com método peer.

No peer, o fluxo é:

o kernel informa ao PostgreSQL qual usuário Linux executou o processo;
PostgreSQL compara esse usuário SO com o usuário PostgreSQL solicitado;
se não bater, bloqueia.

Exemplo prático:

você está logado no Linux como perc_user (whoami);
tenta acessar o banco como domain_user;
resultado: falha imediata, mesmo digitando senha correta.

---

2) Onde isso é definido: `pg_hba.conf`

No Linux, em geral:

/etc/postgresql/{VERSION}/main/pg_hba.conf

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, não por senha.

---

3) Diagnóstico objetivo de campo

3.1 Validar logs em tempo real

sudo tail -f /var/log/postgresql/postgresql-{VERSION}-main.log

3.2 Confirmar tipo de conexão que você está usando

Sem -h, é socket e vai para regra local.

Com -h 127.0.0.1, vira TCP e passa a usar regra host.

3.3 Confirmar identidade no SO

whoami

3.4 Confirmar existência do usuário no PostgreSQL

Como superusuário:

sudo -u postgres psql -c "\du"

---

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 para escapar da regra `local`

O “pulo do gato” para troubleshooting rápido:

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

Isso força avaliação das regras host no pg_hba.conf, normalmente com senha.

Quando uso: validação rápida de credencial e isolamento de problema de método de auth.

---

Opção 3 — Migrar regra para `scram-sha-256` (recomendado produção)

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

Exemplo:

local   all   domain_user   scram-sha-256

Aplicação:

Editar arquivo:

sudo nano /etc/postgresql/{VERSION}/main/pg_hba.conf

Reiniciar serviço:

sudo systemctl restart postgresql

Testar login:

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

Nota de segurança

Evite md5 em ambiente novo. scram-sha-256 é padrão moderno e mais resistente contra vetores de captura/replay em comparação ao legado.

---

5) Armadilhas que geram falso diagnóstico

Alterar pg_hba.conf e esquecer restart/reload.
Testar com psql sem -h achando que está validando regra host.
Confundir erro de autenticação com ausência de role.
Misturar IPv4/IPv6 (127.0.0.1 vs ::1) sem regra correspondente.

Verificação de regras IPv6 (quando aplicável)

host    all   all   ::1/128   scram-sha-256

Se a aplicação resolve localhost para IPv6 e só existe regra IPv4, o comportamento pode parecer inconsistente.

---

6) Comparativo técnico dos métodos

Método	Usa senha?	Baseado no SO?	Uso indicado
`peer`	Não	Sim	administração local via SSH e scripts internos controlados
`trust`	Não	Não	laboratório temporário (nunca produção)
`scram-sha-256`	Sim	Não	aplicações, produção moderna, compliance

---

7) Checklist sênior para fechar incidente

Estou conectando via socket ou TCP?
Quem sou eu no Linux (whoami)?
A regra certa existe no pg_hba.conf?
O serviço recarregou configuração?
A role existe e tem permissão no banco?
IPv4/IPv6 está coerente com o host que a aplicação usa?

---

Conclusão

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.

Este post está licenciado sob CC BY-NC.