Чек-лист миграционных скриптов, сгенерированных ИИ, для безопасных изменений в продакшене

Почему миграции, написанные ИИ, ломаются в продакшене

Модель может сгенерировать SQL, который выглядит аккуратно, и всё же заморозить загруженную таблицу на 40 секунд. Этого достаточно, чтобы накопились запросы, записи перестали проходить, и обычный деплой превратился в инцидент. Скрипт может идеально работать на маленькой тестовой базе, поэтому риск легко пропустить.

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

Размер таблицы меняет риск больше, чем многие ожидают. Изменение, которое завершается за секунду на 50 000 строк, может занять минуты на 50 миллионах. Индексы усугубляют этот разрыв. То же самое — внешние ключи, триггеры и старые строки с «грязными» данными. ИИ пишет для счастливого пути. Продакшен-базы несут в себе годы крайних случаев.

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

Бэктилл — ещё одна ловушка. ИИ может предложить обновить все строки одним оператором. Это выглядит аккуратно в ревью, но может засосать живой трафик, вызвать отставание реплик или держать блокировки слишком долго. Небольшие партии менее элегантны на бумаге, но гораздо безопаснее в реальности.

Используйте ИИ как быстрый генератор черновиков, а не как финального ревьювера. Сначала проверьте, протестируйте на реалистичных данных, оцените риск блокировок и напишите шаги отката до того, как кто‑то тронет таблицу в продакшене.

Что собрать до того, как модель начнёт писать SQL

Чек-лист начинается до любого промпта. Модели пишут лучше, когда вы даёте факты, а не догадки. Они не знают, 20 000 строк ли в таблице или 200 миллионов, растут ли записи каждое утро, или зависит ли одна старая задача от колонки, которую вы хотите переименовать.

Соберите базовую информацию в одной заметке до того, как кто‑то откроет Claude, GPT или другой инструмент для программирования. Укажите таблицу и колонки, текущее количество строк, почасовой объём чтений и записей, пути кода, которые всё ещё зависят от старой схемы, и можно ли деплоить вживую или нужен maintenance window. Это займёт несколько минут и часто сэкономит часы позже.

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

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

Зависимости в коде — там, где команды часто удивляются. Миграция затрагивает не только базу. Она может сломать фоновые воркеры, админские выгрузки, аналитические запросы, мобильные версии и одноразовые скрипты, о которых никто не помнит, пока они не упадут. Запишите точные пути кода, которые зависят от старых имён таблиц или колонок.

Решите заранее про maintenance window, а не после того, как SQL уже написан. Если изменение требует короткой паузы для записей, скажите об этом в начале. Если приложение должно оставаться полностью онлайн, попросите модель предложить поэтапный, обратноссовместимый план.

Пошаговый поток ревью

Начните с одного простого предложения, которое определяет изменение. Если команда не может сформулировать его ясно, модель будет догадываться. "Добавить nullable-колонку customer_note в orders и заполнять её только для новых строк" — ясно. "Обновить orders для лучшей поддержки заметок" — не ясно.

Это предложение станет тестом для каждого последующего решения. Оно держит ревью в фокусе и не даёт модели смешивать работу по схеме, исправления данных и уборку в одном рискованном скрипте.

Используйте этот поток ревью до того, как любой SQL приблизится к продакшену:

1. Попросите модель предложить как минимум два безопасных подхода. Один вариант может добавить новую колонку и выполнить бэктилл позже. Другой — создать новую форму таблицы и перемещать трафик по этапам. Один запрос часто скрывает плохие компромиссы.
2. Читайте каждый оператор и спрашивайте, что он блокирует, как долго и какую таблицу. Даже маленький ALTER TABLE может приостановить записи, если движок требует более сильной блокировки, чем вы ожидали.
3. Разделите план на отдельные шаги. Сначала измените схему. Любой бэктилл выполняйте пакетами позже. Удаляйте старые колонки, индексы или дефолты только после того, как приложение докажет, что новый путь работает.
4. Убедитесь, что у каждого шага есть понятная точка остановки. Если второй шаг упадёт, команда должна знать, приохидить ли остановиться, повторить или откатиться, не усложнив следующий шаг.
5. Прогоните весь план на недавней копии продакшен-данных. Старые тестовые данные лгут. Свежие данные показывают число строк, null-ы, странные строки, дубликаты и медленные запросы, которых модель не видела.

