5편: Django PostgreSQL 연결 방법｜Docker Compose 운영 DB 설정 가이드

5편 Django PostgreSQL 연결 방법｜Docker 환경에서 운영 DB 연동하기

이전 글에서 Docker를 설치하고 Docker Compose 배포를 통해서 Docker에서 Nginx + PostgreSQL + Django 서버 구동과 Django 프로젝트 생성부터 Production 설정을 통해서 웹페이지를 띄우는 것까지 진행했습니다.

본 편에서는 Django와 PostgreSQL을 연동해서 실제 Django 웹과 데이터베이스를 연결하고, SQL 기반 데이터 저장 구조를 사용하는 방법에 대해서 알아보겠습니다.

이번 편의 핵심

Django 프로젝트가 기본 SQLite가 아니라 Docker Compose 안에서 실행 중인 PostgreSQL 데이터베이스를 사용하도록 연결하는 것입니다.

왜 SQLite가 아니라 PostgreSQL을 사용할까?

Django 프로젝트를 처음 생성하면 기본 데이터베이스는 SQLite로 설정되어 있습니다. SQLite는 별도 서버 없이 간단하게 사용할 수 있어서 개발 초기에는 편리합니다.

하지만 실제 웹사이트를 운영하려면 PostgreSQL 같은 서버형 데이터베이스를 사용하는 것이 좋습니다.

운영 환경에서 안정적으로 사용 가능
여러 사용자가 동시에 접속하는 서비스에 적합
데이터 백업과 복구 관리가 용이
Django와 호환성이 좋음
Docker 환경에서 별도 DB 컨테이너로 분리 가능

쉽게 말하면

SQLite는 연습장에 가깝고, PostgreSQL은 실제 운영용 데이터 창고에 가깝습니다. 블로그, 회원가입, 게시글, 문의, 관리자 기능처럼 데이터가 계속 쌓이는 서비스라면 PostgreSQL을 사용하는 것이 좋습니다.

Docker Compose에서 PostgreSQL 구조 확인

Docker Compose를 사용하면 Django와 PostgreSQL을 각각 별도의 컨테이너로 실행할 수 있습니다.

services:
  web:
    build: .
    container_name: django_web
    command: gunicorn config.wsgi:application --bind 0.0.0.0:8000
    env_file:
      - .env
    depends_on:
      - db

  db:
    image: postgres:16
    container_name: django_db
    restart: always
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

여기서 중요한 부분은 db 서비스입니다. PostgreSQL 컨테이너가 실행되고, Django 컨테이너는 이 DB 컨테이너에 연결해서 데이터를 저장합니다.

volumes 설정이 중요한 이유

Docker 컨테이너는 삭제되거나 재생성될 수 있습니다. 만약 PostgreSQL 데이터를 컨테이너 내부에만 저장하면 컨테이너를 삭제했을 때 데이터가 함께 사라질 수 있습니다.

그래서 아래와 같이 volume을 설정합니다.

volumes:
  - postgres_data:/var/lib/postgresql/data

이 설정을 해두면 PostgreSQL 데이터가 Docker volume에 저장됩니다. 컨테이너를 다시 만들더라도 데이터가 유지됩니다.

주의

운영 중인 서비스에서 DB volume을 삭제하면 실제 데이터가 사라질 수 있습니다. docker compose down -v 명령어는 volume까지 삭제할 수 있으므로 운영 환경에서는 특히 조심해야 합니다.

Django에서 PostgreSQL을 사용하기 위한 패키지

Django에서 PostgreSQL을 사용하려면 PostgreSQL 드라이버가 필요합니다. 일반적으로 다음 패키지를 사용합니다.

pip install psycopg2-binary dj-database-url

운영 환경에서는 requirements.txt에 추가해두는 것이 좋습니다.

Django==5.2.0
gunicorn
psycopg2-binary
dj-database-url

.env 파일에 DATABASE_URL 설정하기

데이터베이스 접속 정보는 settings.py에 직접 작성하지 않고, 보통 .env 파일로 분리합니다.

DATABASE_URL=postgres://myuser:mypassword@db:5432/mydb

여기서 중요한 부분은 @db:5432입니다.

myuser : PostgreSQL 사용자명
mypassword : PostgreSQL 비밀번호
db : Docker Compose의 PostgreSQL 서비스 이름
5432 : PostgreSQL 기본 포트
mydb : 사용할 데이터베이스 이름

Docker Compose 환경에서 중요한 포인트

Django 컨테이너에서 PostgreSQL에 접속할 때는 localhost가 아니라 Compose 서비스 이름인 db를 사용해야 합니다.

settings.py에서 DATABASES 설정하기

이제 Django의 settings.py에서 데이터베이스 설정을 PostgreSQL로 변경합니다.

import os
import dj_database_url

