Чек-лист релиза AI migration для безопасных изменений в production

Почему сгенерированные миграции требуют особой осторожности

AI может написать миграцию за секунды. Но если она окажется неверной, ваша база данных заплатит полную цену.

Один сгенерированный UPDATE с слишком широким фильтром может изменить 50 000 строк, прежде чем кто-то это заметит. Плохой DELETE способен нанести еще больший ущерб и еще быстрее. Многие такие миграции на проверке выглядят нормально. SQL аккуратный, названия понятные, логика читается легко. А потом скрипт встречается с настоящими production-данными, где уже ждут старые записи, NULL, дубликаты, сломанные форматы и годы странных крайних случаев.

Простой пример — новое значение по умолчанию. На бумаге сменить значение столбца с NULL на active кажется безобидным. В production это может пометить старые пробные аккаунты как платящих клиентов, запустить не те письма или сломать отчеты за прошлые месяцы. Запрос выполнился именно так, как был написан. Но данные все равно оказались неверными.

Некоторые сбои вообще не связаны с бизнес-логикой. Миграция может заблокировать занятую таблицу дольше, чем ожидалось. Изменение типа столбца способно переписать большую таблицу и замедлить приложение почти до остановки. Создание индекса может блокировать запись в окне релиза, которое казалось вполне щедрым. Команды часто узнают об этом только после того, как пользователи уже не могут сохранять изменения.

Обычно риски простые: потеря данных из-за удаления или перезаписи, неверные значения по умолчанию, попавшие в живые записи, заблокированные таблицы, которые останавливают трафик, и долгий простой из-за медленного backfill или переписывания таблицы.

AI ускоряет подготовку. Но сам по себе он не делает изменения безопасными. Модели хорошо умеют выдавать вероятные шаблоны SQL, но они не знают грязную историю внутри вашей базы, если кто-то не проверит каждое допущение. Относитесь к каждой сгенерированной миграции как к электроинструменту — полезному, быстрому и вполне способному в один проход испортить production-записи.

Сначала оцените риск, потом выкатывайте

Сгенерированные миграции часто ломаются самым обычным образом. SQL выполняется, ошибок синтаксиса нет, а данные все равно оказываются неправильными. Поэтому сначала смотрите на изменение как на бизнес-риск, а уже потом как на изменение кода.

Начните с простого описания того, что может затронуть миграция. Запишите таблицы, столбцы и примерную оценку того, сколько записей может измениться. Если скрипт заполняет новый столбец из старых данных, тоже отметьте это. Маленькие правки иногда расходятся дальше, чем кажется, особенно если одна таблица питает биллинг, отчеты или админские инструменты.

Краткой заметки о риске достаточно, если она отвечает на четыре вопроса: какие данные миграция будет читать и записывать, от каких пользовательских действий зависят эти данные, сколько записей может измениться и кто принимает решение — продолжать релиз или остановиться.

Опишите сбой человеческим языком. «Миграция упала» — слишком расплывчато. Полезная заметка говорит, что люди увидят на самом деле: заказы с неправильным статусом, пустые счета, сотрудники не могут найти клиента, или служба поддержки видит дубликаты. Если вы можете представить плохой исход, вы быстрее заметите его во время релиза.

Заранее задайте правило остановки. Не придумывайте его под давлением. Можно остановить релиз, если проверочный запрос вернул не то число строк, если миграция идет намного дольше ожидаемого или если один приемочный тест не проходит на данных, похожих на production. Правило должно быть настолько простым, чтобы в 2 часа ночи никто с ним не спорил.

Утверждение тоже должно быть с именами, а не с размытыми ролями. Назначьте одного человека, который одобряет релиз, одного, который запускает его, и одного, кто может тут же его отменить. В небольшой команде две из этих задач могут быть у одного человека. Но все равно запишите это.

Десять минут на то, чтобы назвать риск, стоят гораздо меньше, чем два дня, потраченные на догадки, какие записи изменились и кто должен был остановить релиз.

Зафиксируйте точный набор изменений

Многие сбои миграций начинаются еще до дня релиза. Команда тестирует один набор файлов, а выкатывает немного другой. В случае с сгенерированными миграциями это происходит особенно быстро: кто-то заново запускает prompt, правит SQL или добавляет маленькое изменение, которое никто не проверил.

Зафиксируйте release candidate до начала финального тестирования. Сохраните точные файлы миграции, prompt, который их создал, и все ручные правки в одном месте. Если используете Git, зафиксируйте commit. Если конфиг-флаг влияет на то, как приложение читает или записывает данные, зафиксируйте и его.

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

