PostgreSQL을 사용하다 보면 가장 자주 마주치는 오류 중 하나가 바로 “FATAL: password authentication failed for user ‘postgres'” 메시지입니다. 이 오류 때문에 밤잠을 설친 개발자들이 한둘이 아닐 텐데요, 저 역시 처음 PostgreSQL을 다룰 때 이 문제로 꽤 골머리를 앓았던 기억이 납니다.
다행히 이 오류는 원인을 정확히 파악하면 생각보다 간단하게 해결할 수 있습니다. 오늘은 이 문제를 근본적으로 해결하는 방법과 함께, 앞으로 같은 문제가 발생하지 않도록 예방하는 팁까지 상세하게 알아보겠습니다.
1. FATAL: password authentication failed for user ‘postgres’ 오류 발생 원인
PostgreSQL에서 “password authentication failed” 오류가 발생하는 이유는 크게 세 가지로 나눌 수 있습니다.
잘못된 패스워드 입력
가장 기본적인 원인으로, 실제로 잘못된 패스워드를 입력한 경우입니다. 특히 PostgreSQL을 새로 설치했을 때 기본 패스워드가 설정되지 않은 상태에서 패스워드를 요구받는 상황이 많습니다.
pg_hba.conf 설정 문제
PostgreSQL의 클라이언트 인증을 담당하는 pg_hba.conf 파일의 설정이 잘못된 경우입니다. 이 파일은 어떤 사용자가 어떤 방식으로 데이터베이스에 접근할 수 있는지를 결정하는 중요한 역할을 합니다.
데이터베이스 서버 재시작 필요
설정을 변경했지만 PostgreSQL 서비스를 재시작하지 않아서 변경사항이 반영되지 않은 경우입니다.
2. 우선 pg_hba.conf 파일 잘 분석해야 합니다!
pg_hba.conf 파일을 이해하는 것이 이 문제 해결의 핵심입니다. HBA는 ‘Host-Based Authentication’의 줄임말로, 호스트 기반 인증을 의미합니다.
파일 위치 찾기
먼저 pg_hba.conf 파일이 어디에 있는지 확인해야 합니다:
SHOW hba_file;
일반적인 위치는 다음과 같습니다:
- Ubuntu/Debian:
/etc/postgresql/[버전]/main/pg_hba.conf - CentOS/RHEL:
/var/lib/pgsql/[버전]/data/pg_hba.conf - Windows:
C:\Program Files\PostgreSQL\[버전]\data\pg_hba.conf
설정 파일 구조 이해하기
pg_hba.conf 파일의 각 라인은 다음과 같은 구조를 가집니다:
TYPE DATABASE USER ADDRESS METHOD
TYPE: 연결 유형 (local, host, hostssl, hostnossl) DATABASE: 접근 가능한 데이터베이스 (all, 특정 DB명) USER: 사용자명 (all, postgres, 특정 사용자명) ADDRESS: IP 주소 또는 주소 범위 METHOD: 인증 방식 (trust, peer, md5, password, scram-sha-256)
인증 방식별 특징
| 방식 | 설명 | 보안성 | 사용 권장 상황 |
|---|---|---|---|
| trust | 패스워드 없이 무조건 허용 | 낮음 | 로컬 개발 환경만 |
| peer | OS 사용자명과 DB 사용자명 일치 확인 | 중간 | 로컬 연결시 |
| md5 | MD5 해시된 패스워드로 인증 | 중간 | 일반적인 상황 |
| scram-sha-256 | SHA-256 기반 강화된 인증 | 높음 | 보안이 중요한 환경 |
3. 단계별 해결 방법
방법 1: 임시 trust 설정으로 접근 후 패스워드 설정
가장 확실한 방법은 먼저 trust 방식으로 접근한 후 패스워드를 설정하는 것입니다.
1단계: pg_hba.conf 파일 수정
sudo nano /etc/postgresql/[버전]/main/pg_hba.conf
다음 라인을 찾아서:
local all postgres peer
이렇게 변경합니다:
local all postgres trust
2단계: PostgreSQL 서비스 재시작
sudo systemctl restart postgresql
3단계: postgres 사용자로 로그인하여 패스워드 설정
sudo -u postgres psql
패스워드 설정:
ALTER USER postgres PASSWORD '새로운패스워드';
\q
4단계: pg_hba.conf를 md5로 다시 변경
local all postgres md5
5단계: 서비스 재시작 후 테스트
sudo systemctl restart postgresql
psql -U postgres -h localhost
방법 2: 시스템 사용자를 통한 직접 접근
Ubuntu나 Debian 시스템에서는 postgres 시스템 사용자로 직접 접근할 수 있습니다.
sudo -i -u postgres
psql
ALTER USER postgres PASSWORD '새로운패스워드';
\q
exit
이후 pg_hba.conf에서 peer를 md5로 변경하고 서비스를 재시작합니다.
방법 3: pgAdmin 사용자를 위한 호스트 연결 설정
pgAdmin을 사용하는 경우, 호스트 연결 설정도 확인해야 합니다:
# IPv4 local connections:
host all all 127.0.0.1/32 md5
# IPv6 local connections:
host all all ::1/128 md5
4. 특수한 상황에서의 해결법
Docker 환경에서의 문제
Docker로 PostgreSQL을 실행하는 경우, 환경변수를 통해 패스워드를 설정해야 합니다:
docker run --name postgres-container \
-e POSTGRES_PASSWORD=mypassword \
-p 5432:5432 \
-d postgres:15
기존 컨테이너의 패스워드를 변경하려면:
docker exec -it postgres-container psql -U postgres
ALTER USER postgres PASSWORD '새로운패스워드';
여러 PostgreSQL 버전이 설치된 경우
시스템에 여러 PostgreSQL 버전이 설치되어 있으면 포트 충돌이 발생할 수 있습니다:
sudo /etc/init.d/postgresql status
출력 예시:
9.6/main (port 5432): online
11/main (port 5433): online
13/main (port 5434): online
연결할 때 정확한 포트를 지정해야 합니다:
psql -U postgres -p 5433 -h localhost
Windows 환경에서의 해결법
Windows에서는 서비스 관리자를 통해 PostgreSQL을 재시작해야 합니다:
services.msc실행- PostgreSQL 서비스 찾기
- 마우스 우클릭 → 다시 시작
또는 명령 프롬프트에서:
net stop postgresql-x64-[버전]
net start postgresql-x64-[버전]
PostgreSQL의 패스워드 인증 실패 문제는 처음에는 복잡해 보이지만, pg_hba.conf 파일의 구조와 인증 방식을 이해하고 나면 충분히 해결 가능한 문제입니다.
가장 중요한 것은 무작정 trust 모드로 설정해두고 그대로 방치하지 않는 것입니다. 보안을 고려한 적절한 인증 방식을 선택하고, 정기적으로 패스워드를 변경하며, 접근 로그를 모니터링하는 습관을 기르는 것이 진정한 해결책이라고 할 수 있습니다.