Como corrigir o erro PostgreSQL ‘psql: FATAL: a função não existe’

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL: role "yourname" does not existconfunde as pessoas porque elas nunca pediram para se conectar como “seunome”. O PostgreSQL padroniza o nome de usuário do banco de dados para o nome de usuário do seu sistema operacional e, a menos que exista uma função correspondente, a conexão falhará.

Por que isso acontece

Quando você executapsql sem argumentos, o PostgreSQL preenche três padrões:

• Nome de usuário — seu nome de usuário do sistema operacional
• Banco de dados — o mesmo que o nome de usuário
• Anfitrião — o soquete Unix local

Então, em uma máquina onde você faz login comoalice, simplespsql significa “conectar ao banco de dadosalicecomo função “. Uma nova instalação do PostgreSQL cria apenas oalice função de superusuário, para que a conexão falhe imediatamente.postgresCorreção 1: Conecte-se como a função postgres

A verificação mais rápida – confirme se o servidor está funcionando e acessível.

Se conectar, o servidor está bom e você só precisa criar sua função.

# Linux: the postgres OS user maps to the postgres role
sudo -u postgres psql

# macOS with Homebrew: your own user is usually the superuser
psql postgres

# Explicit form that works anywhere
psql -U postgres -d postgres -h localhost

Correção 2: crie uma função que corresponda ao seu nome de usuário

Esta é a solução adequada para o desenvolvimento local, porque torna simples

trabalhe da maneira que você esperava.psqlOu em SQL, que fica mais claro sobre o que você está concedendo:

# From the shell
sudo -u postgres createuser --interactive --pwprompt

# It will ask:
#   Enter name of role to add: alice
#   Enter password for new role: ****
#   Shall the new role be a superuser? (y/n) n
#   Shall the new role be allowed to create databases? (y/n) y
#   Shall the new role be allowed to create more new roles? (y/n) n

é essencial e fácil de perder.

sudo -u postgres psql

CREATE ROLE alice WITH LOGIN PASSWORD 'a-strong-password';
ALTER ROLE alice CREATEDB;
\q

LOGIN sem ele, cria uma função de grupo que não pode ser conectada e você recebe um erro confuso diferente.CREATE ROLE alice;Correção 3: o banco de dados correspondente também deve existir

Criar a função geralmente produz o próximo erro, que as pessoas confundem com o mesmo problema.

Crie-o ou sempre nomeie um banco de dados explicitamente.

psql
# psql: FATAL: database "alice" does not exist

Correção 4: Especifique o usuário explicitamente

createdb alice

# Or specify one every time
psql -d postgres

Se você não quiser uma função que corresponda ao seu nome de usuário do sistema operacional, passe a função desejada.

Observe que

psql -U myapp -d myapp_development -h localhost

# Or set it in the environment for the session
export PGUSER=myapp
export PGDATABASE=myapp_development
export PGHOST=localhost
psql

em um soquete Unix ainda pode falhar dependendo da sua configuração de autenticação — veja o-U seção abaixo.peerCorreção 5: Docker e docker-compose

Dentro de um contêiner, a função é qualquer

especificado quando o volume foi inicializado pela primeira vez.POSTGRES_USERA armadilha:

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp_development
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

# Connect from the host
psql -U myapp -d myapp_development -h localhost -p 5432

# Connect inside the container
docker compose exec db psql -U myapp -d myapp_development

essas variáveis de ambiente só entram em vigor quando o diretório de dados está vazio. Se você mudar em um volume existente, nada acontece e você continua com a função antiga. Recrie o volume para aplicá-lo.POSTGRES_USERCompreendendo a autenticação de pares

# Destroys the database contents — make sure that is acceptable
docker compose down -v
docker compose up -d

No Linux, as conexões de soquete local geralmente usam

autenticação, que exige que o nome da função do banco de dados corresponda exatamente ao nome de usuário do sistema operacional. É por issopeer funciona enquantosudo -u postgres psql como seu próprio usuário não.psql -U postgresMudando o

# Find the config file
sudo -u postgres psql -c 'SHOW hba_file;'
# e.g. /etc/postgresql/17/main/pg_hba.conf

# pg_hba.conf
# TYPE  DATABASE  USER  ADDRESS       METHOD

# peer: OS username must equal the role name
local   all       all                 peer

# scram-sha-256: password authentication, any username
local   all       all                 scram-sha-256
host    all       all   127.0.0.1/32  scram-sha-256

linha paralocal vamosscram-sha-256 trabalhe no soquete com uma senha. Recarregue depois — o arquivo não é relido automaticamente.-UNão mude

sudo systemctl reload postgresql
# or
sudo -u postgres psql -c 'SELECT pg_reload_conf();'

. Isso permite que qualquer usuário local se conecte como qualquer função sem senha, incluindo superusuários.peer to trustEspecificações do macOS

O PostgreSQL do Homebrew cria um superusuário que corresponde ao seu nome de usuário do macOS e um banco de dados com o mesmo nome, portanto

geralmente funciona. Postgres.app se comporta de maneira semelhante. Se você vir esse erro no macOS, as causas comuns são que o serviço não está em execução ou que uma instalação mais antiga está ocultando a mais recente.psqlDiagnosticando Sistematicamente

brew services list
brew services start postgresql@17

# Check which psql is first on PATH
which psql
psql --version

A comparação das etapas 2 e 5 responde à pergunta imediatamente em quase todos os casos.

# 1. Is the server running?
pg_isready
# /tmp:5432 - accepting connections

# 2. Which roles exist?
sudo -u postgres psql -c '\du'

# 3. Which databases exist?
sudo -u postgres psql -c '\l'

# 4. What is psql defaulting to?
psql -d postgres -c 'SELECT current_user, current_database();'

# 5. What is your OS username?
whoami

Erros Relacionados

Erro

P: Qual é a diferença entre uma função e um usuário?

R: Nenhum, funcionalmente.
é uma abreviação deCREATE USER. O PostgreSQL usa “função” para usuários e grupos.CREATE ROLE ... WITH LOGINP: Devo tornar minha função de desenvolvimento um superusuário?

R: Para um banco de dados puramente local, é conveniente. Nunca faça isso para algo acessível a outras pessoas e nunca para uma função à qual seu aplicativo se conecta.
P: Por que funciona no Docker, mas não no host?

R: Servidores diferentes. O contêiner possui seu próprio PostgreSQL com funções próprias. A conexão do host requer o mapeamento da porta e as credenciais do contêiner.
P: Meu aplicativo se conecta bem, mas o psql não. Por que?

R: O aplicativo possui uma string de conexão com nome de usuário, senha e host explícitos. Nu
usa padrões. Leia o nome da função na string de conexão do seu aplicativo e passe-o compsqlP: Como altero a senha de uma função?-U.

como superusuário.
A: ALTER ROLE alice WITH PASSWORD 'new-password';Conclusão

Este erro significa que o PostgreSQL tentou autenticar uma função que não existe — quase sempre porque

o padrão é o nome de usuário do seu sistema operacional. psqlVerifique quais funções existem com, compare com\du, então crie uma função correspondente comwhoami ou passeLOGIN explicitamente.-U explicitamente.No Linux, lembre-se dissopeer a autenticação exige que os nomes correspondam aos soquetes locais; no Docker, lembre-se dissoPOSTGRES_USER aplica-se apenas quando o volume é criado pela primeira vez.