В этой заметке должен быть понятен замысел простыми словами. Что-то вроде «разделить full_name на first_name и last_name, скопировать существующие значения, оставить старый столбец на один релиз» — и у всех будет одна цель. Ревьюеры смогут сверять эту заметку с SQL и кодом приложения, не гадая, что имел в виду model.

Уберите лишние правки, которые не проходили ревью. Маленькие изменения здесь создают реальные проблемы. Переименованный индекс, смена значения по умолчанию или быстрый фикс в коде приложения могут сделать dry run чистым, а production поведет себя иначе. Если тест использовал одну конфигурацию, а production — другую, вы проверили не настоящий релиз.

Зафиксированный набор изменений упрощает и передачу дел. Если один инженер подготовил миграцию, а другой запускает релиз, они должны видеть одни и те же файлы, одинаковую историю prompt и одну и ту же заметку о релизе. Никаких догадок. Никакой «последней версии». Никакого загадочного патча, живущего только на одном ноутбуке.

Прогоните миграцию шаг за шагом

Используйте безопасную среду со свежими данными, которые близки к production. Игрушечный набор данных мало что показывает. SQL, который отлично выглядит на нескольких тестовых строках, может начать тормозить, падать или портить редкие случаи, когда встретится с реальным объемом.

Начните со свежей копии структуры базы и реалистичного вида данных. Если нужно замаскировать чувствительные поля, оставьте странные записи: старые аккаунты, пустые значения, дубликаты и незавершенные строки. Такие случаи очень часто выявляют неправильные допущения в сгенерированных миграциях.

Один раз запустите миграцию ровно так, как планируете запускать ее в день релиза. Используйте тот же порядок, те же скрипты и ту же версию приложения. Засеките полное время выполнения. Если в безопасной среде это заняло 12 минут, не стоит думать, что production завершится быстрее.

После выполнения смотрите на сами данные, а не только на сообщение об успехе. Сравните число строк до и после. Проверьте неожиданные NULL, измененные значения по умолчанию и обрезанный текст. Убедитесь, что индексы созданы, а ограничения продолжают работать. Затем откройте приложение и протестируйте сценарии, которые зависят от измененных данных.

Последний шаг важнее, чем многим кажется. Миграция может завершиться без SQL-ошибок и все равно сломать регистрацию, поиск, биллинг или страницу админа, потому что приложение ожидает старую форму данных.

Потом сбросьте среду и повторите весь процесс с чистой копии. Второй прогон часто выявляет скрытое состояние, недостающие предусловия или ручные шаги, которые никто не записал. Если результат меняется между прогонами, процесс еще не готов.

Для команд, которые быстро двигаются с AI, повторяемый dry run по-прежнему остается одним из самых дешевых способов поймать плохую миграцию до того, как она коснется production.

Сделайте snapshot, который можно быстро восстановить

Делайте snapshot как можно позже, но так, чтобы это было безопасно. Если создать его за несколько часов до релиза, новые заказы, правки или изменения аккаунтов могут проскочить в разрыв. Для миграции, которая меняет живые записи, snapshot за пять или десять минут до запуска обычно гораздо полезнее, чем более ранний снимок в тот же день.

Команды часто пропускают этот шаг, потому что видят завершившуюся задачу backup и считают, что уже защищены. Это не так. Backup, который никто не восстанавливал, — это все еще догадка.

Один раз потренируйтесь до дня релиза. Восстановите snapshot в отдельную среду и убедитесь, что база запускается, таблицы читаются, а приложение при необходимости может подключиться. Для этой проверки не нужна идеальная копия production. Нужны доказательства, что snapshot настоящий и рабочий.

Во время этой тренировки запишите четыре факта: когда вы создали snapshot, сколько времени занял backup, сколько времени занял restore и какая именно команда или какие шаги нужны для восстановления.

Эти цифры важны. Если backup занимает 12 минут, а restore — 18, команда уже понимает реальное окно восстановления. Это влияет на то, когда планировать деплой, кто должен оставаться онлайн и сколько можно ждать до объявления rollback.

Храните команду восстановления там, где вся release-команда сможет добраться до нее за секунды. Поместите ее в release notes, runbook или deployment ticket. Не оставляйте ее только в истории shell одного инженера.

