Створення першої міграції в проєкті FastAPI

У цій лекції ми познайомимось із процесом створення першої міграції в проєкті на FastAPI, використовуючи Alembic. Розберемо базові команди для роботи з міграціями — від створення порожнього шаблону до автоматичної генерації міграції на основі змін у моделях даних. Трохи попрактикуємось, щоб процес міграцій став для нас зрозумілим і, головне, ненапружним. Готові? Поїхали!

Спершу давай пригадаємо, навіщо нам ці міграції. Коли ти працюєш над проєктом, структура бази даних постійно змінюється. Додали нові поля, видалили старі таблиці, помінили типи даних — все це потребує внесення змін безпосередньо в базу. Робити такі зміни вручну — як писати код без Ctrl+Z: нерозумно і ризиковано. Міграції дозволяють описати ці зміни у вигляді послідовності кроків, які можна застосовувати, відкотити і переносити між оточеннями (наприклад, з dev на production).

Alembic приходить на допомогу

Alembic бере на себе управління цими змінами. Він допомагає:

1. Створювати нові міграції.
2. Застосовувати зміни до бази даних.
3. Відкатувати зміни, якщо раптом щось пішло не так (зазвичай це фраза з документації, але давай прикинемо, що такого ніколи не трапляється 🤞).

---

План створення першої міграції

1. Створити й ініціалізувати робочу директорію Alembic.
2. Налаштувати Alembic для взаємодії з базою даних і моделями SQLAlchemy.
3. Створити першу міграцію вручну.
4. Автоматично згенерувати міграцію на основі змін у моделях.

---

Крок 1: ініціалізація Alembic

Почнемо з підготовки проєкту. Припускаємо, що в тебе вже є робочий FastAPI-проєкт з підключенням до бази через SQLAlchemy.

Якщо Alembic ще не встановлений, саме час це зробити. Одна команда — і ти готовий до міграцій:

pip install alembic

Перевір, чи встановлений Alembic, виконавши:

alembic --version

Тепер спробуємо ініціалізувати Alembic у нашому проєкті. Команда нижче створить директорію alembic, де зберігатимуться всі міграції й налаштування:

alembic init alembic

Після виконання цієї команди ти побачиш нову структуру файлів:

project/
 ├── alembic/
 │    ├── env.py
 │    ├── versions/
 ├── alembic.ini

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

---

Крок 2: Налаштування Alembic

Тепер скажемо Alembic, як йому підключатися до бази даних. Для цього відкрий файл alembic.ini і вкажи рядок підключення. Знайди рядок з sqlalchemy.url:

sqlalchemy.url = sqlite:///./test.db

Якщо ти, як справжній прихильник мінімалізму, використовуєш SQLite, рядок вище підійде. Якщо твій проєкт працює з PostgreSQL, зміни його на щось типу:

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

Тепер перейдемо до налаштувань env.py. Цей файл відповідає за те, як Alembic інтегрується з нашими моделями SQLAlchemy. Потрібно вказати модуль, де лежать моделі, і налаштувати підключення.

Знайди функцію run_migrations_online() і виправ частину з connectable на такий код:

from app.database import engine  # Імпортуємо наш SQLAlchemy engine

connectable = engine  # Передаємо engine Alembic для підключення до бази

Також обов'язково переконайся, що моделі підключені:

from app.models import Base
target_metadata = Base.metadata  # Передаємо метадані моделей Alembic

---

Крок 3: створення порожньої міграції

Спробуємо створити нашу першу простеньку міграцію. Для початку скористаємося такою командою:

alembic revision -m "Створення початкової структури"

Ця команда створить файл у директорії versions/:

alembic/versions/
 └── <ідентифікатор_ревізії>_створення_початкової_структури.py

Міграція поки що буде порожньою, але в реальному проєкті ти можеш вручну додати код для створення таблиць.

Приклад вмісту файлу міграції:

def upgrade():
    # Тут можна писати інструкції для оновлення схеми
    pass

def downgrade():
    # Тут пишемо інструкції для відкату змін
    pass

---

Крок 4: генерація міграції на основі змін

Один із найзручніших аспектів Alembic — здатність самостійно генерувати код міграцій на підставі змін у твоїх моделях даних. Час автоматизувати процес!

Припустимо, у нас є модель User:

from sqlalchemy import Column, Integer, String
from app.database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    email = Column(String, index=True, unique=True)

Тепер ми хочемо створити міграцію, що описує структуру таблиці users. Запустимо:

alembic revision --autogenerate -m "Створення таблиці users"

Alembic загляне в твої моделі і згенерує міграцію, яка виглядатиме приблизно так:

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

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

---

Крок 5: застосування міграції

Після створення міграції час застосувати зміни до бази даних. Це можна зробити командою:

alembic upgrade head

head означає, що Alembic застосує всі ревізії до останньої. Після виконання команди в базі даних з'явиться нова таблиця users.

---

На що звернути увагу?

Іноді Alembic не може правильно визначити зміни в моделі — наприклад, якщо ти додав складний тип даних або змінив поведінку стовпця. У таких випадках варто вручну переглянути згенерований файл міграції.

---

Тепер у тебе є базові знання про те, як створити першу міграцію в FastAPI за допомогою Alembic. Попереду ще багато цікавого, включно зі змінами існуючих структур бази даних і відкатами змін. Отже, запасайся кавою і продовжуємо рости як розробники!