Небольшой пример помогает. Допустим, нужна новая non-null колонка статуса в большой таблице orders. Небезопасная версия добавляет колонку с дефолтом, переписывает всю таблицу, обновляет каждую строку и убирает старую логику в одном шаге. Безопасная версия добавляет колонку как nullable, деплоит код, который пишет в обе колонки, делает бэктилл пакетами, сверяет счёты, и только потом ужесточает ограничение.

Смысл чек-листа: дайте модели предложить варианты, а человек разбивает план на спокойные, тестируемые куски.

Сначала проверьте риск блокировок

До того как читать SQL построчно, спросите, какие блокировки вызовет изменение и как долго они могут держаться. Миграция может выглядеть безвредной и всё же блокировать записи, тормозить чтения или накапливать ожидающие запросы за одним медленным оператором.

ИИ часто правильно пишет синтаксис, но пропускает стоимость выполнения. Это важнее всего на загруженных таблицах. Если модель предлагает ALTER TABLE, не думайте, что это дешёво только потому, что оператор короткий.

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

Проверьте также операции, которые переписывают всю таблицу. Добавление колонки с тяжёлым дефолтом, смена типа или принудительное обновление построчно может затронуть каждую запись. Длительная перестройка индексов приносит ту же боль, если SQL не использует online или concurrent опции, которые поддерживает ваша СУБД.

Перед тем как одобрить план, ответьте на пять базовых вопросов: блокирует ли какой‑то оператор чтения, запись или и то, и другое; перепишет ли база всю таблицу; какой сейчас размер таблицы; сколько записей в неё попадает в минуту; и какой шаг займёт больше всего времени?

Последний вопрос важнее, чем команды думают. Если один шаг может идти 20 минут на продакшен-данных, планируйте исходя из этого времени, а не по 5‑секундным шагам перед ним. Проверьте количество строк, размер индексов и недавний объём записей. Если стейджинг близок по размеру к продакшену, отработайте миграцию там и добавьте запас по времени.

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

Эта часть скучна, но она предотвращает худший тип провала: миграцию, которая технически проходит, но вокруг неё приложение встаёт.

Напишите шаги отката до деплоя

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

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

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

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

Частичный успех — обычное дело. Изменение в таблице может закончиться, а деплой приложения — провалиться. Новая колонка может появиться, а копирование данных остановиться на полпути. Планируйте такое состояние заранее. Держите старые чтения рабочими, пока новый путь не доказан. Сохраняйте старые записи или двойные записи, пока не убедитесь, что новые данные завершены.

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

Здесь ИИ часто переоценивает себя. Модель может написать валидный прямой SQL и при этом пропустить главный человеческий вопрос: "Если это остановится на полпути, что мы будем делать следующие 10 минут?" Если скрипт на это не отвечает, он не готов для продакшена.

Планируйте бэктилл так, чтобы не навредить живому трафику

Бэктилл — то место, где многие, казалось бы, безопасные миграции превращаются в продакшен-боль. Схемное изменение может закончиться быстро, но один гигантский UPDATE по загруженной таблице может съесть CPU, заполнить WAL, замедлить реплики и блокировать обычные запросы.

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

Держите бэктилл маленьким и наблюдаемым

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

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

Выберите размер пакета, который вы можете объяснить, а не тот, который модель сочла «разумным». Начните с малого, измерьте реальное влияние и увеличивайте только если база остаётся здоровой.

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

Простой пример с таблицей orders

Допустим, вы хотите добавить поле billing_country в orders. Инструмент ИИ может сразу предложить NOT NULL, потому что приложению «нужно» поле. Тут и начинается продакшен‑проблема. Старых строк ещё нет значения, и быстрое изменение может упасть или блокировать записи.

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

ALTER TABLE orders ADD COLUMN billing_country text NULL;

Теперь приложение может меняться без поломки старых данных. Новые заказы начнут писать billing_country, старые заказы продолжат работать.

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

Простой пакетный подход выглядит так:

UPDATE orders
SET billing_country = shipping_country
WHERE billing_country IS NULL
  AND id > 100000
  AND id <= 101000;

