When you encounter the error FATAL: Peer authentication failed for user "user", PostgreSQL is telling you that the operating system user attempting to connect doesn't match the database user being requested. This happens because:

• PostgreSQL's peer authentication method relies on the underlying OS authentication
• Your current system user doesn't have matching credentials in PostgreSQL
• The connection is being made locally through a Unix domain socket

Peer authentication is actually a security feature, not a bug. It's the default for local connections in many PostgreSQL installations because:

# Typical default pg_hba.conf entry for local connections
local   all             all                                     peer

This configuration means any local connection attempt must come from a system user with the same name as the PostgreSQL user they're trying to access.

Option 1: Match System and PostgreSQL Users

The most secure approach is to create a matching system user:

# Create matching system user
sudo useradd -m postgres_user
sudo -u postgres_user psql -U postgres_user database_name

Option 2: Modify pg_hba.conf (If Appropriate)

For development environments, you might change the authentication method:

# Change this line in pg_hba.conf from:
local   all             all                                     peer

# To either:
local   all             all                                     md5
# Or for passwordless dev environments:
local   all             all                                     trust

Remember to reload PostgreSQL after changes:

sudo systemctl reload postgresql
# Or for older systems
sudo service postgresql reload

Option 3: Connect Using TCP Instead of Unix Socket

Force TCP connection which typically uses password authentication:

psql -h localhost -U username database_name

For more complex setups, you can specify different methods for different users:

# In pg_hba.conf
local   db1             user1                                   peer
local   db2             user2                                   md5
host    all             all             127.0.0.1/32            md5

This configuration allows:

• user1 to access db1 via peer auth
• user2 to access db2 with password
• All other TCP connections via localhost with password

While changing authentication methods solves immediate problems, consider:

• Peer authentication is generally more secure than password-based for local connections
• MD5 is being phased out in favor of SCRAM-SHA-256
• Never use 'trust' in production environments
• Always test authentication changes thoroughly

---

When you encounter the error FATAL: Peer authentication failed for user "user", PostgreSQL is using UNIX socket authentication. This method relies on the operating system's user identity rather than password verification. The database compares the connecting client's OS username with the requested database username.

The most common scenario is when you attempt to connect via psql while logged into the server as a different OS user. For example:

# Logged in as root but trying to connect as 'user'
root@server:~# psql -U user database

PostgreSQL's authentication rules are defined in pg_hba.conf. A typical peer authentication entry looks like:

# TYPE  DATABASE  USER  ADDRESS  METHOD
local   all       all            peer

Option 1: Switch to the matching OS user first

sudo su - user
psql database

Option 2: Modify pg_hba.conf (requires PostgreSQL restart)

# Change authentication method to md5 or trust
local   all       all            md5

Option 3: Create a matching OS user

sudo adduser dbuser
sudo -u dbuser psql -U dbuser database

Security implications vary:

• peer: Most secure for local connections (requires matching OS user)
• md5: Password protected but works for any OS user
• trust: No authentication (only for development)

1. Verify pg_hba.conf location:

psql -U postgres -c "SHOW hba_file;"

2. Check effective authentication rules:

psql -U postgres -c "SELECT * FROM pg_hba_file_rules;"

3. Test connection with explicit host specification:

psql -h localhost -U user database