[Troubleshooting] Docker Volume에 남은 PostgreSQL 인증 정보로 인한 DB 연결 실패 해결

문제 상황

팀원들과 동일한 PostgreSQL 비밀번호를 .env에 설정했음에도 로컬 환경에서만 DB 인증 오류가 발생했습니다.

특히 Spring Boot 테스트 실행 시 contextLoads() 단계에서 Hibernate 초기화가 실패하며 애플리케이션 컨텍스트가 정상적으로 올라오지 않았습니다.

원인 분석

PostgreSQL Docker 이미지는 POSTGRES_PASSWORD 값을 최초 데이터베이스 초기화 시점에만 적용합니다.

기존 Docker Volume에는 과거에 사용하던 비밀번호로 초기화된 PostgreSQL 데이터가 남아 있었기 때문에, .env의 비밀번호를 팀과 동일하게 변경해도 실제 PostgreSQL 사용자 비밀번호는 변경되지 않았습니다.

따라서 다음과 같은 불일치가 발생했습니다.

애플리케이션 설정 비밀번호 = 현재 팀 공통 비밀번호
PostgreSQL Volume 내부 비밀번호 = 기존 비밀번호

이 상태에서 Spring Boot가 PostgreSQL에 연결하려 하면서 인증에 실패했고, 그 결과 Hibernate가 DB 연결 정보를 읽지 못해 초기화 과정까지 연쇄적으로 실패했습니다.

해결 방안

로컬 개발 환경의 DB 데이터를 유지할 필요가 없었기 때문에 기존 PostgreSQL Docker Volume을 삭제한 후 컨테이너를 다시 생성했습니다.

docker compose down -v
docker compose up -d

Volume이 제거된 상태에서 PostgreSQL이 다시 초기화되면서 현재 .env에 설정된 팀 공통 비밀번호가 실제 DB 사용자 비밀번호로 적용되었습니다.

운영 환경이나 데이터 보존이 필요한 환경에서는 Volume을 삭제하지 않고 다음과 같이 PostgreSQL 사용자 비밀번호를 직접 변경해야 합니다.

ALTER USER postgres WITH PASSWORD '새비밀번호';

성과

Docker 환경변수 변경만으로는 기존 PostgreSQL Volume의 인증 정보가 변경되지 않는다는 점을 확인했습니다.

Volume 재생성을 통해 애플리케이션 설정과 PostgreSQL의 실제 인증 정보를 일치시켰고, DB 연결 오류 및 Spring Boot contextLoads() 실패 문제를 해결했습니다.

또한 이후 동일한 문제가 발생했을 때 .env 설정뿐 아니라 기존 Volume의 초기화 상태까지 함께 확인해야 한다는 점을 명확히 했습니다.