Интеграция Alembic с Django для работы с миграциями

Django обладает своим инструментом для миграций — встроенный механизм миграций "на борту" простой и мощный. Однако есть ситуации, когда стандартные миграции Django не подходят идеально:

• Гибридные проекты: Ваш проект использует SQLAlchemy для доступа к базе (по разным причинам, например, для работы с ранее созданной базой данных или для использования сложных функций SQLAlchemy).
• Гранулярный контроль над миграциями: Alembic предлагает более низкоуровневый подход к управлению схемами базы данных.
• Мультиплатформенные проекты: Использование Django ORM только для части проекта, в то время как остальные модули зависят от SQLAlchemy.

Если вы настроили Alembic в других проектах, основы остаются теми же: работа с alembic.ini, env.py и миграционными версиями. Основная сложность при интеграции с Django — это заставить Alembic работать вместе с Django ORM (или дополнительно к нему).

---

Настройка Alembic в проекте Django

Сначала убедитесь, что Alembic установлен в вашем проекте. Если нет, добавляем:

pip install alembic

И выполняем команду для создания структуры Alembic в вашем проекте:

alembic init alembic

Эта команда создаст каталог alembic с файлами alembic.ini, env.py и папкой для миграций.

Настройка alembic.ini

Обновим конфигурационный файл Alembic, чтобы указать подключение к базе данных. Django использует DATABASES в своих настройках (settings.py), так что мы можем передать путь к базе через переменную окружения. Пример настройки:

sqlalchemy.url = postgresql+psycopg2://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}

Это позволит вам использовать уже настроенные параметры подключения к базе данных. Убедитесь, что переменные окружения (DB_USER, DB_PASSWORD и т.д.) определены.

Настройка env.py

Самая сложная часть: в файле env.py нам нужно подключить SQLAlchemy так, чтобы он знал о моделях, управляемых Django ORM (или гибридными моделями). Пример кода:

from django.conf import settings
from sqlalchemy import engine_from_config, pool
from alembic import context
import os
import django

# Установка пути к проекту Django и импорт Django моделей
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'my_project.settings')
django.setup()

# Импортируем ваши SQLAlchemy модели
from my_project.my_app.models import Base  # Пример: импорт модели SQLAlchemy

config = context.config

# Настройка соединения с базой данных
def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=Base.metadata  # Используем метаданные SQLAlchemy
        )

        with context.begin_transaction():
            context.run_migrations()

Здесь мы используем Base.metadata для того, чтобы Alembic "видел" таблицы ваших моделей SQLAlchemy.

---

Совместное использование Alembic и Django migrations

Проблема двойного управления миграциями

Когда вы используете и встроенные миграции Django, и Alembic, важно избегать дублирования миграций. Например, одна и та же таблица может быть изменена одновременно средствами Django и Alembic, что может привести к хаосу.

Решение: для базы данных, где вы используете Alembic, отключите миграции Django. Это можно сделать, добавив следующие строки в файл settings.py:

MIGRATION_MODULES = {
    'your_app': None,  # Отключаем миграции для указанного приложения
}

Это скажет Django, что миграции для этого приложения не должны использоваться.

Как сочетать два инструмента?

Если есть необходимость использовать оба инструмента (например, для разных частей базы данных), придерживайтесь следующего подхода:

1. Используйте Django для управления схемами, завязанными на Django ORM.
2. Используйте Alembic для управления схемами, завязанными на SQLAlchemy.
3. Убедитесь, что они не перекрываются, иначе у вас могут начаться "весёлые" дни отладки.

---

Учет изменений в базе данных при использовании обеих систем

Теперь, когда Alembic настроен, создание новой миграции становится простым. Для отображения изменений выполните команду:

alembic revision --autogenerate -m "Your migration message"

Убедитесь, что Alembic "видит" ваши модели (через target_metadata в env.py). Затем примените миграцию, воспользовавшись:

alembic upgrade head

---

Пример использования Alembic в Django проекте

Представим, что у нас есть проект Django, который управляет базой данных через SQLAlchemy. Мы создадим новую таблицу с использованием SQLAlchemy и проведём миграцию через Alembic.

Создаём модель SQLAlchemy в models.py:

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, Integer, String

Base = declarative_base()

class Item(Base):
    __tablename__ = 'items'

    id = Column(Integer, primary_key=True)
    name = Column(String(100))

Генерируем миграцию:

alembic revision --autogenerate -m "Create items table"

Alembic обнаружит новую таблицу items и создаст файл миграции.

Применение миграции

Применяем миграцию:

alembic upgrade head

Теперь таблица items появилась в базе данных.

---

Особенности и типичные ошибки

Когда дело доходит до работы с Alembic и Django, главное — следить за порядком. Распространённая ошибка — попытка управлять одной и той же таблицей через две системы миграций одновременно. Это может привести к непредсказуемым последствиям, включая конфликты версий.

Ещё одна ошибка — забыть синхронизировать alembic.ini с настройками вашего settings.py. Если вы используете sqlite в разработке и PostgreSQL в продакшене, обязательно обновляйте параметры подключения к базе данных.

---

Теперь вы можете смело использовать Alembic в своих Django проектах и даже совмещать его с стандартными миграциями. Это позволит вам строить гибридные системы, которые извлекают лучшее как из Django, так и из SQLAlchemy.