Alembic: миграции БД

Alembic — инструмент для управления миграциями SQLAlchemy/SQLModel.

Установка

pip install alembic

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

alembic init alembic

Создаёт:

alembic/
├── env.py
├── script.py.mako
└── versions/
alembic.ini

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

sqlalchemy.url = postgresql://user:pass@localhost/mydb
# Или через переменную окружения — лучше настроить в env.py

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

# alembic/env.py
from sqlmodel import SQLModel
from myapp.models import *  # импорт всех моделей
from myapp.database import DATABASE_URL

config.set_main_option("sqlalchemy.url", DATABASE_URL)

target_metadata = SQLModel.metadata

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

# Автоматически из изменений в моделях
alembic revision --autogenerate -m "add task table"

# Пустая миграция (писать вручную)
alembic revision -m "custom migration"

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

alembic upgrade head          # применить все
alembic upgrade +1            # следующая миграция
alembic downgrade -1          # откат на одну
alembic downgrade base        # откат до начала

Пример файла миграции

# alembic/versions/0001_add_task_table.py
from alembic import op
import sqlalchemy as sa

def upgrade():
    op.create_table(
        'task',
        sa.Column('id', sa.Integer, primary_key=True),
        sa.Column('title', sa.String(200), nullable=False),
        sa.Column('status', sa.String(20), default='todo'),
        sa.Column('created_at', sa.DateTime),
    )

def downgrade():
    op.drop_table('task')

Статус миграций

alembic current               # текущая версия
alembic history               # история
alembic history --verbose     # подробно

В Docker/CI

# Применить перед стартом приложения
alembic upgrade head && uvicorn main:app --host 0.0.0.0 --port 8000