{
  "index": 134,
  "slug": "editorial-2024-04-mechanism-data-migrations",
  "title": "Миграция данных без разрыва контракта: expand, backfill и граница отката",
  "excerpt": "Как провести изменение формы данных при смешанных версиях приложения: сохранить совместимость старых reader и writer, ограничить backfill и не принять удаление старой формы за rollback.",
  "contentHtml": "<p>После релиза новая версия сервиса получает записи без нового поля. В логах растёт число ошибок валидации, а старый worker продолжает записывать прежнюю форму. Другой симптом выглядит тише: backfill работает, но вместе с ним растут задержки обычных запросов. Остановка оставляет неизвестное число частично обработанных записей.</p><p>Цена ошибки — не только несколько 500. Смешанные версии могут по-разному прочитать одну запись. Повторная попытка может создать расхождение. Откат бинарника не вернёт удалённое поле или старое значение. Если команда не знает, какие записи уже изменились, она теряет безопасную границу восстановления.</p><h2>Тезис: мигрируют не колонки, а контракт во времени</h2><p>Схема базы — общий протокол между версиями приложения. Поэтому изменение нужно проверять для четырёх ролей: old reader, old writer, new reader и new writer. Пока две версии могут одновременно обслуживать запросы, новая схема обязана принимать допустимую старую форму. Новая версия должна уметь читать обе формы, если backfill ещё не закончен.</p><p>Надёжный маршрут разделяет четыре события: expand добавляет новую поверхность, migrate приводит старые записи к новой форме, switch переводит чтение и запись, contract удаляет старый путь. Эти этапы могут иметь разные владельцы, риски и критерии. Их нельзя прятать в одну миграцию, один релиз или одну фразу «схема уже готова».</p><h2>Механизм совместимости</h2><p>Представим запись заказа. Старая форма хранит сумму в поле <code>amount</code>, новая — объект <code>money</code> с суммой и валютой. В transition-периоде новая версия читает обе формы. Новый writer сохраняет обе формы, пока старый reader ещё возможен. Backfill заполняет <code>money</code> только для записей, где значение можно вывести без потери смысла.</p><pre><code>function readAmount(order) {\n  if (order.money &amp;&amp; Number.isFinite(order.money.value)) {\n    return { value: order.money.value, currency: order.money.currency };\n  }\n\n  if (Number.isFinite(order.amount)) {\n    return { value: order.amount, currency: 'RUB' };\n  }\n\n  return { ok: false, reason: 'amount-is-not-recoverable' };\n}\n\nfunction writeOrder(order, money) {\n  return {\n    ...order,\n    amount: money.value,\n    money: { value: money.value, currency: money.currency },\n  };\n}</code></pre><p>Это учебный пример. Он не подключается к базе, не проверяет валюту по справочнику, не знает транзакционную границу и не доказывает, что dual write атомарен. Его задача уже: явно показать fallback и отрицательный путь. Если старое поле не позволяет однозначно восстановить валюту, функция должна остановиться, а не записать правдоподобное значение.</p><p>В production-протоколе нужно дополнительно определить семантику отсутствующего поля. <code>null</code> может означать «ещё не обработано», «значение неприменимо» или «данные потеряны». Эти состояния нельзя различать по догадке. Их фиксируют в контракте до начала backfill.</p><h2>Симптом → причина → проверка → действие</h2><div class=\"table-scroll\"><table><caption>Диагностика миграции по наблюдаемому сигналу</caption><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>Новый reader получает записи без нового поля</td><td>Backfill не завершён или old writer ещё активен</td><td>Сопоставить версию writer, долю старой формы и область backfill</td><td>Оставить fallback, остановить contract и уточнить owner перехода</td></tr><tr><td>Старый writer получает отказ после expand</td><td>Схема стала обязательной раньше rollout кода</td><td>Проверить запросы old writer и правила default/constraint</td><td>Вернуть совместимое правило или остановить выкладку</td></tr><tr><td>После запуска backfill растёт p95</td><td>Фоновая работа конкурирует за CPU, I/O, lock или соединения</td><td>Сравнить окно backfill с latency, saturation и ожиданием ресурсов</td><td>Остановить работу по заранее заданному signal и сохранить partial state</td></tr><tr><td>Данные в старой и новой форме расходятся</td><td>Dual write не покрывает путь обновления или повторяется неидемпотентно</td><td>Сравнить write paths, ключ операции и правило повторного запуска</td><td>Заморозить switch, определить источник истины и исправить расхождение</td></tr><tr><td>Новая версия зелёная, старый consumer ещё жив</td><td>Готовность оценили по одному deployment</td><td>Проверить workers, очереди, cron и внешних потребителей</td><td>Не удалять старую форму; продлить совместимый период</td></tr><tr><td>Rollback кода прошёл, данные не читаются</td><td>Откат приложения ошибочно приняли за recovery данных</td><td>Проверить форму записей, уже удалённые поля и recovery boundary</td><td>Перейти к data repair или restore-процедуре, если она предусмотрена</td></tr></tbody></table></div><p>Таблица задаёт направление расследования, а не готовую причину. Один симптом может иметь несколько источников. Каждое действие должно ссылаться на конкретный signal и менять только одну переменную, иначе результат нельзя интерпретировать.</p><h2>Expand: добавить новую форму, не сломав старую</h2><p>На expand создают колонку, таблицу или индекс, который не требует от старого кода неизвестного значения. Новая поверхность может быть nullable, но nullable не означает безопасно. Нужно описать, что значит отсутствие, какие записи допустимы и когда значение станет обязательным. Если old writer не способен сохранить новый инвариант, его нельзя превратить в ошибку одним DDL-шагом.</p><p>Стоимость операции зависит от движка, версии и объекта. В документации PostgreSQL описаны разные последствия для добавления колонки, default и ограничений. Поэтому нельзя переносить обещание «без блокировки» с одной СУБД на другую. Перед запуском проверяют конкретную операцию на выбранной версии движка и учитывают её влияние на размер таблицы, lock и репликацию.</p><figure><img src=\"/assets/editorial/2024/data-migrations-2024-version-compatibility.svg\" alt=\"Матрица совместимости старой и новой версии: старый reader и writer используют старую форму, переходная версия читает и пишет обе, новая версия работает с новой формой\" loading=\"lazy\" /><figcaption>Матрица показывает допустимый переход версий. Она не подтверждает, какие версии реально запущены, и не измеряет полноту данных.</figcaption></figure><h2>Migrate: backfill с бюджетом и стоп-сигналом</h2><p>Backfill — отдельный поток изменения состояния. Для него нужны область записей, размер управляемой порции, правило повторного запуска, owner, журнал результата и условие остановки. «Запустить джобу до конца» не является планом. Конец может не наступить, а повторный запуск может дважды применить преобразование.</p><p>Стоп-сигнал должен быть наблюдаемым: превышение согласованной задержки, рост ошибок, lock wait, нарушение контрольной выборки или явная команда владельца. Значения порции и пороги нельзя брать из этого учебного текста. Их получают для конкретной среды. Учебный код не читает метрики и не даёт производственных результатов.</p><p>Остановка не означает провал. Она должна оставить состояние, которое можно описать: какие записи обработаны, какие пропущены, что делает следующий запуск и сохраняется ли старая форма. Если после stop никто не может ответить на эти вопросы, backfill не готов к запуску.</p><h2>Switch и contract: два разных решения</h2><p>Switch переводит reader на новую форму. До него проверяют, что новый reader понимает старую запись, новая запись имеет ожидаемую семантику, а divergence можно обнаружить. После switch fallback ещё может оставаться. Факт, что известная выборка заполнена, не доказывает отсутствие старого writer-а в очереди, worker-е или внешнем consumer-е.</p><p>Contract удаляет старую колонку, таблицу, индекс, fallback или dual write. Это необратимее обычного rollback. Возврат старого бинарника может вернуть старую логику, но не удалит уже записанные новые значения и не восстановит очищенную историю. Поэтому contract выполняют отдельным решением после доказательства отсутствия declared old reader/writer и после фиксации recovery boundary.</p><p>В официальном описании онлайн-миграции Stripe переход разделён на dual write, переключение readers, переключение writers и удаление старых данных. Это полезный шаблон последовательности, но не готовая настройка для другой БД. Сам Stripe отдельно отмечает дополнительную стоимость записи и постепенное увеличение нагрузки. В собственном проекте эти параметры нужно измерять отдельно.</p><h2>Порядок действий</h2><ol><li>Опишите old и new shape. Назовите обязательные поля, значение отсутствия, правила преобразования и случаи, которые нельзя восстановить.</li><li>Составьте матрицу old/new reader и writer. Включите сервисы, worker-ы, очереди, cron и внешних потребителей. Неизвестную роль пометьте как blocker.</li><li>Выберите expand, который сохраняет работу declared old writer. Проверьте DDL, lock и поведение конкретной версии СУБД по официальной документации.</li><li>Выпустите совместимый reader и writer. Убедитесь, что fallback виден в коде и наблюдении, а dual write имеет понятное правило повторения.</li><li>Оформите backfill: scope, owner, bounded batch, idempotency, stop signal, partial state и действие после остановки.</li><li>Проведите ограниченную проверку mixed-version сценария. Зафиксируйте только проверенный результат; не называйте учебный или изолированный прогон доказательством production-ready.</li><li>Переключите reader по заранее названному evidence. Оставьте старую форму доступной на период наблюдения.</li><li>Проверьте отсутствие старых consumers, расхождения данных и необработанной области. Только после этого принимайте отдельное решение о contract.</li></ol><h2>Ограничения и отрицательный путь</h2><p>Эта модель не выбирает isolation level, batch size, lock timeout, формат журнала, стратегию репликации или восстановление из backup. Она не решает вопросы PII, retention, шифрования и прав доступа. Dual write может быть неатомарным, если две формы лежат за разными транзакционными границами. ORM, cache, trigger и очередь могут добавить пути, которых нет в основном сервисе.</p><p>Если новый инвариант нельзя поддержать для old writer, не пытайтесь ускорить rollout. Оставьте expand совместимым, добавьте адаптер или выберите отдельный период остановки. Если backfill нельзя bounded-ить, не запускайте его «на пробу». Если не найден old consumer, не удаляйте старую форму. Если уже произошла потеря данных, называйте действие recovery или data repair, а не rollback.</p><h2>Критерий готовности</h2><p>Миграция готова к следующему этапу, когда документированный owner может проверить пять фактов: каждая активная версия имеет описанные read/write-пары; old writer не отвергается; backfill имеет повторяемость, границу и stop signal; divergence обнаруживается; contract имеет отдельный recovery boundary. Для финального удаления дополнительно нужно подтверждение, что старое представление больше не требуется ни одному заявленному consumer-у.</p><p>Учебный пример выше можно проверить на четырёх входах: новая форма, старая форма, неполная старая форма и конфликтующие значения. Ожидаемый результат — корректное чтение первых двух и явный отказ последних двух. Эта проверка подтверждает логику функции, но не поведение базы, нагрузку, deployment или полноту production-данных.</p><h2>Проверяемые источники</h2><ul><li><a href=\"https://stripe.com/blog/online-migrations\" target=\"_blank\" rel=\"noopener noreferrer\">Stripe Engineering: Online migrations at scale</a> — пример последовательности dual write, смены readers и writers и последующего удаления старой модели. Это описание миграции Stripe, а не гарантия для другой системы.</li><li><a href=\"https://www.postgresql.org/docs/current/ddl-alter.html\" target=\"_blank\" rel=\"noopener noreferrer\">PostgreSQL Documentation: Modifying Tables</a> — ограничения и последствия операций изменения таблиц в PostgreSQL. Точный план нужно проверять для своей версии и объекта.</li><li><a href=\"https://sre.google/sre-book/testing-reliability/\" target=\"_blank\" rel=\"noopener noreferrer\">Google SRE Book: Testing for Reliability</a> — различие между изолированным тестом и проверкой живой среды. Источник не задаёт пороги или критерии готовности конкретной миграции.</li></ul>"
}