Налаштування Liquibase для автоматичних міграцій БД і CI/CD

Налаштування Liquibase: де ручні міграції ламають реліз

Налаштування Liquibase починається з простого факту: поки схему БД накочують руками — скриптом по ssh, файлом із задачі, командою в консолі, — розбіжність схеми між середовищем розробки, тестовим контуром і продом з'являється непомітно.

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

Ціна проявляється на релізі: збій під час викатки через те, що колонка вже створена або тип не збігся, а застосунок чекає іншу схему. Далі — відкат релізу вручну, звірка дампів, пошук забутого змінення за логами й листуванням. Вікно викатки розтягується, а впевненості, що наступна міграція пройде так само, не з'являється.

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

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

Нижче розбираємо, як це закривається: структура changelog, контексти й мітки для різних середовищ, відкат змін і вбудовування міграцій у конвеєр викатки.

Що дає автоматизація міграцій: ефект за етапами доставки

Ефект від автоматизації міграцій оцінюють не за загальним враженням, а за вимірюваними точками на кожному етапі доставки. Ведемо чотири позначки й звіряємо їх до і після впровадження — так видно, що саме дає перенесення змін схеми з ручних дій у Liquibase.

Відтворюваність середовищ

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

Перевірка проста — розгорнути контур з нуля й порівняти структуру зі стендом, де зміни накочувалися поступово: розбіжностей бути не повинно.

Час викатки змін

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

Час викатки перестає зростати разом із кількістю правок — він визначається обсягом змін, а не кількістю кроків навколо них.

Простій під час оновлення

Кроки вибудовуються за схемою «розширити — заповнити — стиснути»: спочатку сумісні об'єкти, потім перенесення даних, потім видалення старого. Застосунок працює на обох версіях схеми одночасно, тому простій під час оновлення зникає або скорочується до непомітного користувачу.

Частка помилок схеми й зниклий клас відмов

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

Порівняння режимів міграцій: схема, дані, відкат

Режим застосування змін обирають за характером задачі, а не за звичкою: додати колонку або індекс — одна історія, перелити й нормалізувати значення — зовсім інша.

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

Другий фактор — хто ініціює накат. Поки зміни застосовує інженер вручну, порядок тримається на домовленостях; у конвеєрі його фіксує інструмент на кшталт Liquibase, і тоді критично, що саме лежить у наборах змін і як перевіряється їхня цілісність.

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

Налаштування Liquibase у конвеєрі складання й доставки

Налаштування Liquibase у конвеєрі доставки йде від фактичного стану схеми, а не від документації: розбіжності між контурами зазвичай і спливають на викатці. Нижче — порядок робіт, за яким ми проходимо разом із командою замовника.

1. Інвентаризація. Звіряємо схеми контурів розробки, передрелізного й бойового, збираємо об'єкти, що живуть поза системою міграцій, і розбіжності, накопичені ручними правками.
2. Структура changelog. Розбиваємо зміни на файли за релізами, задаємо єдиний формат ідентифікаторів і підключаємо кореневий майстер-файл — історія правок читається без археології.
3. Опис змін. Кожна зміна оформлюється разом із зворотною операцією: застосування й відкат лежать в одному наборі, тому відкат релізу не перетворюється на ручну роботу під навантаженням.
4. Параметри запуску. Налаштовуємо контексти й мітки за середовищами: службові зміни не виїжджають на бойовий контур, а важкі операції йдуть окремим потоком.
5. Перевірка міграцій. Проганяємо зміни на передрелізному контурі на копії бойових даних — дивимося час виконання, блокування, план запитів і вартість відкату.
6. Журнал застосованих версій. Контрольна таблиця стає єдиним джерелом правди про стан бази: за нею видно, що і коли застосувалося, і від неї йде відновлення після збою.
7. Передача регламенту. Віддаємо команді правила додавання змін, автоматичну перевірку в конвеєрі й порядок дій у разі конфлікту — міграції перестають бути зоною одного інженера.

Що залишається в репозиторії: файли, схеми, регламенти

Вихід проєкту — не набір разових правок у базі, а відтворюваний контур міграцій: чистий стенд піднімається однією командою, а розбіжностей між контурами не залишається. Передаємо не тільки код, а й артефакти, за якими команда замовника далі працює без нас.

• Файли змін — упорядковані описи міграцій зі зворотними операціями й поділом на логічні набори; видно, яка зміна до якої задачі належить і як її зняти.
• Схема середовищ — які контури існують, чим відрізняються за правами й даними, де застосовується автоматично під час складання, а де — тільки вручну з підтвердженням.
• Регламент викатки — послідовність кроків, вікно застосування, відповідальний за запуск, порядок у разі несумісної зміни та правила зупинки.
• Політики доступу до бази — окремий обліковий запис для міграцій із мінімально потрібними правами, ролі для читання й запису, заборона ручних правок структури в обхід репозиторію.
• Порядок застосування на різних контурах — від тестового стенда до робочого, з перевіркою на копії даних і синхронізацією номерів змін.
• Інструкції для чергової зміни — що дивитися в журналі, як діагностувати завислу міграцію, як відкотитися й кого підключати.
• Передача документації — опис моделі даних, карта змін, відповідальні та порядок ескалації; приймання йде за чек-лістом, а не за пам'яттю.

