Как происходит создание миграции в Alembic?

Создание миграций в Alembic

Alembic — это инструмент для управления версионированием схемы БД в SQLAlchemy приложениях. Процесс создания миграции включает несколько шагов.

Инициализация Alembic

Первый раз нужно инициализировать Alembic в проекте:

alembic init migrations

Это создаст папку migrations/ с конфигурацией и папкой versions/.

Конфигурация alembic.ini

В файле alembic.ini указывается строка подключения к БД:

sqlalchemy.url = postgresql://user:password@localhost/dbname

Лучше использовать переменные окружения:

sqlalchemy.url = driver://%(DB_USER)s:%(DB_PASSWORD)s@%(DB_HOST)s/%(DB_NAME)s

Создание автоматической миграции

Если у вас уже есть модели SQLAlchemy, Alembic может автоматически сгенерировать миграцию:

alembic revision --autogenerate -m "Add users table"

Это создаст файл в migrations/versions/ с автоматически сгенерированным кодом:

# migrations/versions/001_add_users_table.py
from alembic import op
import sqlalchemy as sa

revision = 1234567890ab
down_revision = None
branch_labels = None
depends_on = None

def upgrade() -> None:
    op.create_table(
        users,
        sa.Column(id, sa.Integer(), nullable=False),
        sa.Column(name, sa.String(255), nullable=False),
        sa.Column(email, sa.String(255), nullable=False),
        sa.PrimaryKeyConstraint(id)
    )

def downgrade() -> None:
    op.drop_table(users)

Создание ручной миграции

Можно создать пустую миграцию и написать SQL вручную:

alembic revision -m "Add email column to users"

Это создаст файл с пустыми функциями upgrade() и downgrade(), которые вы заполняете вручную:

def upgrade() -> None:
    op.add_column(users, sa.Column(email, sa.String(255), nullable=True))
    op.create_unique_constraint(uq_users_email, users, [email])

def downgrade() -> None:
    op.drop_constraint(uq_users_email, users, type_=unique)
    op.drop_column(users, email)

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

Для применения миграций используется команда upgrade:

# Применить все новые миграции
alembic upgrade head

# Применить одну миграцию
alembic upgrade +1

# Откатить все миграции
alembic downgrade base

# Откатить одну миграцию
alembic downgrade -1

Проверка статуса миграций

# Посмотреть текущую версию БД
alembic current

# Посмотреть историю миграций
alembic history

Лучшие практики

1. Одна миграция = одна логическая задача: добавление таблицы, изменение колонки, создание индекса
2. Всегда писать downgrade(): это необходимо для отката в production
3. Тестировать миграции: откатить и накатить обратно
4. Избегать несовместимых изменений: если возможно, добавляй колонки с nullable=True
5. Не редактировать уже применённые миграции: создавай новую

Типичный рабочий процесс

# 1. Изменяешь модели в коде
# 2. Генерируешь миграцию
alembic revision --autogenerate -m "Add new field"

# 3. Проверяешь сгенерированный код
cat migrations/versions/*.py

# 4. Применяешь
alembic upgrade head

# 5. Тестируешь
pytest

# 6. Коммитишь
git add alembic/
git commit -m "Add migration: new field"

Alembic упрощает управление схемой БД, позволяя легко отслеживать, применять и откатывать изменения в production среде.