[ Docker ] PostgreSQL Docker 볼륨 설정 및 외부 접속 구성하기

---

Intro

 

안녕하세요. 환이s입니다 👋

이번 글에서는 Docker 환경에서 PostgreSQL 16을 실행하고, 볼륨 설정을 통해 데이터 영속성을 확보한 뒤
외부에서 접속 가능한 DB 서버 환경을 구성하는 방법을 정리해 보려고 합니다.

 

실무에서는 PostgreSQL을

• VM 기반 서버
• 또는 클라우드 관리형 DB

로 사용하는 경우가 많지만,

테스트 환경이나 로컬/개발 서버에서는 Docker 기반 PostgreSQL이 훨씬 빠르고 관리하기 편리합니다.

 

특히 Docker 볼륨을 활용하면 컨테이너를 삭제하거나 재생성하더라도 DB 데이터는 그대로 유지할 수 있기 때문에 실습용 환경뿐 아니라 운영 전 검증 환경에서도 매우 유용합니다.

 

이번 글의 목표는 다음과 같습니다.

• PostgreSQL Docker 이미지 다운로드
• Docker Volume을 이용한 DB 데이터 영구 저장
• 컨테이너 실행 및 정상 동작 확인
• 외부(DB 툴)에서 접속 가능한 환경 구성

---

1. PostgreSQL Docker 이미지 다운로드

 

먼저 PostgreSQL 16 공식 이미지를 다운로드합니다.

docker pull postgres:16

 

• postgres : PostgreSQL 공식 이미지
• 16 : PostgreSQL 메이저 버전
  (운영 환경에서는 버전을 명시적으로 고정하는 것을 권장합니다)

---

2. 이미지 다운로드 확인

 

이미지가 정상적으로 다운로드 되었는지 확인합니다.

docker images

 

 

위 캡처 화면처럼 postgres 16 이미지가 보인다면 정상입니다.

---

3. Docker 볼륨 생성

 

PostgreSQL 이미지를 다운로드하고 확인까지 마쳤다면,

이제 바로 컨테이너를 실행하고 싶어질 수 있습니다.

 

하지만 DB 컨테이너는 바로 실행하기 전에 반드시 한 가지를 먼저 고려해야 합니다.

바로 데이터를 어디에 저장할 것인가입니다.

 

Docker 컨테이너는 기본적으로 일회성 실행 환경이기 때문에,

별도의 설정 없이 컨테이너 내부에만 데이터를 저장하면

컨테이너를 삭제(docker rm)하거나 재생성하는 순간

DB 데이터도 함께 삭제됩니다.

 

즉,

• ❌ 볼륨 미사용 → 컨테이너 삭제 = 데이터 삭제
• ⭕ 볼륨 사용 → 컨테이너 삭제 후 재생성해도 데이터 유지

라는 결정적인 차이가 발생합니다.

 

특히 PostgreSQL과 같은 데이터베이스 서버는
테스트 환경이라 하더라도 데이터 유실 자체가 치명적이기 때문에,
Docker 환경에서도 반드시 Volume을 통한 데이터 영속성 확보가 필요합니다.

 

1️⃣ Docker Volume을 사용하는 이유

Docker Volume을 사용하면 다음과 같은 장점이 있습니다.

• 컨테이너 재생성 시에도 데이터 유지
• 이미지 업데이트/버전 변경 시에도 데이터 안전
• 호스트 서버의 특정 디렉터리에 종속되지 않음
• Docker가 직접 관리하므로 권한/경로 이슈가 적음

👉 실무에서는 DB 컨테이너 = 무조건 볼륨 사용이 기본 원칙입니다.

 

2️⃣ PostgreSQL Docker 이미지의 데이터 저장 위치

PostgreSQL 공식 Docker 이미지는
DB 데이터를 컨테이너 내부의 다음 경로에 저장합니다.

/var/lib/postgresql/data

 

따라서 이 경로를 Docker Volume과 연결해 주어야 컨테이너와 무관하게 데이터가 안전하게 유지됩니다.

 

3️⃣ Docker Volume 생성

docker volume create postgres_data

• postgres_data
  → PostgreSQL DB 데이터를 저장하기 위한 전용 볼륨
• Docker가 직접 관리하는 볼륨이기 때문에
  권한 문제나 경로 충돌 없이 안정적으로 사용할 수 있습니다.

 

볼륨 생성 후에는 다음 명령어로 정상 생성 여부를 확인할 수 있습니다.

docker volume ls

 

 

이 볼륨은 이후 컨테이너 실행 시
다음과 같이 PostgreSQL 데이터 디렉터리와 연결됩니다.

postgres_data  →  /var/lib/postgresql/data

 

👉 이 설정을 통해 컨테이너의 수명과 DB 데이터의 수명을 완전히 분리할 수 있습니다.

---

4. PostgreSQL 컨테이너 생성 및 실행

 

