Войти или Регистрация
питон либ луна питонлиб солнце pythonlib цветок

Изменить тему

Alembic – миграции базы данных

онлайн тренер по питону
Онлайн-тренажер Python 3 для начинающих

Теория без воды. Задачи с автоматической проверкой. Подсказки на русском языке. Работает в любом современном браузере.

начать бесплатно

Введение

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

Alembic — это официальный инструмент миграций для SQLAlchemy, поддерживающий как синхронные, так и асинхронные проекты, включая FastAPI, Flask и другие фреймворки.

Установка и инициализация Alembic

Установка:

bash
pip install alembic

Инициализация проекта миграций:

bash
alembic init alembic

Будет создана папка alembic/ с файлами и alembic.ini.

Базовые команды Alembic

  • alembic revision -m "описание" — создание новой ревизии вручную

  • alembic revision --autogenerate -m "описание" — генерация на основе моделей

  • alembic upgrade head — применить все миграции

  • alembic downgrade -1 — откатить последнюю миграцию

  • alembic history — история ревизий

Интеграция с SQLAlchemy

В alembic/env.py необходимо указать путь к Base, где определены модели:

python
from myproject.models import Base target_metadata = Base.metadata

Также указывается URL подключения:

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

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

Ручная миграция

bash
alembic revision -m "create users table"

Затем редактируем файл миграции:

python
def upgrade(): op.create_table( 'users', sa.Column('id', sa.Integer, primary_key=True), sa.Column('name', sa.String, nullable=False) )

Автоматическая генерация

bash
alembic revision --autogenerate -m "add email column"

Alembic сравнивает Base.metadata с текущим состоянием базы.

Откат миграций и история изменений

  • alembic downgrade -1 — откатить последнюю миграцию

  • alembic downgrade base — откатить всё

  • alembic show <revision_id> — показать SQL изменений

  • alembic current — текущая ревизия базы

Работа с несколькими базами данных

В env.py можно настроить выбор базы по параметрам:

python
config.get_main_option("sqlalchemy.url")

Или использовать переменные окружения.

Alembic в асинхронных проектах

С SQLAlchemy 2.0 поддержка async стала официальной:

python
from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("postgresql+asyncpg://...")

В env.py необходимо использовать async-версию функций run_migrations_online() и подключения к базе.

Миграции и тестирование

  • Создание временной базы для тестов

  • Проверка корректности миграций через alembic upgrade head

  • Использование pytest и фикстур с rollback

CI/CD и Alembic

GitHub Actions

yaml
- name: Run Alembic migrations run: alembic upgrade head

Можно использовать на этапе деплоя или перед запуском тестов.

GitLab CI

Добавьте шаг в .gitlab-ci.yml:

yaml
migrate: script: - alembic upgrade head

Советы по структуре и best practices

  • Давайте понятные имена миграциям

  • Одна миграция — одно логическое изменение

  • Проверяйте SQL, особенно при autogenerate

  • Комментируйте изменения в файлах ревизий

  • Не удаляйте миграции, даже если они "устарели"

Сравнение с другими инструментами миграции

Инструмент Язык Поддержка ORM Авто-генерация Подходит для
Alembic Python SQLAlchemy Да Flask, FastAPI, SQLAlchemy
Django Migrations Python Django ORM Да Только Django
Flyway SQL Нет Нет Java-проекты, CLI
Liquibase XML/SQL Нет Нет Enterprise-решения

Часто задаваемые вопросы (FAQ)

1. Что такое Alembic?
Это инструмент миграций базы данных для SQLAlchemy.

2. Поддерживает ли Alembic асинхронность?
Да, с SQLAlchemy 1.4+ и 2.0 поддерживается async engine.

3. Нужно ли писать SQL вручную?
Не обязательно, есть поддержка --autogenerate.

4. Как откатить только одну миграцию?
С помощью alembic downgrade -1.

5. Можно ли использовать Alembic без SQLAlchemy ORM?
Да, но тогда нужно писать миграции вручную.

6. Где хранится история миграций?
В таблице alembic_version в базе данных.

Полный справочник по ключевым функциям и модулям библиотеки Alembic для Python

Установка

bash
pip install alembic

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

Команда Описание
alembic init alembic Создает структуру проекта Alembic.
alembic.ini Конфигурационный файл (подключение к БД и параметры миграций).
bash
alembic init alembic

Настройка подключения к БД

В файле alembic.ini:

ini
sqlalchemy.url = sqlite:///./example.db

Или задать программно в env.py:

python
from models import Base # ваши ORM-модели target_metadata = Base.metadata

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

Команда Описание
alembic revision -m "msg" Создает пустую миграцию.
alembic revision --autogenerate -m "msg" Создает миграцию на основе изменений моделей.
bash
alembic revision --autogenerate -m "создание таблицы users"

Применение и откат миграций

Команда Описание
alembic upgrade head Применяет все миграции до последней.
alembic downgrade -1 Откатывает последнюю миграцию.
alembic downgrade base Откат до начального состояния.

Работа с версиями

Команда Описание
alembic current Показывает текущую версию схемы.
alembic history Список всех миграций.
alembic heads Все активные точки миграций.
alembic show <revision> Показывает содержание миграции.

Структура файла миграции

python
def upgrade(): op.create_table( 'users', sa.Column('id', sa.Integer, primary_key=True), sa.Column('name', sa.String(50)) ) def downgrade(): op.drop_table('users')

Основные операции (через op)

Метод Описание
op.create_table(...) Создание таблицы.
op.drop_table(name) Удаление таблицы.
op.add_column(table, column) Добавление столбца.
op.drop_column(table, column) Удаление столбца.
op.alter_column(...) Изменение типа/атрибутов столбца.
op.create_index(...) Создание индекса.
op.drop_index(...) Удаление индекса.
op.execute("SQL") Выполнение произвольного SQL.

Автогенерация: ограничения и рекомендации

Особенности Описание
Требует target_metadata Установить в env.py через ваши модели.
Не отслеживает изменения данных Только структура таблиц.
Иногда требует ручной правки Проверьте миграции после генерации.

Пример настройки для SQLAlchemy + Alembic

python
# models.py from sqlalchemy import Column, Integer, String from sqlalchemy.orm import declarative_base Base = declarative_base() class User(Base): __tablename__ = "users" id = Column(Integer, primary_key=True) name = Column(String)
python
# alembic/env.py from models import Base target_metadata = Base.metadata

Использование с FastAPI

  1. Создайте SQLAlchemy-движок в db.py.

  2. Подключите Base.metadata в env.py.

  3. Используйте alembic upgrade head при запуске.

Работа в CI/CD

Практика Рекомендация
Храните миграции в Git Как часть кода.
Автоматически выполняйте upgrade head при деплое Через alembic upgrade head.
Используйте --sql для dry-run Не выполняет миграции, а выводит SQL.
bash
alembic upgrade head --sql > deploy.sql

Интеграция с другими библиотеками

Библиотека Применение
SQLAlchemy Основная зависимость.
FastAPI / Flask Используется через SQLAlchemy.
async SQLAlchemy Неофициальная поддержка через сторонние решения (например, alembic[asyncio]).
Pydantic Для сериализации моделей (отдельно от миграций).

Заключение

Alembic – миграции базы данных — это надёжный и гибкий инструмент для управления схемой базы. Он упрощает работу разработчиков, помогает поддерживать единое состояние базы данных между окружениями и обеспечивает безопасность при изменениях. Благодаря поддержке как синхронных, так и асинхронных приложений, Alembic стал стандартом де-факто для проектов на SQLAlchemy.

войти или зарегистрироваться

Мы в соцсетях