Встановлення та налаштування Alembic для роботи з SQLAlchemy

Уявіть, що ваш проєкт щойно почав розвиватися, і ви створили кілька моделей таблиць. Усе добре, код працює. Але раптом приходить бос (або клієнт, який грає роль боса) і пропонує додати новий стовпець у таблицю users для збереження їхніх улюблених фільмів. Ось тут усе стає цікавіше. Потрібно оновити структуру бази даних так, щоб не зіпсувати наявні дані, і зробити це так, щоб у боєвому середовищі (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 і налаштований проєкт. Ви готові до створення і керування міграціями, які допоможуть вам легко змінювати структуру бази даних вашого застосунку.