앞 단계에서 PostgreSQL 전용 Docker Volume을 생성했기 때문에,
이제 해당 볼륨을 연결하여 실제 PostgreSQL DB 컨테이너를 실행할 차례입니다.

이 단계에서는 단순히 컨테이너를 띄우는 것이 아니라,

• DB 계정 생성
• 기본 데이터베이스 생성
• 외부 접속 포트 개방
• 컨테이너 재시작 정책 설정
• DB 데이터 영속성 확보

까지 한 번에 구성합니다.

 

아래 명령어를 실행하여 PostgreSQL 컨테이너를 생성하고 실행합니다.

docker run -d 
--name postgres-db 
-e POSTGRES_USER=admin 
-e POSTGRES_PASSWORD=admin123 
-e POSTGRES_DB=postgres 
-p 5432:5432 
-v postgres_data:/var/lib/postgresql/data 
--restart unless-stopped 
postgres:16

 

1️⃣ 실행 옵션 설명

위 명령어에 사용된 주요 옵션은 다음과 같습니다.

옵션	설명
-d	컨테이너를 백그라운드(datached) 모드로 실행
--name postgres-db	컨테이너 이름 지정
POSTGRES_USER	PostgreSQL 기본 관리자 계정 생성
POSTGRES_PASSWORD	관리자 계정 비밀번호 설정
POSTGRES_DB	컨테이너 최초 실행 시 생성할 기본 DB
-p 5432:5432	호스트 ↔ 컨테이너 포트 매핑 (외부 접속 허용)
-v postgres_data:/var/lib/postgresql/data	DB 데이터 영구 저장을 위한 볼륨 연결
--restart unless-stopped	서버 재부팅 시 컨테이너 자동 재시작
postgres:16	사용할 PostgreSQL 이미지

 

👉 이 한 줄의 docker run 명령으로
운영 환경에서도 바로 사용할 수 있는 PostgreSQL 기본 구조가 완성됩니다.

 

2️⃣ 컨테이너 정상 실행 확인

컨테이너가 정상적으로 실행 중인지 확인합니다.

docker ps

 

위 이미지처럼 postgres-db 컨테이너가 실행 중이라면 정상입니다.

 

3️⃣ PostgreSQL 로그 확인

PostgreSQL이 정상적으로 초기화되었는지 로그를 통해 확인합니다.

docker logs postgres-db

 

아래 메시지가 출력된다면 정상적으로 가동된 상태입니다.

database system is ready to accept connections

 

이 메시지는 PostgreSQL 서버가 외부 연결을 받을 준비가 완료되었다는 의미입니다.

---

5. 컨테이너 내부 접속

 

다음으로는 

컨테이너 내부에서 직접 PostgreSQL에 접속하여 정상 동작 여부를 확인합니다.

docker exec -it postgres-db psql -U admin -d postgres

 

정상적으로 접속되면 다음과 같은 프롬프트가 출력됩니다.

postgres=#

 

이 상태에서 SQL 명령어를 실행할 수 있으며, DB 서버가 정상적으로 구동 중임을 확인할 수 있습니다.

 

이제 Docker 외부(DB 클라이언트 툴)에서 PostgreSQL 접속이 가능한지 확인해 봅니다.

 

---

6. 애플리케이션 전용 계정 생성(권장)

 

운영 환경에서는 기본 관리자 계정(admin)을 애플리케이션에서 직접 사용하는 것을 권장하지 않습니다.

따라서 애플리케이션 전용 계정을 생성하고 필요한 권한만 부여하는 방식이 바람직합니다.

 

ALTER USER admin12 WITH PASSWORD '패스워드';

GRANT CONNECT ON DATABASE postgres TO admin12;
GRANT USAGE ON SCHEMA public TO admin12;

GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO admin12;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO admin12;

 

👉 이 설정으로

• 외부 접속 가능
• public 스키마 사용 가능
• 테이블/시퀀스 접근 가능

한 애플리케이션 전용 DB 계정이 완성됩니다.

 

 

마지막으로 아래 명령어를 통해 PostgreSQL 접속 상태로 사용자 목록을 확인해서 생성한 계정과 권한이 정상적으로 표시되면 PostgreSQL Docker 환경 구성이 완료된 상태입니다.

\du

Docker Desktop

---

📝 마무리

이번 글에서는
Docker 환경에서 PostgreSQL 16을 실행하고,

• Docker Volume을 활용한 데이터 영구 저장
• 컨테이너 기반 DB 서버 구성
• 외부 접속 가능한 PostgreSQL 환경 설정

까지 한 번에 정리해 보았습니다.

Docker 기반 PostgreSQL은

• 빠른 환경 구성
• 동일한 설정 재현
• 테스트 / 개발 / 검증 환경 구축

에 매우 강력한 선택지입니다.

 

궁금한 점이나 추가적으로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요! 🙌😊