PostgreSQL password authentication failed for user postgres 원인 5가지 해결법

psql: error: FATAL:  password authentication failed for user "postgres"

이 한 줄을 보고 비밀번호를 열 번쯤 다시 입력해본 경험, 다들 있으실 겁니다. 그런데 진짜 문제가 비밀번호인 경우는 의외로 많지 않습니다. 이 에러는 자격 증명, 계정 상태, 인증 방식, 네트워크라는 4개 영역에서 발생하는 5가지 원인이 모두 같은 메시지로 뭉뚱그려져 나옵니다. 그래서 무작정 비밀번호만 바꾸면 해결이 안 되는 거죠.

이 글에서는 "당황하지 말고 위에서부터" 순서대로 진단·격리하는 방법을 복붙 가능한 명령과 함께 정리했습니다.

먼저 진단 순서도부터 — 위에서 아래로

에러가 났을 때 다음 순서를 그대로 따라가세요. 위 단계에서 걸러지면 아래는 볼 필요가 없습니다.

원인 1·3·4 — 자격 증명과 계정 자체 문제

원인 1: 오타와 환경변수 누락

가장 흔하고 가장 허무한 원인입니다. 특히 환경변수가 주입되지 않아 빈 문자열로 접속을 시도하면, PostgreSQL은 그냥 "인증 실패"라고만 알려줍니다. 셸에서 직접 확인해보세요.

echo "[$DB_PASSWORD]"   # 대괄호 사이가 비었다면 변수 주입 실패
psql -U postgres -h localhost -d postgres

비밀번호에 !, $ 같은 특수문자가 있으면 셸이 변형시키므로, 변수는 반드시 작은따옴표나 .env 파일로 관리하세요.

원인 3: 존재하지 않는 유저·DB

연결하려는 롤이나 DB가 실제로 없을 수도 있습니다. 슈퍼유저로 접속해 목록부터 확인합니다.

\du           -- 롤(사용자) 목록과 권한
\l            -- 데이터베이스 목록

\du 결과에 postgres가 없다면 인증 이전에 계정 자체가 문제입니다.

원인 4: 비밀번호가 설정되지 않았거나 다름

소스 빌드나 일부 설치 방식에서는 postgres 롤에 비밀번호가 아예 없을 수 있습니다. 슈퍼유저로 들어가 재설정합니다.

ALTER ROLE postgres WITH PASSWORD 'newpass';

저장된 해시 형식이 궁금하면 다음으로 확인하세요. 출력값 앞에 SCRAM-SHA-256$ 또는 md5가 붙습니다.

SELECT rolname, rolpassword FROM pg_authid WHERE rolname = 'postgres';

원인 2 — pg_hba.conf 인증 method 불일치

여기가 PostgreSQL 14 이후 가장 많은 사람을 괴롭히는 함정입니다. pg_hba.conf는 "어떤 접속에 어떤 인증 방식을 쓸지" 정의하는데, 서버가 비밀번호를 저장한 방식과 받겠다고 선언한 방식이 어긋나면 비밀번호가 맞아도 실패합니다.

먼저 파일 위치를 찾습니다.

SHOW hba_file;
SHOW password_encryption;   -- scram-sha-256 또는 md5

scram vs md5 — 왜 어긋나는가

핵심은 이렇습니다. PostgreSQL 14부터 password_encryption 기본값이 md5에서 scram-sha-256으로 바뀌었습니다. 그래서 구버전에서 마이그레이션했거나, pg_hba.conf는 md5인데 비밀번호는 scram으로 저장된 경우 충돌이 납니다.

pg_hba.conf를 다음처럼 맞춰줍니다.

# TYPE  DATABASE  USER  ADDRESS       METHOD
# 변경 전
local   all       all                 md5
host    all       all   127.0.0.1/32  md5
# 변경 후 (권장)
local   all       all                 scram-sha-256
host    all       all   127.0.0.1/32  scram-sha-256

