PostgreSQL "Peer authentication failed for user": connect the right way, or change pg_hba.conf

1. Connect as the matching system user

The usual way to administer PostgreSQL, and it’s fine as it is:

sudo -u postgres psql
sudo -u postgres createuser --pwprompt app
sudo -u postgres createdb -O app shop

There’s no need to give the postgres user a password for this.

2. Connect over TCP instead

The rule depends on how you connect. Local socket and TCP are separate lines in the configuration, and adding -h switches:

psql -U app -d shop                   # socket: peer
psql -h localhost -U app -d shop      # TCP: password

Check the current rules, from inside psql as an admin:

SELECT type, database, user_name, address, auth_method
FROM pg_hba_file_rules;

 type  | database | user_name |   address   | auth_method
-------+----------+-----------+-------------+---------------
 local | {all}    | {postgres}|             | peer
 local | {all}    | {all}     |             | peer
 host  | {all}    | {all}     | 127.0.0.1   | scram-sha-256

A connection string with a host, such as postgresql://app:secret@localhost/shop, already uses TCP, so applications often don’t run into this at all. Applications that connect with no host set use the socket, and fail with this error. Set the host.

The user needs a password for that. If it has none:

ALTER ROLE app WITH PASSWORD 'new-password-here';

The Password Generator gives you a strong one. Use its shell-safe option if it goes in a connection URL. If this now fails with a different message, see “password authentication failed”.

3. Change the rule for local connections

If you want passwords on the socket too, edit pg_hba.conf. Find it first:

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

It’s usually /etc/postgresql/18/main/pg_hba.conf on Ubuntu, and /var/lib/pgsql/18/data/pg_hba.conf on RHEL. Change the second local line, and leave the postgres one alone:

# TYPE  DATABASE  USER      METHOD
local   all       postgres  peer
local   all       all       scram-sha-256

The order matters. PostgreSQL uses the first line that matches, and never looks further. A rule below a broader one is never reached.

Then reload, which needs no restart:

sudo systemctl reload postgresql

And test:

psql -U app -d shop

Keeping peer for postgres means that sudo -u postgres psql still works. If you change that one too and don’t know its password, you’ve locked yourself out, so keep a session open while you test.

4. Map a system user to a database user

Maybe the system user and the database user are legitimately different, as with a service account running as deploy that should connect as app. You can stay with peer, which needs no password at all, using a map. In pg_ident.conf:

# MAPNAME   SYSTEM-USERNAME   PG-USERNAME
appmap      deploy            app

And in pg_hba.conf:

local   shop   app   peer map=appmap

Reload as before. It’s a clean setup for scripts on the same machine, with no password stored in any file.

5. Docker and the other engines’ defaults

The official Docker image is set up differently, with trust on the local socket inside the container, and scram-sha-256 from elsewhere:

docker exec -it db psql -U postgres

On RHEL, fresh installs use peer on the socket and ident over TCP. That second one gives a similar message:

FATAL:  Ident authentication failed for user "app"

Change it to scram-sha-256 in the host lines the same way, and reload. On managed services such as RDS, you don’t get peer at all, as you only connect over TCP.