So beheben Sie den PostgreSQL-Fehler „psql: FATAL: Rolle existiert nicht“.

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL: role "yourname" does not existverwirrt die Leute, weil sie nie darum gebeten haben, sich mit „Ihr Name“ zu verbinden. PostgreSQL setzt den Datenbank-Benutzernamen standardmäßig auf den Benutzernamen Ihres Betriebssystems. Sofern keine entsprechende Rolle vorhanden ist, schlägt die Verbindung fehl.

Warum es passiert

Wenn Siepsqlausführen Ohne Argumente füllt PostgreSQL drei Standardwerte aus:

• Benutzername – Ihr Betriebssystem-Benutzername
• Datenbank — das Gleiche wie der Benutzername
• Gastgeber — der lokale Unix-Socket

Also auf einem Computer, auf dem Sie sich alsaliceanmelden , einfachpsql bedeutet „Verbindung zur Datenbankaliceals Rollealiceherstellen“. Eine Neuinstallation von PostgreSQL erstellt nurpostgres Superuser-Rolle, sodass die Verbindung sofort fehlschlägt.

Fix 1: Verbinden Sie sich als Postgres-Rolle

Die schnellste Überprüfung besteht darin, sicherzustellen, dass der Server läuft und erreichbar ist.

# 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

Wenn die Verbindung hergestellt wird, ist der Server in Ordnung und Sie müssen nur Ihre Rolle erstellen.

Fix 2: Erstellen Sie eine Rolle, die Ihrem Benutzernamen entspricht

Dies ist die richtige Lösung für die lokale Entwicklung, da siepsqlbloßstellt funktioniert so, wie Sie es erwartet haben.

# 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

Oder in SQL, wo klarer ist, was Sie gewähren:

sudo -u postgres psql

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

LOGIN ist wichtig und leicht zu übersehen. CREATE ROLE alice; Ohne sie wird eine Gruppenrolle erstellt, die keine Verbindung herstellen kann, und Sie erhalten eine andere verwirrende Fehlermeldung.

Fix 3: Die passende Datenbank muss auch vorhanden sein

Beim Erstellen der Rolle kommt es oft zum nächsten Fehler, den die Leute mit demselben Problem verwechseln.

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

Erstellen Sie es oder benennen Sie eine Datenbank immer explizit.

createdb alice

# Or specify one every time
psql -d postgres

Fix 4: Geben Sie den Benutzer explizit an

Wenn Sie keine Rolle möchten, die Ihrem Betriebssystem-Benutzernamen entspricht, übergeben Sie die gewünschte Rolle.

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

Beachten Sie, dass-U über einen Unix-Socket kann abhängig von Ihrer Authentifizierungskonfiguration immer noch fehlschlagen – siehepeer Abschnitt unten.

Fix 5: Docker und Docker-Compose

Innerhalb eines Containers ist die Rolle beliebigPOSTGRES_USER angegeben, als das Volume zum ersten Mal initialisiert wurde.

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

Die Falle: Diese Umgebungsvariablen werden nur wirksam, wenn das Datenverzeichnis leer ist. Wenn SiePOSTGRES_USERändern Auf einem vorhandenen Volume passiert nichts und Sie erhalten weiterhin die alte Rolle. Erstellen Sie das Volume neu, um es anzuwenden.

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

Peer-Authentifizierung verstehen

Unter Linux verwenden lokale Socket-Verbindungen normalerweisepeer Authentifizierung, die erfordert, dass der Name der Datenbankrolle genau mit dem Benutzernamen des Betriebssystems übereinstimmt. Deshalbsudo -u postgres psql funktioniert währendpsql -U postgres wie Ihr eigener Benutzer dies nicht tut.

# 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

Wechseln deslocal Zeile zuscram-sha-256 lass uns-U Arbeiten Sie über den Socket mit einem Passwort. Anschließend neu laden – die Datei wird nicht automatisch erneut gelesen.

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

Ändern Siepeer to trustnicht . Dies ermöglicht es jedem lokalen Benutzer, sich mit einer beliebigen Rolle ohne Passwort zu verbinden, einschließlich Superuser.

macOS-Besonderheiten

PostgreSQL von Homebrew erstellt einen Superuser, der Ihrem macOS-Benutzernamen und einer Datenbank mit demselben Namen entspricht, alsopsql funktioniert normalerweise. Postgres.app verhält sich ähnlich. Wenn dieser Fehler unter macOS auftritt, liegen die häufigsten Ursachen darin, dass der Dienst nicht ausgeführt wird oder dass eine ältere Installation die neuere überschattet.

brew services list
brew services start postgresql@17

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

Systematisch diagnostizieren

# 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

Der Vergleich der Schritte 2 und 5 beantwortet die Frage in fast allen Fällen sofort.

Verwandte Fehler

überein Häufig gestellte Fragen

F: Was ist der Unterschied zwischen einer Rolle und einem Benutzer?
A: Keine, funktionell. CREATE USER ist die Abkürzung fürCREATE ROLE ... WITH LOGIN. PostgreSQL verwendet „Rollen“ sowohl für Benutzer als auch für Gruppen.

F: Sollte ich meine Entwicklungsrolle zu einem Superuser machen?
A: Für eine rein lokale Datenbank ist es praktisch. Tun Sie dies niemals für etwas, das für andere erreichbar ist, und niemals für eine Rolle, mit der Ihre Anwendung verknüpft ist.

F: Warum funktioniert es in Docker, aber nicht auf dem Host?
A: Verschiedene Server. Der Container verfügt über ein eigenes PostgreSQL mit eigenen Rollen. Für die Verbindung vom Host sind die Portzuordnung und die Anmeldeinformationen des Containers erforderlich.

F: Meine App stellt eine gute Verbindung her, psql jedoch nicht. Warum?
A: Die App verfügt über eine Verbindungszeichenfolge mit einem expliziten Benutzernamen, Passwort und Host. Nacktpsql verwendet Standardwerte. Lesen Sie den Rollennamen aus der Verbindungszeichenfolge Ihrer App und übergeben Sie ihn mit-U.

F: Wie ändere ich das Passwort einer Rolle?
A: ALTER ROLE alice WITH PASSWORD 'new-password'; als Superuser.

Fazit

Dieser Fehler bedeutet, dass PostgreSQL versucht hat, eine nicht vorhandene Rolle zu authentifizieren – fast immer, weilpsql Standardmäßig wird Ihr Betriebssystem-Benutzername verwendet. Überprüfen Sie mit , welche Rollen vorhanden sind , vergleiche mit\du, dann erstellen Sie entweder eine passende Rolle mitwhoami oder übergeben SieLOGIN ausdrücklich.-U ausdrücklich.Denken Sie unter Linux daran, dasspeer Für die Authentifizierung müssen die Namen über lokale Sockets übereinstimmen. Denken Sie in Docker daran, dassPOSTGRES_USER Gilt nur, wenn das Volume zum ersten Mal erstellt wird.