Гайды

Alembic: миграции схемы базы данных

init и env.py, autogenerate и ручные ревизии, upgrade и downgrade, офлайн SQL и командная работа.

~9 мин чтения

Alembic: миграции схемы базы данных

Alembic — инструмент миграций схемы для SQLAlchemy. Хранит цепочку ревизий в виде Python-файлов и таблицы alembic_version. ORM-контекст — SQLAlchemy в Python; для Django миграции встроены в manage.py — первый проект Django.

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

bash

pip install alembic sqlalchemy psycopg[binary]
alembic init alembic

Появится каталог alembic/ и alembic.ini.

В alembic/env.py подключите Base.metadata ваших моделей и target_metadata = Base.metadata для autogenerate.

2. sqlalchemy.url

В alembic.ini можно задать URL или передавать через env:

bash

set DATABASE_URL=postgresql+psycopg://user:pass@localhost/db
alembic revision --autogenerate -m "add users table"

В env.py часто читают os.environ["DATABASE_URL"].

3. Ревизии

bash

alembic revision -m "manual tweak"        # пустой шаблон
alembic revision --autogenerate -m "..."  # сравнение с моделями

Проверяйте сгенерированный файл руками: autogenerate не видит переименований колонок (сделает drop+add).

4. Применение

bash

alembic upgrade head
alembic downgrade -1
alembic current
alembic history

В CI/CD — alembic upgrade head перед стартом приложения или как отдельный job.

5. Оффлайн SQL

bash

alembic upgrade head --sql

Полезно для DBA-ревью без применения.

6. Несколько баз / шардов

Отдельные ветки Alembic или именованные конфиги — продвинутая тема; начните с одной version_path.

7. Совместная работа

Конфликты merge в ревизиях: объединить down_revision в одну ветку (merge revision).
Не редактировать уже применённые на проде ревизии — только новые.

8. Онлайн-изменения в PostgreSQL

Крупные ADD INDEX CONCURRENTLY лучше выносить в отдельные ревизии без транзакции Alembic (transaction_per_migration=False в env.py для этой ревизии) — иначе блокировки. Проверяйте ACCESS EXCLUSIVE операции в проде по окну обслуживания.

9. Чек-лист

Autogenerate + ручной diff перед merge.
Бэкап перед миграцией на проде.
Тест upgrade → downgrade → upgrade на копии БД.
Таймауты и retry в CI job миграций.
Версия драйвера SQLAlchemy согласована с прод-образом приложения.

Дальше: SQLAlchemy · тег Alembic