PostgreSQL 'FATAL: role does not exist' 오류 해결 방법
PostgreSQL을 사용하다 보면 가끔 의외의 오류를 마주하게 되는데, 그중에서도 초보자들이 자주 겪는 대표적인 오류 중 하나가 바로 'FATAL: role "사용자명" does not exist'입니다. 이 오류는 PostgreSQL에 접속할 때 발생하며, 말 그대로 해당하는 이름의 역할(사용자 계정)이 존재하지 않는다는 뜻이죠.
간단한 로그인 시도만 했을 뿐인데 갑자기 붉은 경고창과 함께 마주하게 되는 이 메시지는, 개발 초기 설정 실수나 서버 구성 변경 등 다양한 원인에서 발생할 수 있습니다. 하지만 다행히도 이 문제는 몇 가지 체크 포인트만 잘 따라가면 손쉽게 해결할 수 있답니다. 이 글에서는 PostgreSQL에서 'role does not exist' 오류가 발생했을 때 어떤 과정을 거쳐 해결할 수 있는지, 실제 경험과 함께 하나씩 짚어보도록 하겠습니다.
목차
📌 오류가 발생하는 이유
PostgreSQL에서 'FATAL: role does not exist' 오류는 보통 데이터베이스에 접속을 시도하는 사용자 계정이 시스템에 존재하지 않을 때 발생합니다. 특히 로컬 개발 환경이나 새롭게 PostgreSQL을 설치한 경우에 자주 마주치는 문제입니다. PostgreSQL은 OS 사용자 이름과 동일한 이름의 데이터베이스 사용자 계정이 기본적으로 필요하기 때문에, 이 계정이 존재하지 않으면 오류가 뜨는 거죠.
예를 들어, 터미널에서 다음과 같이 접속을 시도한다고 해볼게요:
psql -d mydb위 명령어를 입력한 사용자의 시스템 계정 이름이 PostgreSQL 내에 존재하지 않으면, PostgreSQL은 해당 유저를 찾을 수 없다는 메시지를 반환하게 됩니다.
📌 사용자 이름 확인 방법
먼저 내가 접속하려는 사용자 계정이 PostgreSQL에 실제로 존재하는지 확인하는 것이 중요해요. PostgreSQL에 접속 가능한 관리자 권한 계정으로 로그인한 뒤, 아래 명령어로 현재 존재하는 사용자 계정들을 조회할 수 있습니다:
\du위 명령을 실행하면, 현재 등록된 모든 역할(role) 목록이 출력돼요. 내가 로그인하려는 사용자 이름이 이 리스트에 없다면, 오류는 당연한 결과겠죠.
📌 PostgreSQL에 사용자 추가하기
만약 사용자 계정이 존재하지 않는다면, 새로 추가해야 합니다. 아래와 같이 명령어를 입력하면, PostgreSQL 내에 해당 역할을 만들 수 있어요:
CREATE ROLE 사용자명 WITH LOGIN PASSWORD '비밀번호';그리고 나서, 권한을 더 부여하려면 다음과 같이 SUPERUSER 권한도 줄 수 있죠:
ALTER ROLE 사용자명 WITH SUPERUSER;이제 해당 사용자로 로그인하면 더 이상 오류 없이 PostgreSQL에 접속할 수 있어요.
📌 pg_hba.conf 설정 확인
가끔 사용자 계정이 잘 생성되어 있는데도 오류가 발생하는 경우가 있어요. 이럴 땐 pg_hba.conf 파일의 설정도 점검해보는 것이 좋아요. 이 파일은 PostgreSQL 클라이언트 접속을 제어하는 보안 설정 파일인데요, 접속 가능한 사용자, IP, 인증 방식 등을 정의합니다.
파일 위치는 보통 /etc/postgresql/버전번호/main/pg_hba.conf 또는 /var/lib/pgsql/data/pg_hba.conf에 있어요. 파일을 열어서 아래와 같은 형식이 있는지 확인해보세요:
local all 사용자명 md5수정 후에는 PostgreSQL 서버를 재시작해야 설정이 적용돼요:
sudo systemctl restart postgresql📌 실전 팁 및 자주 하는 실수
제가 실제로 이 오류를 처음 겪었던 건 우분투에 PostgreSQL을 설치하고, 별 생각 없이 터미널에서 `psql` 명령어를 입력했을 때였어요. 그때 제 시스템 사용자 계정 이름으로 로그인하려다 보니 PostgreSQL에서는 해당 역할이 존재하지 않아 오류가 났죠. 당시에는 아무것도 몰라서 멘붕이었지만, 알고 보니 계정만 추가하면 되는 간단한 문제였더라고요.
이 오류에서 가장 흔한 실수는 다음과 같아요:
- PostgreSQL 사용자 계정과 OS 계정을 혼동하는 경우
- 계정은 만들었지만 LOGIN 권한을 주지 않은 경우
- pg_hba.conf에서 해당 계정을 허용하지 않은 경우
이런 부분들만 체크해보면, 대부분의 경우 오류를 금방 해결할 수 있습니다.
📌 실제 경험을 바탕으로 한 추가 팁
PostgreSQL을 처음 접하는 개발자나 서버 관리자에게는 이런 권한 문제 하나도 꽤 낯설고 당황스러울 수 있어요. 특히 여러 환경에서 PostgreSQL을 설치하거나 운영할 때, 사용자 계정 오류는 너무 흔하게 발생하죠. 그래서 저는 업무에서 겪었던 몇 가지 실제 상황을 바탕으로, 보다 실용적인 팁들을 추가로 정리해봤어요.
1. 로컬 vs 리모트 접속 구분하기
로컬에서는 잘 접속되던 PostgreSQL이, 리모트 환경에서는 ‘role does not exist’ 오류를 뿜을 때가 있어요. 이런 경우는 보통 pg_hba.conf의 설정이 리모트 접속을 허용하지 않거나, 해당 서버에 생성된 역할이 없기 때문이에요. 리모트 클라이언트용 계정은 별도로 생성해줘야 하고, pg_hba.conf에 IP 대역도 잘 지정해줘야 해요. 이 부분이 누락되면 계정이 있어도 오류가 발생할 수 있답니다.
2. 도커(Docker) 환경에서는 더 신경 써야 해요
도커로 PostgreSQL 컨테이너를 띄우는 경우, 컨테이너 생성 시점에만 계정을 만들 수 있도록 설정하는 경우가 많아요. 만약 컨테이너 실행 후에 계정을 추가하려고 한다면, 수동으로 접속해서 SQL로 추가해야 해요. 도커에서는 다음과 같은 환경 변수를 이용해 초기 유저를 지정할 수 있죠:
POSTGRES_USER=admin
POSTGRES_PASSWORD=secret초기화 설정을 잘못하면, 나중에 컨테이너를 지우고 다시 띄워야 하는 번거로움도 있어요. 도커 쓸 때는 설정을 깔끔하게 정리해두는 게 핵심!
3. 사용자 계정과 데이터베이스 이름을 일치시키는 습관
PostgreSQL은 기본적으로 로그인 사용자와 동일한 이름의 데이터베이스에 접속하려고 해요. 그래서 사용자명과 DB명을 동일하게 맞춰주는 습관을 들이면 실수할 확률이 줄어요. 예를 들어, ‘devuser’라는 유저를 만들었다면, ‘devuser’라는 DB도 만들어두는 거죠. 이렇게 하면 psql 명령어만으로도 손쉽게 접속이 가능해요:
psql -U devuser4. Mac이나 Windows에서 Homebrew, WSL 환경도 주의!
Mac에서 Homebrew로 PostgreSQL을 설치한 경우, 기본 로그인 계정이 macOS 사용자와 매칭되지 않는 문제가 생기곤 해요. 이럴 땐 아예 PostgreSQL 유저를 명시적으로 지정하거나, 슈퍼유저로 전환해서 계정을 새로 만드는 게 좋습니다. Windows의 WSL(Windows Subsystem for Linux)에서도 비슷한 이슈가 발생할 수 있어요. 이때는 `sudo -u postgres psql` 명령으로 PostgreSQL에 먼저 접속하고 필요한 역할을 추가하면 문제없이 해결됩니다.
5. 간단한 점검 리스트 만들기
매번 이 오류가 날 때마다 구글링하는 것도 피곤하죠. 그래서 저는 아래와 같은 체크리스트를 만들어두고 있어요. 참고해서 여러분도 활용해보세요!
- ✅ 현재 사용자 이름이 PostgreSQL 내에 존재하는가?
- ✅ 역할에 LOGIN 권한이 부여되어 있는가?
- ✅ 해당 계정에 맞는 DB가 존재하는가?
- ✅ pg_hba.conf에 접속 허용 설정이 되어 있는가?
- ✅ PostgreSQL 서버를 재시작했는가?
💡 실전 꿀팁: PostgreSQL에서 오류 메시지를 두려워하지 마세요. 대부분은 아주 사소한 설정에서 비롯되며, 차근차근 원인을 파악하면 누구나 쉽게 해결할 수 있습니다. 오류는 내가 더 능숙한 개발자가 되는 과정이에요!
📌 결론
'FATAL: role does not exist' 오류는 PostgreSQL을 사용하는 과정에서 자주 마주치는 대표적인 에러 중 하나입니다. 하지만 그 원인은 단순한 사용자 계정 누락 또는 권한 설정 문제인 경우가 대부분이에요. 처음에는 이 에러 메시지가 낯설고 당황스럽게 느껴질 수 있지만, 지금까지 소개한 점검 포인트를 하나씩 따라가다 보면 쉽게 해결할 수 있습니다.
무엇보다 중요한 것은, 문제의 원인을 정확히 파악하는 능력을 기르는 것입니다. 사용자 계정이 있는지 확인하고, 필요한 권한을 부여하며, pg_hba.conf와 같은 설정 파일도 주기적으로 점검해보는 습관이 필요해요. 다양한 환경—로컬, 리모트, Docker, WSL 등—에 따라 상황은 달라질 수 있지만, 원칙은 동일합니다.
이 오류를 한 번 해결해본 경험은 PostgreSQL과의 거리감을 줄이고, 보다 자신 있게 데이터베이스를 다룰 수 있게 해줄 거예요. 앞으로 비슷한 에러가 발생해도 당황하지 말고, 지금 배운 내용을 바탕으로 차근차근 문제를 풀어나가 보세요.