Небольшой пример хорошо показывает смысл. Допустим, сгенерированная миграция разделяет таблицу клиентов на две таблицы и переписывает значения статусов. Команда делает snapshot в 6:55, начинает релиз в 7:00 и сначала восстанавливает этот snapshot в staging. Они узнают, что восстановление занимает 14 минут, а не пять, как предполагали. Один этот факт может спасти очень тяжелую ночь, если production-поддержка пойдет не так.

Потренируйте rollback

План rollback — это часть релиза. Это не записка на спасение, которую пишут уже после начала проблем.

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

Используйте ту же безопасную копию, что и для dry run. Rollback может выглядеть хорошо на игрушечном наборе данных и провалиться на данных с реальными дубликатами, NULL, старыми форматами или частично обновленными записями. Сначала выполните прямую миграцию, подтвердите изменения, а потом запустите rollback ровно так, как делали бы это под давлением.

Некоторые изменения нельзя обратить полностью. Скрипт rollback может вернуть столбец или отменить изменение схемы, но часто не может восстановить удаленные строки или разделить записи, которые уже были объединены. Если миграция объединяет две записи клиента в одну, вам нужна сохраненная карта того, что изменилось. Без нее вы можете восстановить форму таблицы и все равно потерять исходное состояние данных.

Хорошая проверка rollback отвечает на четыре простых вопроса: кто запускает откат, какой сигнал говорит команде остановиться и вернуть все назад, сколько занимает rollback и какие данные он не сможет восстановить сам.

Время важнее, чем думают многие команды. Если rollback занимает 18 минут, а перестройка cache — еще 12, половина окна релиза уже ушла. Записывайте полное время, а не только шаг базы данных. Добавьте и проверки после rollback: количество строк, выборочные проверки свежих записей и одно бизнес-действие, которое докажет, что приложение все еще работает.

Именно здесь чек-лист действительно помогает. AI может написать reverse migration, но он не скажет, какой простой downtime выдержит ваша команда и у кого вообще есть доступ к production в 11 вечера. Команды с дисциплиной релизов обычно справляются с этим лучше, потому что каждая роль и каждый шаг прописаны явно.

Если rollback в тренировке кажется медленным, запутанным или неполным, отложите релиз. Это дешевле, чем обнаружить пробелы уже на production-данных.

Простой пример из релиза

Небольшой SaaS-команде нужно было добавить обязательное поле customer_segment в таблицу клиентов перед выпуском обновления billing. Инструмент AI написал миграцию: добавить столбец, заполнить его из истории billing и заметок по аккаунту, а затем сделать его NOT NULL. Один инженер подготовил изменение, а CTO дал единственное решение — можно релизить или нет — для ночного окна выката.

Dry run изменил план. Команда восстановила свежую копию production-данных в staging и прогнала миграцию шаг за шагом. Изменение схемы сработало, но backfill оставил сотни строк пустыми, потому что у многих старых клиентов не было истории billing и были грязные заметки. Если бы они выкатили этот скрипт прямо в production, финальное ограничение бы упало в середине релиза.

Поэтому релиз разделили на два этапа. Сначала добавили новый столбец. Потом заполнили только строки с понятным источником данных, а строки с пропусками отправили в очередь на проверку.

Это сделало релиз медленнее, но намного безопаснее.

Перед настоящим деплоем команда взяла свежий snapshot и протестировала восстановление на другом сервере. Потом они потренировали rollback. Инженер засек, сколько времени уходит на остановку job приложения, удаление нового пути записи и восстановление измененных строк из snapshot. Вся последовательность заняла около 12 минут, что укладывалось в их 30-минутное окно.

Эта практика окупилась. Во время production revised backfill начал записывать неправильный segment для небольшой партии архивных тестовых аккаунтов, потому что условие join было слишком широким. Команда заметила это по количеству строк, которое они заранее записали до релиза. Они остановили job, откатили изменение в приложении, восстановили затронутые строки из snapshot и закрыли окно без повреждения данных клиентов.

Полезной частью была не сама сгенерированная миграция. Полезной была дисциплина вокруг нее: сначала dry run, snapshot перед релизом и rollback, который они уже отрепетировали.

Ошибки, которые команды допускают прямо перед релизом

Большинство сбоев релиза начинается не с экзотических багов. Они начинаются тогда, когда команда доверяет сгенерированному SQL только потому, что он выглядит аккуратно, а тестовый прогон один раз прошел.

Первая ошибка проста: никто по-настоящему не читает, что именно затронет миграция. Сгенерированный UPDATE может выглядеть правильно, но затронутые строки говорят другое. Если запрос меняет 200 строк в staging и 2 миллиона в production, это уже не тот же самый релиз. Проверьте число строк, образцы записей и точные фильтры до запуска чего-либо в реальности.

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

