docker-compose PostgreSQL DB 백업 및 복원

docker-compose로 운영하는 postgreSQL DB를 백업하고 복원하는 방법을 정리합니다.

PostgreSQL Docker Compose 환경에서 DB 백업 및 복원 방법

PostgreSQL을 Docker Compose로 운영할 때 DB를 백업하고 복원하는 방법은 크게 두 가지로 나눌 수 있습니다.

1. Docker 컨테이너 내에서 직접 pg_dump와 pg_restore 사용
2. Docker 컨테이너 외부에서 docker-compose exec를 통해 명령 실행

두 방법 모두 장단점이 있으므로 상황에 맞게 선택하여 사용하시면 됩니다.

1. 백업 방법

1-1. Docker 컨테이너 내에서 직접 백업

이 방법은 Docker 컨테이너 쉘에 접속하여 백업 명령어를 실행하는 것입니다. 아래의 명령으로 PostgreSQL 컨테이너 쉘에 접속합니다.

docker-compose exec [서비스_이름] bash

[서비스_이름]은 docker-compose.yml 파일에 정의된 PostgreSQL 서비스 이름입니다 (예: db, postgres). 컨테이너에 접속 후 아래의 명령으로 DB를 백업합니다.

pg_dump -U [유저_이름] -d [데이터베이스_이름] > /backup/[백업_파일명].sql

• -U [유저_이름]: 데이터베이스 사용자 이름 (예: postgres).
• -d [데이터베이스_이름]: 백업할 데이터베이스 이름.
  
• /backup/[백업_파일명].sql: 백업 파일을 저장할 경로와 파일명.

컨테이너의 backup폴더를 docker-compose가 실행되는 클라이언트 컴퓨터의 backup폴더와 연결됩니다. backup 볼륨을 추가한 아래의 예시를 참고하세요.

docker-compose 예시파일

services:
  db:
  image: postgres:14
  volumes:
    - ./data:/var/lib/postgresql/data
    - ./backup:/backup  # 백업 디렉토리 마운트

Note

/backup 디렉토리는 컨테이너 내부에 있어야 합니다. 영구적인 백업을 위해 docker-compose.yml에 볼륨을 마운트하여 호스트와 컨테이너 간에 공유하는 것이 좋습니다.

1-2. Docker Compose 외부에서 백업

이 방법은 호스트 OS에서 docker-compose exec 명령어를 사용하여 컨테이너 내의 pg_dump를 실행하고 결과를 호스트로 바로 저장하는 방법입니다. pg_dump명령을 이용해서 DB파일을 backup폴더로 백업합니다.

docker-compose exec [서비스_이름] \
                pg_dump \
                  -U [유저_이름] \
                  -d [데이터베이스_이름] > ./backup/[백업_파일명].sql

./backup/[백업_파일명].sql: 호스트 OS의 현재 디렉토리 아래 backup 폴더에 백업 파일이 생성됩니다. 이 방법은 별도의 볼륨 설정 없이도 호스트에 바로 백업 파일을 생성할 수 있어 편리합니다.

2. 복원 방법

복원 방법도 백업과 유사하게 두 가지로 나눌 수 있습니다. 복원을 진행하기 전에 복원할 데이터베이스가 존재해야 합니다.

2-1. Docker 컨테이너 내에서 직접 복원

docker cp 명령어를 사용하여 호스트의 백업 파일을 컨테이너 내부로 복사합니다.

docker cp ./backup/[백업_파일명].sql [컨테이너_이름]:/tmp/

[컨테이너_이름]은 docker-compose ps 명령어로 확인할 수 있습니다 (예: myproject_db_1). /tmp/는 컨테이너 내 임시 디렉토리입니다. 아래의 명령으로 PostgreSQL 컨테이너 쉘에 접속합니다.

docker-compose exec [서비스_이름] bash

복사한 파일을 psql이용하여 복원합니다. 아래의 명령을 이용해서 /tmp폴더로 복사한 DB 백업을 데이터베이스에 적용할 수 있습니다.

psql -U [유저_이름] -d [데이터베이스_이름] < /tmp/[백업_파일명].sql

2-2. Docker Compose 외부에서 복원

이 방법은 호스트 OS에서 docker-compose exec를 통해 psql 명령어를 실행하고, stdin으로 백업 파일을 전달하는 방법입니다.

docker-compose exec -T [서비스_이름] psql -U [유저_이름] -d [데이터베이스_이름] < ./backup/[백업_파일명].sql

• -T: docker-compose exec의 pseudo-TTY 할당을 비활성화하는 옵션입니다. 이 옵션은 스크립트 실행 시 필요합니다.
• ./backup/[백업_파일명].sql: 호스트 OS의 백업 파일 경로.

3. DB 백업 및 복원 방법

PostgreSQL 데이터베이스를 복원하는 두 가지 주요 방법인 psql과 pg_restore의 차이를 알아봅니다. 위의 예제에서는 psql을 이용하여 DB를 백업하고 복원 했습니다.

간단한 복원이나 수동편집이 필요한 경우 유용하지만 대규모 데이터베이스를 빠르고 효율적으로 복원하는 경우 pg_restore를 사용합니다.

특징	psql	pg_restore
백업 파일 형식	SQL 스크립트(.sql)	커스텀/디렉토리/tar 아카이브 (-Fc/-Fd/-Ft)
복원 속도	느림 (순차적 실행)	빠름 (병렬 복원 가능, -j 옵션)
복원 유연성	낮음 (전체 복원만 가능)	높음 (선택적 복원 가능, --table 옵션)
파일 크기	큼 (압축되지 않은 텍스트)	작음 (기본적으로 압축)
사용 환경	소규모 DB, 개발/테스트 환경	대규모 프로덕션 DB, 정기 백업/복원
요약	단순하지만 비효율적인 방법	복잡하지만 유연하고 효율적인 방법

4. 추가 팁: 자동 백업 스크립트

정기적인 백업을 위해 백업 스크립트를 작성하고, cronjob 등을 이용하여 자동화할 수 있습니다.

예시 DB백업 script

#!/bin/bash

# 설정
SERVICE_NAME="db"
DB_USER="postgres"
DB_NAME="my_database"
BACKUP_DIR="./backup"

# 백업 디렉토리 생성
mkdir -p $BACKUP_DIR

# 파일명 설정 (예: my_database-2025-08-02T10:00:00.sql)
TIMESTAMP=$(date +"%Y-%m-%dT%H:%M:%S")
BACKUP_FILE="$BACKUP_DIR/$DB_NAME-$TIMESTAMP.sql"

# 백업 실행
echo "Starting backup of '$DB_NAME'..."
docker-compose exec $SERVICE_NAME pg_dump -U $DB_USER -d $DB_NAME > $BACKUP_FILE

# 백업 성공 여부 확인
if [ $? -eq 0 ]; then
  echo "Backup successful: $BACKUP_FILE"
else
  echo "Backup failed!"
  rm $BACKUP_FILE
fi

# 오래된 백업 파일 삭제 (예: 7일 지난 파일)
find $BACKUP_DIR -name "*.sql" -type f -mtime +7 -delete

이 스크립트를 Crontab에 등록하여 매일 특정 시간에 실행하도록 설정할 수 있습니다.

# 매일 새벽 2시에 백업 실행
0 2 * * * /path/to/your/backup_db.sh

카테고리 다른 글