PostgreSQL 컨테이너를 Docker Compose로 관리할 때, 환경 변수 설정은 컨테이너의 초기 동작과 재시작 방식에 중요한 영향을 미칩니다. 특히, 데이터 볼륨의 존재 여부에 따라 각 변수의 적용 시점이 달라지므로 이를 정확히 이해해야 안전한 운영이 가능합니다.

1. 필수 환경 변수: POSTGRES_PASSWORD

PostgreSQL 컨테이너를 Docker 이미지로 구동하는 경우, POSTGRES_PASSWORD 는 데이터 볼륨의 상태와 관계없이 반드시 설정해야 하는 유일한 필수 환경 변수입니다.

변수명 역할 적용 시점 삭제 시 동작
POSTGRES_PASSWORD 슈퍼유저 비밀번호 설정 항상 필요 (초기 설정 및 컨테이너 시작 프로세스) 컨테이너 시작 실패 (보안 오류)

핵심: 이 변수는 컨테이너를 시작하기 위한 보안 요구 사항이며, 데이터가 이미 존재하는 경우에도 docker-compose.yml 파일 내에 명시되어 있어야 합니다.

2. 초기 설정 변수: 적용 시점 이해

POSTGRES_USER와 POSTGRES_DB는 데이터베이스 클러스터가 최초로 생성될 때(데이터 볼륨이 비어있을 때) 만 적용되는 환경 변수입니다.

변수명 역할 적용 시점 재가동 시 변경의 영향
POSTGRES_USER 초기 슈퍼유저 이름 지정 볼륨이 비어있을 때만 무시됨 (기존 사용자 유지)
POSTGRES_DB 초기 데이터베이스 이름 생성 볼륨이 비어있을 때만 무시됨 (기존 DB 유지)

📌 재가동 시의 동작 원리

이미 데이터가 존재하는 볼륨을 연결하여 컨테이너를 docker-compose up -d로 재시작하는 경우, PostgreSQL 이미지는 초기화 프로세스(initdb)를 건너뛰고 기존 데이터를 로드합니다.

따라서, 컨테이너 이름, 로깅 방식 등 다른 설정을 변경하고 재가동할 때, POSTGRES_USER나 POSTGRES_DB의 값을 수정하더라도 이미 존재하는 데이터베이스의 사용자나 이름은 변경되지 않습니다.

3. Docker Compose 예제

다음은 필수 변수와 권장 변수를 포함한 간결한 docker-compose.yml 예제입니다.

services:
  db:
    image: postgres:latest
    restart: always
    container_name: my_postgres_db  # 컨테이너 이름 (변경 가능)
    logging:
      driver: "json-file"          # 로깅 방식 (변경 가능)
    environment:
      # ⚠️ 필수 변수: 반드시 포함되어야 함.
      POSTGRES_PASSWORD: your_secure_password 

      # 초기 설정 변수: 볼륨이 비어있을 때만 적용됨.
      POSTGRES_USER: devuser
      POSTGRES_DB: main_app_db
    ports:
      - "5432:5432"
    volumes:
      # 데이터를 영구 저장하기 위한 볼륨
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

✨ 운영 팁: 안전한 설정 변경

컨테이너 이름, 로깅 설정 등을 변경한 후, 기존 데이터를 유지하며 재가동하려면 다음 명령어를 사용합니다.

docker-compose up -d

주의: 데이터가 담긴 볼륨을 삭제하는 명령어(docker-compose down -v)는 절대 사용하지 않도록 주의해야 합니다.