Docker 기반 PostgreSQL 설치 및 설정 가이드

PostgreSQL는 고성능 오픈소스 관계형 데이터베이스이며, Docker를 활용하면 설치와 관리가 매우 간편해집니다. 본 문서에서는 공식 PostgreSQL Docker 이미지를 사용하여 몇 분 내에 안정적인 데이터베이스 환경을 구축하는 방법을 단계별로 설명합니다.

왜 Docker로 PostgreSQL를 사용해야 할까?

• 환경 일관성: 모든 호환 시스템에서 동일한 실행 환경을 보장
• 격리성: 컨테이너 외부의 시스템 구성과 독립적 운영 가능
• 빠른 시작: 복잡한 설치 과정 없이 한 줄 명령어로 서비스 시작
• 버전 관리 용이: 다양한 버전 간 전환 간편, 프로젝트 요구사항 맞춤 가능

공식 이미지 구조 이해

이 프로젝트는 여러 버전과 리눅스 배포판 조합을 제공하며, 주요 디렉터리 구조는 다음과 같습니다: - 14/, 15/, 16/, 17/, 18/ → 각각의 PostgreSQL 버전 - 각 버전 폴더 내부: alpine3.21/, alpine3.22/, bookworm/, trixie/ → 기반 운영체제 변형 각 플랫폼 폴더에는 다음 파일 포함: - Dockerfile: 이미지 생성 지침 - docker-entrypoint.sh: 컨테이너 시작 진입점 스크립트 - docker-ensure-initdb.sh: 초기화 작업 보조 스크립트 예: 17/alpine3.22/ 는 PostgreSQL 17 + Alpine 3.22 조합을 의미합니다.

기본 컨테이너 실행 절차

1. 준비 작업: 시스템에 Docker가 설치되어 있는지 확인하세요. 미설치 시 공식 문서 참조.
2. 소스 코드 다운로드:

   git clone https://gitcode.com/gh_mirrors/post/postgres
   cd postgres

3. 이미지 빌드 및 실행 (예: 17 + Alpine 3.22):

   cd 17/alpine3.22
   docker build -t pgapp:17-alpine .
   docker run --name db-container -e POSTGRES_PASSWORD=securepass -d pgapp:17-alpine

이 명령은 이름이 db-container인 컨테이너를 생성하고, 기본 유저 postgres의 암호를 securepass로 설정합니다.

핵심 구성 파일 분석

Dockerfile

기반 이미지 정의 예시: - FROM alpine:3.22 → 최소 크기, 보안 중심 - FROM debian:bookworm-slim → 더 많은 도구 포함, 개발 편의성 이러한 선택은 환경 특성에 따라 적절한 기반을 제공합니다.

docker-entrypoint.sh

컨테이너 시작 시 수행되는 핵심 로직: - 데이터 디렉터리 초기화 - 환경 변수 처리 - PostgreSQL 서버 시작 - 종료 신호 감지 및 정상 종료 처리

docker-ensure-initdb.sh

DB 초기화를 보장하는 보조 스크립트: - 초기화 실패 방지 - 확장된 초기화 동작 예시 제공 - 메인 진입 스크립트와 연동 작동

실용적인 운영 팁

실행 중 컨테이너 접속

docker exec -it db-container psql -U postgres

데이터 영속성 유지

컨테이너 삭제 시 데이터 손실 방지를 위해 볼륨 사용:

docker run --name db-container -e POSTGRES_PASSWORD=securepass \
  -v pgdata-volume:/var/lib/postgresql/data \
  -d pgapp:17-alpine

사용자 정의 설정 적용

커스텀 설정 파일 마운트:

docker run --name db-container -e POSTGRES_PASSWORD=securepass \
  -v $(pwd)/custom.conf:/etc/postgresql/custom.conf \
  -d pgapp:17-alpine -c 'config_file=/etc/postgresql/custom.conf'

버전 선택 권장 사항

| 목적 | 추천 버전 | |------|----------| | 생산 환경 | 14 또는 15 (검증 완료, 안정성 우수) | | 개발/테스트 | 18 (최신 기능 체험 가능) | | 자원 제한 환경 | Alpine 기반 (이미지 크기 작음) | | 시스템 도구 필요 | Debian (bookworm/trixie) |

고급 기능: 초기화 확장

docker-ensure-initdb.sh를 커스터마이징하여 다음 작업을 추가할 수 있습니다: - 기본 데이터베이스 및 사용자 생성 - 샘플 데이터 삽입 - 권한 및 설정 자동 설정 프로젝트의 예제 파일을 참고하여 구현하세요.

결론

Docker 기반의 PostgreSQL은 개발자와 시스템 관리자에게 일관성 있고 효율적인 데이터베이스 배포 수단을 제공합니다. 위 단계를 따라하면 빠르게 환경을 구축하고, 프로젝트 요구에 맞게 유연하게 조정할 수 있습니다. 개발, 테스트, 생산 모두에서 시간과 노력을 절약할 수 있습니다. 지금 바로 이 방법을 활용해 컨테이너 기반 데이터베이스를 시작하세요. 자세한 정보는 프로젝트 내 README.md를 참조하시기 바랍니다.