Повторяйте этот паттерн по диапазонам до завершения. Следите за ошибками, временем запроса и задержкой записей при выполнении. Если трафик растёт, приостановите и продолжите позже.

Изменение в приложении так же важно, как и SQL. Некоторое время приложение должно писать и старое исходное поле, и новую billing_country. Этот период наложения даёт подушку безопасности. Если какая‑то задача пропустила кусок старых строк, новые заказы останутся корректными.

Перед добавлением ограничения проверьте данные, не предполагайте, что бэктилл сработал. Посчитайте строки, где billing_country всё ещё NULL. Ищите странные случаи: пустые строки, тестовые заказы, импортированные записи или отменённые заказы, которые пропустили нормальный поток.

Когда колонка чиста и приложение достаточно долго писало новое поле, тогда добавляйте ограничение.

ALTER TABLE orders
ALTER COLUMN billing_country SET NOT NULL;

Медленные, скучные миграции обычно выигрывают у хитрых при работе с продакшен-таблицами.

Ошибки команд при работе с миграциями, сгенерированными ИИ

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

Обычная ошибка — доверять сгенерированному SQL, не проверив детали конкретной СУБД. Модель может предложить оператор, который работает на тестовом инстансе, но вызывает блокировки в реальном окружении. Мелочи имеют значение: как строятся индексы, как реплики нагоняют изменения или как долго под нагрузкой держится metadata lock.

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

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

Планы отката часто слишком оптимистичны. После изменения данных откат редко бывает быстрым обращением назад. Если вы переписали значения, разделили колонки или преждевременно удалили старые поля, старое состояние может быть утрачено. Может понадобиться исправление вперёд, восстановление из бэкапа или ручная очистка.

Маленькие тестовые датасеты скрывают неприятные сюрпризы. 10 тысяч строк не покажут поведения 10 миллионов. Они также не выявят крайние случаи: null-ы в старых записях, дубликаты, сломанные внешние ключи или старые версии приложений, которые всё ещё пишут по‑старому.

Короткое ревью ловит большую часть этого. Проверьте, что SQL соответствует вашей конкретной СУБД и её версии. Разделяйте схемные изменения и тяжёлые бэктиллы. Спросите, что будет с репликами и долгими транзакциями. Предполагайте, что откаты, меняющие данные, будут медленными или неполными. Тестируйте на реалистичном объёме, а не на игрушечных данных.

Плохие скрипты миграций редко выглядят безрассудно. Они выглядят разумно до того момента, как попадают в занятую таблицу.

Быстрая проверка и следующие шаги

Миграция может выглядеть безопасной в стейджинге и всё же заморозить записи в продакшене на 30 секунд. Этого достаточно, чтобы вызвать таймауты, накопление очередей и долгую ночь для команды.

Используйте этот чек-лист как знак «стоп», а не формальность. Если какой‑то ответ кажется расплывчатым, притормозите и исправьте план до того, как модель начнёт трогать живые таблицы.

• Спросите, как долго изменение может блокировать чтения или записи. Добавление индекса, смена типа колонки или переписывание большой таблицы может держать блокировки дольше, чем ожидается.
• Проверьте, можно ли безопасно остановиться после каждого шага. Хорошие миграции имеют чистые точки паузы, чтобы вы могли деплоить первую часть, наблюдать систему и продолжать только если всё в порядке.
• Тестируйте на данных, похожих на продакшен, а не на маленьком сэмпле. Запрос на 10 000 строк может работать 2 секунды, а на 80 миллионах — 20 минут.
• Ищите «грязные» данные заранее. Null-ы, дубликаты, сломанные дефолты и поздние записи часто ломают скрипт или оставляют полукорректные данные.
• Убедитесь, что откат реален. Если шаг три провалится, команда должна точно знать, что откатить, что сохранить и как подтвердить консистентность базы.

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

Человеческое ревью всё ещё важно, даже при сильной модели. ИИ быстро генерирует SQL, но он не может судить о продакшен‑рисках так, как опытный инженер.

Если вашей команде нужен второй взгляд перед продакшеном, Oleg Sotnikov на oleg.is делает такого рода ревью как Fractional CTO и советник. Короткий контроль перед деплоем обычно обходится дешевле, чем исправление плохой миграции после появления ошибок у пользователей.