Кейс: міграції під автоматичним контролем

Замовник розвивав сервіс із трьома середовищами: розробка, передпродакшн-стенд і робочий контур. Правки схеми накочували вручну — інженер підключався до бази, виконував файл зі змінами й повторював те саме на наступному стенді.

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

Зміни перевели в Liquibase: кожен крок описаний окремим набором у репозиторії, поруч із кодом, і застосовується автоматично під час викатки.

Стан схеми тепер визначається списком застосованих наборів, а не пам'яттю конкретного інженера, — на будь-який стенд потрапляє рівно те, що вже пройшло розробку.

Метрики до і після

Підготовка структури бази перед релізом: було 40–60 хвилин ручної роботи з прив'язкою до однієї людини, стало 6–8 хвилин автоматичного прогону.

Звернень, пов'язаних зі схемою, за квартал: сім до переведення й одне після — і те зловили на передпродакшн-стенді, а не на робочому контурі.

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

Що робити, якщо база вже розгорнута й є розбіжності?

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

Перший крок — інвентаризація змін: знімаємо фактичну схему (DDL-дамп або системний каталог), порівнюємо її з тим, що описує changelog, і розкладаємо розбіжності на три групи — застосовані вручну, відсутні, розійшлися за типом або довжиною полів. Поки ця картина не зібрана, будь-яка міграція — лотерея з даними.

Далі — baseline: Liquibase командою changelog-sync позначає наявні changeSet як виконані, не запускаючи їх, а тег на поточному стані схеми стає точкою відкату.

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

Безпечний перехід будується на попередньому перегляді: спочатку прогін на копії з реальним обсягом даних, потім update-sql — побачити, що саме піде в базу, і тільки потім застосування.

Кожен changeSet іде у своїй транзакції там, де це підтримує СУБД, блокування на журнал міграцій не дає двом релізам стартувати паралельно, а зміни з важкими блокуваннями виносяться в узгоджене вікно.

Якщо схему правили повз міграції, це зловиться за контрольною сумою записів: validate і status зупиняють складання до деплою, а не після нього. Разові розбіжності так перетворюються на зафіксований baseline, а не на постійну ручну синхронізацію двох версій схеми.

Технічні сумніви перед впровадженням міграцій

Частину сумнівів закриває сама механіка міграцій — журнал застосованих changeSet і звірка за контрольними сумами. Решту забезпечує регламент і те, як організований changelog. Відповідаємо на питання, які найчастіше піднімають на етапі оцінки.

Кілька команд мігрують схему одночасно — буде конфлікт?

Кожен модуль веде свій changelog і підключається до спільного через кореневий файл, тому команди не перетинаються в чужих changeSet. Службове блокування на журнал знімає гонку, якщо міграції запускаються паралельно.

Як відкочувати невдалу міграцію?

Для changeSet із парним rollback відкат виконується однією командою. Для незворотних операцій — видалення або перейменування колонки — заздалегідь готуємо компенсувальну міграцію й перевіряємо її на копії робочої бази.

Хто і як запускає зміни на робочому контурі?

Міграції застосовує конвеєр після рев'ю changeSet, а не людина руками. Прямий доступ до робочої бази залишається в чергового інженера й логується — регламент доступу описуємо в документації.

Схеми на стендах розійшлися — що робити?

Єдине джерело — changelog, а відмінності контурів описуємо контекстами й мітками: на стенді застосовується підмножина міграцій, і схема приводиться до потрібної версії без ручних скриптів.

Обговоримо задачу: що потрібно для старту міграцій

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

Що потрібно від вас на вході:

• Список баз і стендів: розробка, тест, передпродакшн, продакшн — і де міграції сьогодні застосовуються вручну.
• Репозиторій із поточними SQL-скриптами або описом схеми — за ним збираємо baseline і бачимо розбіжності між середовищами.
• Доступи до системи складання й до сервера міграцій: сервісний користувач із правами на зміну схеми, але без прав на прод-дані.
• Регламенти: вікна обслуговування, вимоги до відкату, хто підтверджує застосування на продакшні.
• Відповідальний за схему з боку продукту — той, хто погоджує правки перед викаткою.

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

За підсумками оцінки готуємо план переведення змін під Liquibase: з якого середовища починаємо, як синхронізуємо вже застосовані скрипти, як виглядає відкат на кожному кроці.

План погоджуємо разом зі строками й точкою неповернення — моментом, після якого правки схеми йдуть тільки через міграції.