수정 후 재시작 없이 리로드합니다.

SELECT pg_reload_conf();

pg_ctl reload   # 또는 sudo systemctl reload postgresql

실무 팁: method를 scram으로 바꾼 뒤에도 실패한다면, 비밀번호가 여전히 md5 해시로 저장돼 있을 가능성이 큽니다. ALTER ROLE ... PASSWORD로 한 번 더 재설정하면 현재 password_encryption 방식으로 해시가 새로 갱신됩니다. 저는 14로 업그레이드한 운영 DB에서 이 한 줄로 절반 이상의 인증 티켓을 닫았습니다.

원인 5 — 도커·원격 접속과 Spring 설정

로컬에선 되는데 도커나 원격에서만 실패한다면 인증보다 네트워크 노출 문제일 확률이 높습니다.

postgresql.conf에서 리스닝 주소를 열고, pg_hba.conf에 외부 host 라인을 추가합니다.

# postgresql.conf
listen_addresses = '*'

# pg_hba.conf
host  all  all  0.0.0.0/0  scram-sha-256

도커로 띄울 땐 비밀번호를 환경변수로 명시해야 postgres 롤이 그 값으로 생성됩니다.

docker run -d --name pg \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_USER=postgres \
  -p 5432:5432 postgres:16

Spring application.yml 점검

Spring Boot에서 가장 흔한 실수는 환경변수가 비어 있는데도 앱이 그대로 빈 비밀번호로 접속을 시도하는 경우입니다.

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: postgres
    password: ${DB_PASSWORD}   # 미주입 시 빈 문자열 → 인증 실패
    driver-class-name: org.postgresql.Driver

또한 구버전 JDBC 드라이버는 scram 인증을 지원하지 못합니다. 드라이버를 42.x 최신으로 올리고, 일부 환경에서는 scram 의존성(com.ongres.scram)이 함께 포함됐는지 확인하세요. 최신 org.postgresql:postgresql:42.x에는 보통 자동 포함됩니다.

결론: 진단 체크리스트와 권장 설정

1. echo $DB_PASSWORD     → 오타·빈 문자열 확인
2. \du / \l              → 계정·DB 존재 확인
3. ALTER ROLE ... PASSWORD → 비밀번호 재설정(해시 갱신)
4. SHOW hba_file → method를 scram으로 통일 → reload
5. listen_addresses='*', host 0.0.0.0/0 → 네트워크 확인

위에서부터 차근차근 격리하면 대부분 3단계 안에서 해결됩니다. 운영 환경에서는 md5 대신 scram-sha-256을 표준으로 쓰고, 0.0.0.0/0은 가능한 한 신뢰 가능한 대역으로 좁히는 것을 권장합니다.

자주 묻는 질문 (FAQ)

Q. 비밀번호가 분명 맞는데도 계속 실패합니다. 왜죠? A. pg_hba.conf의 인증 method와 저장된 해시 형식이 어긋났을 가능성이 큽니다. method를 scram-sha-256으로 맞추고 ALTER ROLE postgres WITH PASSWORD '...'로 비밀번호를 다시 설정해 해시를 새 방식으로 갱신한 뒤 pg_reload_conf()를 실행하세요.

Q. 로컬에선 접속되는데 도커/원격에서만 실패합니다. A. 인증이 아니라 노출 설정 문제일 수 있습니다. listen_addresses = '*'를 설정하고 pg_hba.conf에 host all all 0.0.0.0/0 scram-sha-256 라인을 추가한 뒤 리로드하세요.

Q. PostgreSQL 14로 올린 뒤 Spring 앱에서만 인증 에러가 납니다. A. 14부터 기본 인증이 scram-sha-256으로 바뀌어 구버전 JDBC 드라이버가 이를 처리하지 못하는 경우입니다. org.postgresql:postgresql 드라이버를 42.x 최신 버전으로 업그레이드하세요.