Установка и настройка Alembic для работы с SQLAlchemy

Представьте, что ваш проект только начал развиваться, и вы создали несколько моделей таблиц. Всё прекрасно, код работает. Но внезапно приходит босс (или клиент, который играет роль босса) и предлагает добавить новый столбец в таблицу пользователей для сохранения их любимых фильмов. Вот здесь всё становится интереснее. Вам нужно обновить структуру базы данных, чтобы не нарушить существующие данные, и сделать это так, чтобы в боевой среде (production) ничего не сломалось.

Alembic — это инструмент для управления такими изменениями. Это слово, которое программисты произносят с уважением. Задача Alembic — управлять миграциями базы данных, позволяя разработчикам:

• Создавать изменения в структуре базы данных (называемые миграциями) и применять их.
• Откатывать изменения в случае необходимости.
• Легко синхронизировать изменения между локальными и удалёнными базами данных.

Если SQLAlchemy — это мост между кодом и базой данных, то Alembic — это управляющий дорожным движением на этом мосту.

Установка Alembic

Первый шаг — это установка Alembic. Это делается, как всегда, с помощью pip:

pip install alembic

После установки убедитесь, что Alembic доступен в вашей системе. Для этого выполните команду:

alembic --help

Если вы видите список команд Alembic, значит, всё прошло успешно! Поздравляю, вы сделали первый шаг к управлению миграциями. (Или как мы, программисты, любим говорить: "Hello, world!" в мире Alembic.)

Настройка Alembic в проекте

Предположим, у вас есть проект на FastAPI, который использует SQLAlchemy. Давайте настроим Alembic.

Шаг 1: инициализация проекта Alembic

Чтобы подключить Alembic к вашему проекту, выполните команду:

alembic init alembic

Эта команда создаст новую директорию alembic в вашем проекте, а также файл alembic.ini.

• alembic.ini — основной конфигурационный файл Alembic. Здесь настраиваются параметры подключения к базе данных, пути к миграциям и другие настройки.
• alembic/env.py — файл, где происходит настройка взаимодействия Alembic с вашим проектом. Именно здесь вы связываете модели SQLAlchemy с Alembic.

Шаг 2: настройка alembic.ini

Откройте файл alembic.ini. Найдите строку, начинающуюся с sqlalchemy.url, и укажите строку подключения к вашей базе данных. Например, если вы используете PostgreSQL, это будет выглядеть так:

sqlalchemy.url = postgresql+psycopg2://username:password@localhost/dbname

Замените username, password и dbname на реальные значения, подходящие вашему проекту. Если у вас другой тип базы данных, вам нужно будет использовать правильный драйвер (например, sqlite:/// для SQLite или mysql+pymysql:// для MySQL).

Примечание: Если строка подключения к базе данных хранится в переменных окружения (что рекомендуется для безопасности), вы можете воспользоваться библиотекой os внутри env.py, чтобы считать значение из переменных.

Шаг 3: настройка env.py

Теперь откроем файл alembic/env.py. Этот файл необходимо настроить так, чтобы Alembic знал, какие именно модели данных использовать при генерации миграций. Найдите блок кода:

target_metadata = None

И измените его так, чтобы он указывал на объект MetaData из SQLAlchemy — тот самый объект, который вы импортировали или создали при настройке вашего проекта. Например:

from myproject.database import Base

# Указываем мета-данные для моделей
target_metadata = Base.metadata

Если вы используете FastAPI и SQLAlchemy, то у вас уже должен быть файл database.py (или что-то подобное), где вы определяете объект Base:

from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

Вот и всё. Теперь Alembic знает, где искать ваши модели данных.

Проверка настройки Alembic

После того как вы настроили alembic.ini и env.py, можно проверить, всё ли работает. Для этого выполните команду:

alembic current

Если всё настроено правильно, вы увидите сообщение с текущей версией базы данных. На данный момент это будет base, так как миграции ещё не созданы.

Теперь попробуем сделать что-то поинтереснее.

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

Давайте создадим первую "ревизию" (migration revision) в нашем проекте. Ревизии — это файлы, которые содержат инструкции Alembic для изменения структуры базы данных.

Создать ревизию можно с помощью команды:

alembic revision -m "Создание таблицы users"

• Флаг -m позволяет добавить описание миграции, например, "Создание таблицы users".
• После выполнения команды в папке alembic/versions создаётся файл ревизии.
• Его имя состоит из уникального идентификатора и вашего комментария.

Пример файла ревизии:

"""Создание таблицы users"""
revision = 'abcdef123456'
down_revision = None
branch_labels = None
depends_on = None

from alembic import op
import sqlalchemy as sa

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

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

Функции upgrade и downgrade описывают изменения в структуре базы данных. Функция upgrade применяется, если вы хотите внести изменения, а downgrade — если хотите откатить их.

Запустим миграцию, чтобы применить изменения к базе данных:

alembic upgrade head

Если всё прошло успешно, наша таблица users появилась в базе данных! Вы даже можете открыть вашу базу и проверить её с помощью SQL-команд.

Типичные ошибки и как их избежать

1. "Connection is None" при выполнении миграции.
   • Проверьте, указали ли вы строку подключения в alembic.ini или настроили её в env.py.
2. "Target metadata is None" при генерации миграции.
   • Убедитесь, что target_metadata в env.py правильно указывает на мета-данные ваших моделей.
3. "Cannot import module '...'"
   • Проверьте пути импорта в env.py. Возможно, Alembic не может найти ваши модели данных.

Теперь у вас есть работающий Alembic и настроенный проект. Вы готовы к созданию и управлению миграциями, которые помогут вам легко изменять структуру базы данных вашего приложения.