Backup тоже создает ложное чувство безопасности. Backup, который никто не восстанавливал, — это просто файл. Команды делают snapshot, чувствуют себя защищенными и идут дальше. А потом релиз идет не так, восстановление занимает намного больше времени, чем ожидалось, или восстановленные данные уже не совпадают с той версией приложения, которую они выкатили.

Проверки времени пропускают по той же причине. Миграция, которая выполняется за 12 секунд на ноутбуке, может идти час на занятой таблице с индексами, блокировками и живым трафиком. Такая задержка бьет дважды: пользователи ее чувствуют, и окно релиза закрывается, пока команда все еще ждет.

Самые грязные сбои случаются, когда изменения в приложении и в схеме приходят не по порядку. Команда выкатывает код, который читает новый столбец, до того как миграция его создала или заполнила. Часть запросов попадает в старую форму, часть — в новую, и ошибки начинают всплывать в местах, которые кажутся не связанными.

Представьте команду, которая добавляет обязательное поле status. Они сначала выкатывают приложение и полагаются на backfill. Backfill зависает на неожиданных NULL в старых записях. Новые запросы начинают падать, потому что код уже ожидает, что status будет везде.

Прямо перед релизом скепсис полезнее скорости. Посмотрите на затронутые строки, протестируйте на грязных данных, один раз восстановите snapshot, измерьте время выполнения и убедитесь, что приложение переживет момент, когда схема меняется.

Короткий checklist на день релиза

День релиза должен быть скучным. Обычно это хороший знак.

Перед тем как кто-то запустит миграцию, проверьте несколько простых фактов:

• Dry run прошел на свежей копии production-данных.
• Команда сделала свежий snapshot и доказала, что может быстро восстановить его.
• Шаги rollback записаны простыми словами, и у каждого шага есть ответственный.
• Окно релиза согласовано заранее.
• Проверки после релиза готовы еще до начала миграции.

Здесь важны мелочи. Используйте тот же файл миграции, который вы тестировали, а не правку в последний момент. Храните SQL, версию приложения, настройки среды и runbook в одном месте, чтобы никому не пришлось гадать под давлением.

Помогает простое правило: если одному человеку нужно по памяти объяснить весь план, значит, план слишком расплывчатый. Запишите его. Поставьте имена рядом с задачами. Выберите четкую точку остановки, где команда скажет «go», «pause» или «roll back».

Если хотя бы один пункт все еще кажется неясным, отложите релиз. Выкатить на час позже дешевле, чем неделю разгребать поврежденные production-данные.

Что делать дальше

Безопасный процесс релиза не должен зависеть от того, кто в этот день оказался онлайн. Превратите свой чек-лист миграции в короткий шаблон, по которому каждый член команды сможет работать одинаково.

Храните этот шаблон рядом с файлом миграции, release notes и командами rollback. Когда давление растет, люди делают меньше ошибок, если план уже записан.

Для каждой сгенерированной миграции добавляйте еще одно ревью перед утверждением. Один человек должен прочитать саму правку. Другой — подтвердить план релиза: результаты dry run, время snapshot, шаги восстановления и точный момент, когда команда остановится и откатит изменения.

Для такого ревью не нужен долгий созвон. Десять аккуратных минут перед релизом могут сэкономить часы разборок позже.

После каждого деплоя записывайте, что произошло на самом деле. Фиксируйте реальное время выполнения, любые предупреждения или ошибки, что команда исправила и выглядел ли план rollback реалистично уже после того, как изменение стало живым.

Короткий шаблон может включать имя и владельца миграции, результат dry run и ожидаемое время, статус snapshot, результаты теста восстановления, команду rollback и заметки о живом релизе.

Эти записи формируют следующий релиз. Если одна миграция заняла на 90 секунд больше, чем ожидалось, или если тест восстановления оказался медленнее, чем позволял release window, следующий план должен измениться.

Сохраняйте процесс компактным, но не убирайте части, которые защищают production-данные. Короткий чек-лист, которому люди доверяют, лучше длинного документа, который никто не читает.

Если вашей команде нужен еще один взгляд перед рискованным релизом, Oleg Sotnikov at oleg.is работает как Fractional CTO и startup advisor и часто помогает небольшим командам выстраивать более надежные процессы релиза и rollback вокруг изменений в software на базе AI.