Docker로 PostgreSQL 생성 관리 예시

코딩하는목수 — Wed, 5 Aug 2026 18:06:03 +0900

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`	제거	삭제(초기화)

코딩하는목수의 재무모델링

Docker로 PostgreSQL 생성 관리 예시

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

docker-compose.yml 작성

1. 서비스 정의(services)

2. 환경 변수(environment)

3. 포트 연결(ports)

4. 데이터 저장소(volumes)

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