Docker로 PostgreSQL 생성 관리 예시

PostgreSQL 사용시 도커를 사용하는 이유

• 컴퓨터에 직접 설치하지 않아도 되서 편하게 만들 수 있고, OS 오염이 없음
• 팀 또는 프로젝트마다 버전/설정을 격리할 수 있음
• 설정을 파일(docker-compose.yml)로 남기면 누구나 똑같이 재현 가능

생성 방법은 두가지

• 방법 1 - docker run : 명령 한 줄로 빠르게 생성 가능. 단발성/실험용.
• 방법 2 - docker compose : 설정을 파일로 관리. 실제 프로젝트에서는 이 방식 사용을 권장.

docker-compose.yml 작성

프로젝트 루트에 docker-compose.yml 작성

services:
  postgres:
    image: postgres:16
    container_name: my-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

1. 서비스 정의(services)

도커 컴포즈로 실행할 컨테이너(서비스)들을 정의하는 최상위 블록

• postgres: : 이 컨테이너의 서비스 이름. 도커 네트워크 내부의 컨테이너들끼리 서로를 부를 때 쓰는 주소 겸 역할명
• image: postgres:16 : 도커 허브(Docker Hub)에서 가져올 이미지를 지정. 공식 PostgreSQL 16 버전 이미지를 사용하겠다는 의미
• container_name: my-postgres : 실행될 컨테이너의 고유한 이름
• restart: unless-stopped : 컨테이너 재시작 정책. 사용자가 직접 멈추지(docker stop) 않는 이상, 에러로 인해 종료되거나 컴퓨터(서버)가 재부팅될 때 컨테이너를 자동으로 다시 실행함.
  • no : 기본값, 재시작 안함
  • always : 무조건 다시 시작
  • on-failure : 비정상 종료시만 재시작

2. 환경 변수(environment)

컨테이너 내부에서 PostgreSQL이 처음 실행될 때 필요한 설정값들 지정

• POSTGRES_USER: appuser : 데이터베이스의 최고 관리자(SuperUser) 계정 이름을 appuser로 생성함.
• POSTGRES_PASSWORD: secret : 해당 관리자 계정의 비밀번호를 secret으로 설정함.
• POSTGRES_DB: appdb : 컨테이너가 처음 실행될 때 기본적으로 만들어질 데이터베이스의 이름을 appdb로 지정함.

3. 포트 연결(ports)

호스트(현재 내 컴퓨터 또는 서버)와 컨테이너 간의 네트워크 포트를 연결

• - "5432:5432" : [호스트 포트]:[컨테이너 포트] 형태. 내 컴퓨터의 5432포트로 들어오는 요청을, 컨테이너 내부의 5432포트(PostgreSQL 기본 포트)로 연결(포워딩)해 줌.

4. 데이터 저장소(volumes)

도커 컨테이너는 삭제되면 내부 데이터가 모두 삭제됨. 이를 방지하고 데이터를 영구 보존하기 위해 사용

• - pgdata:/var/lib/postgresql/data : 아래 정의되는 pgdata라는 도커 관리 볼륨을, 컨테이너 내부에서 DB 데이터가 실제로 저장되는 경로(/var/lib/postgresql/data)와 연결함. 이렇게 하면 컨테이너를 지웠다 다시 만들어도 데이터가 그대로 유지됨.

5. 볼륨 선언 (최하단 volumes)

• pgdata: : 위 서비스 블록에서 사용한 pgdata라는 이름의 '네임드 볼륨(Named Volume)'을 도커가 생성하고 관리하도록 선언하는 최상위 항목

 

도커 생성하기

docker-composer.yml 파일을 작성하고, 해당 폴더에서 아래와 같이 도커를 생성하고 시작합니다.

$ docker compose up -d      # 생성 + 시작
$ docker compose ps         # 상태 확인

 

DB 접근하기

컨테이너 안에서 psql 실행

$ docker exec -it my-postgres psql -U appuser -d appdb

 

상태 및 로그, 시작/종료

$ docker compose ps                    # 또는: docker ps
$ docker compose logs -f postgres      # 실시간 로그 (Ctrl+C로 보기 종료)

$ docker compose stop                  # 끄기(데이터·컨테이너 유지)
$ docker compose start                 # 다시 켜기
$ docker compose restart postgres      # 재시작

 

데이터 초기화

DB데이터는 볼륨에 저장되므로, 컨테이너를 지워도 데이터가 남음. 아래 세가지를 구분해서 사용해야 함.

명령	컨테이너	데이터(볼륨)
docker compose stop	멈춤(유지)	유지
docker compose down	제거	유지
docker compose down -v	제거	삭제(초기화)