Відкат міграцій і керування версіями бази даних

Уяви, що ти впровадив важливі зміни в структуру бази даних, але щось пішло не так. Наприклад, забув врахувати важливу вимогу, або хтось на проєкті почав кричати: «Навіщо ви видалили потрібні стовпці?!» Для таких випадків потрібна можливість відкотити міграції.

Відкат міграцій в Alembic — це як кнопка ctrl + z у твоїй базі даних. Ти можеш повернутися в попередню «точку збереження» і почати з чистого аркуша (ну, майже).

---

Команда alembic downgrade

Щоб відкотити зміни, які були внесені останньою міграцією, використовується команда:

alembic downgrade -1

За допомогою прапорця -1 ми кажемо Alembic, що потрібно повернутися на одну версію назад. Таким чином буде виконано відкат змін, внесених останньою міграцією.

Приклад: Припустимо, ти додав новий стовпець age в таблицю users, але усвідомив, що це була помилка. Твоя остання міграція була створена для додавання цього стовпця. Після команди downgrade, стовпець буде видалений зі структури таблиці.

Кожна міграція в Alembic складається з двох блоків: upgrade (для внесення змін) і downgrade (для відкату цих змін).

Ось приклад:

def upgrade():
    # додаємо новий стовпець age
    op.add_column('users', sa.Column('age', sa.Integer(), nullable=True))

def downgrade():
    # прибираємо стовпець age
    op.drop_column('users', 'age')

Коли ти викликаєш команду downgrade, Alembic виконує інструкцію з функції downgrade.

Відкат до певної версії

Іноді може знадобитися відкотитися не просто на одну версію, а відразу до якоїсь конкретної точки в минулому. Для цього використовується ідентифікатор версії міграції (він знаходиться у файлі міграції, приблизно так: dd8e8f7d9b46).

Команда для відкату до певної версії:

alembic downgrade dd8e8f7d9b46

Порада: щоб побачити список всіх міграцій і їх ідентифікаторів, використовуй команду:

alembic history

Це покаже тобі «хронологію» всіх міграцій, їх ідентифікатори і опис (якщо він був вказаний).

---

Керування версіями бази даних

Alembic зберігає інформацію про поточну версію бази даних у спеціальній таблиці alembic_version. Ця таблиця створюється автоматично при виконанні першої міграції і оновлюється при кожному застосуванні (або відкаті) міграцій.

Ти можеш перевірити поточну версію бази даних за допомогою команди:

alembic current

Ця команда покаже ідентифікатор поточної версії бази даних (наприклад, dd8e8f7d9b46).

Якщо потрібно оновити базу даних до останньої версії міграції, використовується команда:

alembic upgrade head

Тут head вказує, що ти хочеш оновитися до найостаннішої міграції.

Як Alembic відслідковує версії?

Кожна міграція має унікальний ідентифікатор (ревізію). Ці ідентифікатори пов'язані між собою лінійно (або у вигляді дерева, якщо ти використовуєш ветвлення міграцій).

Приклад структури версій:

base -> migration_001 -> migration_002 -> migration_003 (current)

Якщо ти додаєш нову міграцію, вона стає «головою» (head):

base -> migration_001 -> migration_002 -> migration_003 -> migration_004 (head)

Конфлікти версій

Конфлікт версій може статися, якщо два розробники вносять зміни в одну й ту ж базу даних одночасно, а потім зливають свої гілки. Це призведе до появи двох «голов» (heads).

Щоб побачити поточні heads міграцій, використовуй:

alembic heads

Якщо у тебе більше однієї голови, значення можна виправити злиттям міграцій.

Злиття міграцій

Для об'єднання міграцій використовується команда:

alembic merge <revision_1> <revision_2>

Ця команда створює нову міграцію, яка об'єднує зміни з вказаних ревізій. Після злиття у тебе буде лише одна «голова».

---

Типові помилки при роботі з відкатом міграцій

1. Відсутність функції downgrade у міграції. Alembic не зможе виконати відкат, якщо у твоїй міграції відсутнє визначення функції downgrade. Завжди перевіряй, щоб функція була, особливо якщо ти використовуєш автогенерацію.
2. Зміни даних замість структури. Відкат міграції не відкотить зміни в даних! Наприклад, якщо ти додав рядок в таблицю у міграції, відкат не видалить цей рядок.
3. Неправильно налаштоване оточення. Якщо ти намагаєшся відкотити міграцію, але Alembic не може знайти конфігурацію бази даних (наприклад, через неправильний файл alembic.ini), переконайся, що налаштування з'єднання з базою даних вказані коректно.
4. Конфлікти версій. При виникненні конфлікту версій завжди об'єднуй міграції за допомогою команди merge.

---

Практичний приклад

Давай розберемо на реальному прикладі, як виконувати відкати міграцій і керувати версіями.

Крок 1: перевіримо поточну версію

alembic current

Крок 2: відкотимося на одну версію назад

alembic downgrade -1

Перевіряємо, що зміни відкотилися, наприклад, стовпець зник з таблиці.

Крок 3: відкат до базової версії

alembic downgrade base

Цей крок поверне базу даних до стану до виконання першої міграції.

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

alembic upgrade head

Тепер наша база даних знову на останній версії.

---

Реальне застосування навичок

Подібні операції корисні в реальному житті для відновлення бази даних після помилок або тестування змін. Наприклад, у процесі розробки ти можеш відкотити базу даних до попередньої версії, щоб перевірити, як додаток працює зі застарілою структурою даних.

На співбесіді в тебе можуть запитати: «Що робити, якщо остання міграція поламала базу даних?» Тепер ти впевнено зможеш відповісти: «Звісно, використовувати відкат за допомогою Alembic!»

Для великих командних проєктів, керування версіями з синхронізацією міграцій через Git робить роботу з базою даних прозорою й організованою. А автоматизація цих операцій через CI/CD (наприклад, в GitHub Actions) повністю позбавить тебе головного болю на етапі розгортання.