Інтеграція 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.