PostgreSQL은 안정성과 확장성이 뛰어난 오픈소스 관계형 Database입니다.

최근에는 Web Application, API Server, Cloud 서비스 환경에서 MySQL과 함께 많이 사용되고 있습니다.

일반적인 서비스 구조:

사용자

↓

Web Server

↓

Application

↓

PostgreSQL Database

↓

Storage

기존 서버 설치 방식:

Linux Server 접속

↓

PostgreSQL 설치

↓

설정 변경

↓

Database 생성

↓

User 설정

문제:

• 서버 환경 차이 발생
• 설치 과정 반복
• 이전 작업 복잡
• 설정 관리 어려움

Docker Compose 방식:

docker-compose.yml

↓

PostgreSQL Image

↓

Database Container

↓

Volume 연결

↓

서비스 실행

장점:

• 동일 환경 재현
• 빠른 서버 구축
• 쉬운 백업
• 간편한 이전

이번 글에서는 Docker Compose PostgreSQL Container 구성부터 환경 변수 설정, Volume 관리, Application 연결, Backup 방법까지 실제 서버 운영 기준으로 알아보겠습니다.

Docker Compose PostgreSQL 구조 이해하기

Docker Compose에서 PostgreSQL은 하나의 Service로 구성합니다.

기본 구조:

services:

  postgres:

    image: postgres:16

동작:

PostgreSQL Image

↓

PostgreSQL Container

↓

Database 실행

운영 환경에서는 추가 설정이 필요합니다.

필수 구성:

• Database Password
• Database Name
• User 설정
• Volume
• Network
• Backup

Docker Compose PostgreSQL 기본 설정

docker-compose.yml:

services:

  postgres:

    image: postgres:16

    environment:

      POSTGRES_PASSWORD: password

      POSTGRES_DB: app

      POSTGRES_USER: appuser


    ports:

      - "5432:5432"


    volumes:

      - postgres-data:/var/lib/postgresql/data


volumes:

  postgres-data:

구조:

PostgreSQL Container

↓

postgres-data Volume

↓

Database 저장

실행:

docker compose up -d

확인:

docker compose ps

결과:

postgres

running

5432 port

Docker Compose PostgreSQL 환경 변수 설정

PostgreSQL Image는 초기 실행 시 Environment 값을 사용합니다.

POSTGRES_PASSWORD

Database 관리자 비밀번호입니다.

예:

POSTGRES_PASSWORD: password

POSTGRES_DB

자동 생성할 Database 이름입니다.

예:

POSTGRES_DB: production

POSTGRES_USER

생성할 사용자 이름입니다.

예:

POSTGRES_USER: admin

Docker Compose PostgreSQL .env 파일 사용

운영 환경에서는 환경 변수를 분리하는 것이 좋습니다.

.env:

POSTGRES_PASSWORD=securepassword

POSTGRES_DB=app

POSTGRES_USER=admin

docker-compose.yml:

services:

  postgres:

    image: postgres:16

    environment:

      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

      POSTGRES_DB: ${POSTGRES_DB}

      POSTGRES_USER: ${POSTGRES_USER}

구조:

.env

↓

Docker Compose

↓

PostgreSQL Container

Docker Compose PostgreSQL Volume 연결

Database는 반드시 Volume 사용을 권장합니다.

설정:

volumes:

  - postgres-data:/var/lib/postgresql/data

의미:

Database 데이터

↓

Volume 저장

↓

Container 삭제 후 유지

확인:

docker volume ls

Docker Compose PostgreSQL 접속 방법

Container 접속:

docker compose exec postgres bash

PostgreSQL 접속:

psql -U admin -d app

Database 확인:

\l

Table 확인:

\dt

사용자 확인:

\du

Docker Compose Application과 PostgreSQL 연결

Application Container에서는 Service 이름으로 접근합니다.

구조:

Application

↓

Docker Network

↓

PostgreSQL

환경 변수:

DB_HOST=postgres

DB_PORT=5432

DB_NAME=app

DB_USER=admin

DB_PASSWORD=password

중요:

잘못된 설정:

DB_HOST=localhost

올바른 설정:

DB_HOST=postgres

이유:

Container 내부 localhost는 자기 자신입니다.

Docker Compose PostgreSQL Network 구성

예:

services:

  app:

    image: my-app

    networks:

      - backend


  postgres:

    image: postgres:16

    networks:

      - backend


networks:

  backend:

구조:

Application

↓

backend Network

↓

PostgreSQL

Docker Compose PostgreSQL Port 관리

PostgreSQL 기본 Port:

5432

개발 환경:

ports:

  - "5432:5432"

외부 접속 가능:

Server:5432

Production 권장:

expose:

  - "5432"

구조:

Application

↓

PostgreSQL

(외부 비공개)

Docker Compose PostgreSQL 백업 방법

PostgreSQL은 pg_dump를 사용합니다.

Backup:

docker compose exec postgres \
pg_dump -U admin app \
> backup.sql

결과:

PostgreSQL Database

↓

backup.sql

복원:

docker compose exec -T postgres \
psql -U admin app \
< backup.sql

Docker Compose PostgreSQL 업데이트 방법

Image 확인:

docker compose pull postgres

재실행:

docker compose up -d

업데이트 과정:

Backup

↓

Image Update

↓

Container 재생성

↓

데이터 확인

Docker Compose PostgreSQL 운영 Best Practice

Production 추천:

Database:

• Volume 사용
• 정기 Backup
• Password 분리
• Port 제한
• Version 고정
• Monitoring 구성

권장:

postgres:16

비추천:

postgres:latest

Docker Compose PostgreSQL 장애 대응

Container 실행 실패

확인:

docker compose logs postgres

확인:

• Password 설정
• Volume 권한
• Storage 상태

Application 연결 실패

확인:

DB_HOST

DB_PORT

USER

PASSWORD

Database 데이터 확인

Volume 확인:

docker volume ls

자주 묻는 질문

Docker Compose에서 PostgreSQL을 운영할 수 있나요?

가능합니다.

개발 환경부터 Production 환경까지 사용할 수 있습니다.

MySQL과 PostgreSQL 중 어떤 것을 사용해야 하나요?

서비스 요구사항에 따라 선택합니다.

PostgreSQL은 복잡한 데이터 구조와 확장 기능이 강점입니다.

PostgreSQL 데이터는 어디에 저장되나요?

Volume을 연결하면 Container 외부 Storage에 저장됩니다.

PostgreSQL Port를 공개해야 하나요?

Production에서는 Application Container 내부 Network 연결을 권장합니다.

마무리

Docker Compose PostgreSQL 구성은 Container 기반 서버에서 안정적인 Database 환경을 구축하는 대표적인 방법입니다.

핵심 구조:

PostgreSQL Container

↓

Volume

↓

Network

↓

Application 연결

↓

Backup 관리

이 구조를 이해하면 Docker Compose 기반 서비스에서 PostgreSQL Database를 안정적으로 운영할 수 있습니다.

다음 글에서는 빠른 데이터 처리와 Cache 시스템 구축에 많이 사용하는 Docker Compose Redis 구성 방법을 알아보겠습니다.