PostgreSQL и Django в Docker: Полное руководство по настройке и подключению

Современная веб-разработка всё чаще использует контейнеризацию для создания воспроизводимых и изолированных сред. Docker Compose становится стандартом для оркестрации многоконтейнерных приложений, а связка Django с PostgreSQL в контейнерах — мощный дуэт для production-ready проектов. В этом руководстве мы разберём каждый шаг подключения PostgreSQL к Django через docker-compose, от базовой настройки до продвинутых практик.

Почему именно Docker Compose для Django и PostgreSQL?

Docker Compose позволяет описать всю инфраструктуру вашего приложения в одном файле — базу данных, веб-сервер, кэш и другие сервисы. Это даёт несколько ключевых преимуществ:

• Воспроизводимость окружения: одинаковое окружение на всех машинах — от разработки до продакшена
• Простота развёртывания: одна команда для запуска всей системы
• Изоляция зависимостей: PostgreSQL работает в своём контейнере с нужной версией
• Масштабируемость: лёгкое добавление новых сервисов

Структура проекта и базовый docker-compose.yml

Начнём с создания типичной структуры проекта Django в Docker-окружении:

Основной docker-compose.yml

Создайте файл docker-compose.yml со следующим содержимым:

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    environment:
      - POSTGRES_DB=${DB_NAME}
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
    environment:
      - DB_HOST=db
      - DB_NAME=${DB_NAME}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}

volumes:
  postgres_data:

Настройка Django для работы с PostgreSQL

Конфигурация settings.py

В файле settings.py вашего Django-проекта настройте подключение к базе данных:

import os

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST', 'db'),
        'PORT': '5432',
    }
}

Создание .env файла

Создайте файл .env в корне проекта (добавьте его в .gitignore!):

DB_NAME=mydatabase
DB_USER=myuser
DB_PASSWORD=mysecurepassword123
DB_HOST=db

Dockerfile для Django-приложения

Создайте Dockerfile для вашего Django-приложения:

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

RUN pip install --upgrade pip
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

Работа с миграциями и статикой

Автоматизация миграций

Добавьте в docker-compose.yml специальный сервис для выполнения миграций:

  migrations:
    build: .
    command: python manage.py migrate
    depends_on:
      db:
        condition: service_healthy
    environment:
      - DB_HOST=db
      - DB_NAME=${DB_NAME}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
    volumes:
      - .:/app

Сборка статики

Для production можно добавить отдельный сервис для сбора статики или использовать volume для её хранения.

Запуск и управление

1. Сборка и запуск: docker-compose up --build
2. Запуск в фоне: docker-compose up -d
3. Остановка: docker-compose down
4. Просмотр логов: docker-compose logs -f web
5. Выполнение команд в контейнере: docker-compose exec web python manage.py createsuperuser

Продвинутые настройки

Настройка pgAdmin для управления БД

Добавьте в docker-compose.yml сервис pgAdmin:

  pgadmin:
    image: dpage/pgadmin4
    environment:
      - PGADMIN_DEFAULT_EMAIL=admin@admin.com
      - PGADMIN_DEFAULT_PASSWORD=admin
    ports:
      - "5050:80"
    depends_on:
      - db

Бэкапы и восстановление

Создайте скрипт для автоматического бэкапа базы данных:

docker-compose exec db pg_dump -U myuser mydatabase > backup.sql

FAQ — Часто задаваемые вопросы

Как подключиться к PostgreSQL извне Docker?

Используйте localhost:5432 с теми же credentials, что указаны в .env файле. Убедитесь, что в PostgreSQL конфигурации разрешены внешние подключения.

Почему Django не видит базу данных при запуске?

Частая проблема — timing issue. Убедитесь, что используете healthcheck для базы данных и depends_on с condition: service_healthy. PostgreSQL должен быть полностью готов перед запуском Django.

Как сохранить данные между перезапусками контейнеров?

Используйте volumes, как показано в примере (postgres_data). Это гарантирует сохранность данных даже при удалении контейнера.

Как обновить requirements.txt без пересборки всего образа?

Используйте кэширование зависимостей: разделите установку зависимостей и копирование кода в Dockerfile, чтобы изменения в requirements.txt не вызывали переустановку всех пакетов.

Как настроить разные конфигурации для development и production?

Используйте несколько файлов docker-compose: docker-compose.yml для базовой конфигурации и docker-compose.prod.yml для продакшена с переопределениями.

Какой пароль PostgreSQL использовать в production?

Используйте длинные случайные пароли, генерируемые системой. Никогда не используйте дефолтные или простые пароли. Храните их в защищённых системах управления секретами.