Перевірка міграцій БД «up → down без слідів» у CI: пакети Migration Checker для Symfony та Laravel

💡 Усі статті, обговорення, новини про DevOps — в одному місці. Приєднуйтесь до DevOps спільноти!

Вітаю! Мене звати Олександр Рослов. Я програміст із 12-річним досвідом техлід-позицій. Регулярно працюю з PHP-проєктами, де міграції є щоденною реальністю: десятки змін схеми, review в PR, CI, деплої, інколи — термінові rollback’и.

Про що і для кого стаття

У цій статті я коротко розповідаю:

• яку проблему міграцій я закриваю і чому вона часто «не болить», доки не стане пізно;
• як працює підхід «up → down → schema diff» як автоматична перевірка якості;
• що саме роблять мої пакети Migration Checker для Symfony та Laravel і як їх запускати локально та в CI;
• які типові фейли проходять код-рев’ю, і як їх ловить автоматична перевірка.

Чому вирішив написати? Бо бачу, що тема «міграції як артефакт, який треба тестувати» досі недооцінена: часто ми рев’юємо міграції очима, але не маємо механічної гарантії, що відкат поверне схему в нульовий стан. А саме це відрізняє «міграції працюють» від «міграції безпечні».

Стаття буде корисна:

• PHP-розробникам на Symfony/Laravel, які регулярно додають міграції;
• тим, хто займається код-рев’ю і хоче менше «людського фактора»;
• DevOps/Tech Lead’ам, які відповідають за стабільні деплої та rollback;
• командам з raw SQL у міграціях (тригери, індекси, constraints), де ризики вищі.

У більшості команд міграції сприймаються як «код, що еволюціонує схему». Але з практики проблема часто не в up, а в тому, що down не повертає базу в початковий стан: лишаються таблиці, індекси, тригери, «тимчасові» колонки, зміни default-значень, коментарі або інші артефакти. Це може довго не проявлятися — аж поки не знадобиться rollback, відкат релізу або прогін міграцій у чистому середовищі.

Саме через це я зробив набір пакетів Migration Checker, який формалізує просте правило: після up → down стан схеми має бути ідентичним, і це має перевірятися автоматично (локально та в CI).

Чому я взагалі до цього дійшов

Класичний біль міграцій виглядає так:

• up() додає колонку/індекс/constraint/тригер, а down() забуває його прибрати.
• down() «відкотив» таблицю, але лишились супутні об’єкти або зміни метаданих.
• У CI ми проганяємо міграції «тільки вгору», але не перевіряємо, що rollback реально повертає схему назад.

І тут вступає в гру код-рев’ю. Бо реальність така: навіть сильні рев’ювери не тримають у голові всі нюанси БД, і в PR легко пропустити дрібні, але критичні деталі.

Приклади з код-рев’ю: що найчастіше прослизає

Нижче — типові ситуації, які я бачу на рев’ю міграцій (і через які, власне, й народився Migration Checker).

1) «Колонку видалили — значить все ок»... але індекс лишився

На рев’ю зазвичай дивляться на головну дію: «додали колонку — прибрали колонку». Але індекс міг створюватися:

• окремою командою;
• у сирому SQL;
• або автоматично через ORM-хелпер.

В результаті down() колонку прибрав, а індекс — ні. І поки ніхто не робить rollback — все тихо.

Як це виглядає в рев’ю:

«Так, dropColumn() є. LGTM».

Як це виглядає при реальному відкаті:

«Relation already exists / index already exists / cannot drop column because...»

2) «Додали FK» — але відкат не симетричний

У up() легко додати foreign key, але в down():

• забути dropForeign;
• переплутати ім’я constraint’а;
• або відкотити таблицю, залишивши constraint (залежить від СУБД і сценарію).

На рев’ю часто не ловиться, бо назви constraint’ів в різних командах можуть генеритись по-різному, а людина не завжди запускає міграцію локально «вгору-вниз».

3) «Тригер/функція» через raw SQL — і down() пустий

Все, що виходить за межі стандартного DSL міграцій, на рев’ю стає ризикованим:

• CREATE TRIGGER,
• CREATE FUNCTION,
• специфічні типи (наприклад, enum/типи в Postgres).

Часто down() або взагалі пропускають, або пишуть «потім доробимо».

На рев’ю це виглядає як:

«Так, воно треба для бізнес-логіки, давайте мерджити, rollback не плануємо».

А потім rollback «раптом» планується.

4) «Rename» — один з найпідступніших сценаріїв

Перейменування таблиці/колонки вгору може бути коректним, але відкат:

• повертає ім’я, але забуває про індекси;
• або індекси повертаються з іншими назвами;
• або ORM генерує різні імена залежно від версії.

Це складно виявити очима в PR, бо треба «симулювати» кінцеву схему.