DATABASES = {
    "default": dj_database_url.config(
        default=os.getenv("DATABASE_URL"),
        conn_max_age=600,
    )
}

이렇게 설정하면 Django는 .env에 있는 DATABASE_URL 값을 읽어서 PostgreSQL에 연결합니다.

기본 SQLite 설정과 비교

Django 기본 설정은 보통 아래와 같습니다.

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

이 설정은 SQLite를 사용하는 방식입니다. PostgreSQL을 사용하려면 위 설정을 dj_database_url 방식으로 변경하면 됩니다.

마이그레이션 실행하기

데이터베이스 연결이 끝났다면 Django 모델 정보를 실제 PostgreSQL 데이터베이스에 반영해야 합니다. 이 작업을 마이그레이션이라고 합니다.

docker compose exec web python manage.py makemigrations

docker compose exec web python manage.py migrate

makemigrations는 모델 변경 내용을 마이그레이션 파일로 만들고, migrate는 그 내용을 실제 데이터베이스에 반영합니다.

관리자 계정 생성하기

Django 관리자 페이지를 사용하려면 superuser 계정을 생성해야 합니다.

docker compose exec web python manage.py createsuperuser

관리자 계정을 생성한 뒤 아래 주소로 접속하면 Django 관리자 페이지를 확인할 수 있습니다.

https://도메인주소/admin/

PostgreSQL 연결 확인 방법

정상적으로 연결되었는지 확인하려면 다음 작업을 해볼 수 있습니다.

Django 관리자 페이지 접속
superuser 로그인 확인
게시글 또는 테스트 모델 데이터 생성
컨테이너 재시작 후 데이터 유지 여부 확인

docker compose restart

재시작 후에도 관리자 계정이나 저장한 데이터가 유지된다면 PostgreSQL volume 설정이 정상적으로 동작하고 있는 것입니다.

DB 컨테이너 로그 확인하기

PostgreSQL 컨테이너에 문제가 있는 경우 로그를 확인하면 원인을 찾을 수 있습니다.

docker compose logs db

Django 컨테이너 로그도 함께 확인할 수 있습니다.

docker compose logs web

자주 발생하는 오류

1. connection refused 오류

Django가 PostgreSQL에 연결하지 못할 때 발생합니다.

확인할 부분은 다음과 같습니다.

DB 컨테이너가 실행 중인지 확인
DATABASE_URL의 host가 db인지 확인
PostgreSQL 사용자명, 비밀번호, DB명이 Compose 설정과 같은지 확인

2. role does not exist 오류

PostgreSQL 사용자명이 잘못되었을 가능성이 있습니다. POSTGRES_USER와 DATABASE_URL의 사용자명이 같은지 확인해야 합니다.

3. database does not exist 오류

데이터베이스 이름이 일치하지 않을 때 발생할 수 있습니다. POSTGRES_DB와 DATABASE_URL 마지막 DB 이름을 확인해야 합니다.

4. migrate가 적용되지 않는 경우

마이그레이션 파일이 생성되지 않았거나, 다른 설정 파일을 보고 있을 수 있습니다.

docker compose exec web python manage.py showmigrations

위 명령어로 어떤 마이그레이션이 적용되었는지 확인할 수 있습니다.

운영 환경에서 조심해야 할 부분

개발 환경에서는 DB를 삭제하고 다시 만들 수 있지만, 운영 환경에서는 데이터가 실제 서비스의 핵심입니다.

운영 DB volume 삭제 금지
마이그레이션 전 백업 권장
.env 파일 외부 공개 금지
DB 비밀번호를 GitHub에 올리지 않기
운영 DB와 개발 DB 분리하기

운영 DB 관리 핵심 정리

Django 프로젝트에서 PostgreSQL 연결은 단순히 설정 한 줄을 바꾸는 작업이 아닙니다. 데이터가 어디에 저장되고, 어떻게 유지되며, 배포 후에도 안전하게 관리되는지를 함께 생각해야 합니다.

이번 편 정리

이번 글에서는 Docker Compose 환경에서 Django와 PostgreSQL을 연결하는 방법을 정리했습니다.

SQLite와 PostgreSQL의 차이
Docker Compose의 PostgreSQL 서비스 구조
DB volume 설정의 중요성
.env 기반 DATABASE_URL 설정
Django settings.py 데이터베이스 설정
마이그레이션 실행 방법
운영 환경에서 주의할 점

여기까지 진행하면 Django 프로젝트가 단순히 화면만 띄우는 상태를 넘어서, 실제 데이터를 저장하고 관리할 수 있는 구조가 됩니다.

다음 편 예고

다음 편에서는 Django에서 Models.py 설계 및 DB 구조 설계부터 마이그레이션까지 한번에 정리해보겠습니다.

이전 글