5) «Змінили default / nullability / charset / collation» — а назад не повернули

Міграція може міняти:

• DEFAULT;
• NOT NULL;
• charset/collation;
• коментарі;
• порядок колонок (інколи важливо);
• типи (наприклад, int → bigint).

На рев’ю такі правки виглядають дрібними, але down() часто роблять «спрощеним»: повернули тип — і забули default/collation.

6) «Дропнули таблицю в down()» як універсальний відкат

Це взагалі окремий жанр:

• up() додає кілька змін;
• down() просто dropTable() «щоб гарантовано відкотити».

Таке часто проходить рев’ю, бо «працює». Але воно несиметричне і може:

• знести таблицю, яка існувала до міграції (якщо помилились контекстом);
• або знищити дані в dev/stage, де відкат роблять частіше.

Як працює Migration Checker

Алгоритм простий:

1. snapshot-схеми;
2. up;
3. down;
4. snapshot-схеми;
5. diff;
6. up і далі по списку.

Якщо після rollback лишився хоч один об’єкт — інструмент показує різницю і падає.

Як це допомагає саме в процесі код-рев’ю

Я сприймаю Migration Checker як «другу пару очей», яка:

• не втомлюється;
• не пропускає дрібниці;
• не покладається на «я впевнений, що down ок»;
• економить час код-рев’ю.

І практично це змінює рев’ю так:

• Рев’ювер більше фокусується на сенсі міграції (чи правильно ми міняємо домен), а не на «чи всі дрібні об’єкти видалені».
• Якщо в PR є raw SQL — checker стає обов’язковою страховкою.
• Зникає клас «LGTM, але down потім» — бо CI просто не пропустить.

Встановлення та локальний запуск

Symfony

composer require --dev roslov/migration-checker-bundle
php bin/console migration-checker:check --env=test -vv

Laravel

composer require --dev roslov/laravel-migration-checker
php artisan migration-checker:check --env=testing -vv

Підключення до CI

Нижче наведу приклад перевірки міграцій на Jenkins’і:

// Підготовлюємо тестове середовище
sh """
    docker stop ${service}-test-db || true
    docker rm --force ${service}-test-db || true
    docker network rm ${service}-network || true
    docker network create ${service}-network
"""
// Запускаємо тестову базу
sh """
    docker run --name ${service}-test-db --network=${service}-network -d --rm \
        -e MYSQL_ROOT_PASSWORD=rootpass \
        -e MYSQL_DATABASE=${service}_test \
        -e MYSQL_USER=${service}testuser \
        -e MYSQL_PASSWORD=${service}testpass \
        mysql:8.4.5 \
            --character-set-server=utf8mb4 \
            --collation-server=utf8mb4_0900_ai_ci \
            --log_bin_trust_function_creators=1 \
            --explicit_defaults_for_timestamp=0
"""
// Очікуємо, доки база буде готова приймати запити
sh """
    while ! docker exec ${service}-test-db \
        mysql --user=${service}testuser --password=${service}testpass \
        -e 'SELECT 1' \
        >/dev/null 2>&1; do
        echo 'Waiting for database connection...'
        sleep 1
    done
"""
if (service == 'service1') {
    // Запускаємо перевірку міграцій для сервіса `service1`.
    // В цьому випадку це Symfony-мікросервіс, в якому ми прописали підключення до тестової бази
    // в файлі `.env.test`
    sh """
        docker run --network=${service}-network --rm \
            ${service}-migration-check \
            php bin/console migration-checker:check --env=test -vv
    """
}
if (service == 'service2') {
    // Запускаємо перевірку міграцій для сервіса `service2`.
    // В цьому випадку це Laravel-мікросервіс, в якому ми НЕ прописали підключення до тестової бази
    // в файлі `.env.testing`, тому використовуємо змінну середовища для підключення
    sh """
        docker run --network=${service}-network --rm \
            -e DB_URL="mysql://${service}testuser:${service}testpass@${service}-test-db:3306/${service}_test
?serverVersion=8.4.5&charset=utf8mb4" \
            ${service}-migration-check \
            php artisan migration-checker:check --env=testing -vv
    """
}
// Зупиняємо тестове середовище
sh """
    docker stop ${service}-test-db
    docker network rm ${service}-network
"""

Де подивитися й спробувати

• roslov/migration-checker-bundle — додає консольну команду для перевірки міграцій в Symfony.
• roslov/laravel-migration-checker — додає консольну команду для перевірки міграцій в Laravel.
• roslov/migration-checker — в цьому пакеті знаходиться основна бізнес-логіка.

Пакети наближаються до стабільних релізів та вже «прикручені» до CI кількох комерційних проєктів. Буду вдячний за коментарі та знайдені баги.

Сподобалась стаття? Підписуйтесь на автора, щоб отримувати сповіщення про нові публікації на пошту.