{
  "index": 54,
  "slug": "editorial-2026-07-practice-migration-playbook",
  "title": "Миграция без прыжка: как сохранить данные и управлять откатом",
  "excerpt": "Пошаговая схема миграции с инвентарём, совместимыми версиями, контрольным срезом трафика и отдельным планом возврата данных.",
  "contentHtml": "<p>После переключения на новую версию часть заказов читает новое поле, а часть продолжает писать старое. HTTP-ответы остаются успешными, поэтому сбой обнаруживается позже: фильтр не находит заказ, отчёт считает две версии одной записи разными, а возврат трафика не отменяет уже записанные значения. Команда видит зелёный deploy, но не может быстро ответить, что именно возвращать.</p>\n<p>У такой ошибки несколько состояний. Код можно вернуть на предыдущую ревизию, запросы можно отправить на прежний маршрут, но данные уже могли пройти через новый преобразователь. Если эти действия не разделены до начала работ, откат превращается в импровизацию: кто-то исправляет схему, кто-то повторяет операции, а журнал показывает несовместимые версии.</p>\n<p>Ниже — рабочая модель для изменения контракта заказа с <code>status</code> на <code>state</code>. Это не инструкция для конкретной базы или балансировщика. Её цель — заставить миграцию отвечать на четыре вопроса: какой участок меняется, как доказать совместимость, где остановить поток и как восстановить запись после отказа.</p>\n<h2>Миграция — это последовательность состояний</h2>\n<p>Безопасный переход состоит не из одного cutover, а из состояний, которые можно наблюдать и покинуть. Сначала старый контракт остаётся рабочим. Затем новая схема принимает оба представления. После этого писатель создаёт согласованные значения, а сверка проверяет уже существующие записи. Только потом новый читатель получает ограниченный поток.</p>\n<p>Порядок имеет значение. Если удалить <code>status</code> одновременно с выпуском нового читателя, неизвестно, что именно сломалось: схема, сериализация, выборка или маршрутизация. Если сначала включить двойную запись, но не определить, какое значение является источником истины, команда накопит расхождения, которые позднее будет трудно отличить от корректных преобразований.</p>\n<figure><img src=\"/assets/editorial/2026/migration-playbook-2026-phase-decision-gates.svg\" alt=\"Четыре этапа миграции: инвентарь зависимостей, совместимая запись, контрольный срез и решение о расширении или возврате\" loading=\"lazy\" /><figcaption>Каждый переход имеет проверку и стоп-ветку. Пока не названы владелец, состояние данных, контрольная сторона и условие возврата, поток не расширяется.</figcaption></figure>\n<h2>Инвентарь ограничивает область риска</h2>\n<p>Начните с одного маршрута, таблицы или события, а не с формулировки «перенести систему». Для <code>GET /orders/:id</code> запишите владельца, читателя, писателя, источник данных, индекс, кэш, очередь и внешних потребителей. Для каждого звена добавьте версию контракта и способ проверить результат.</p>\n<p>Полезный инвентарь отвечает на вопрос «кто ещё может записать старую форму?». Один забытый batch-job способен продолжать отправлять <code>status</code> после переключения чтения на <code>state</code>. Один отчёт с собственным SQL может видеть другую картину, даже если основной API выглядит исправным. Неизвестный писатель — самостоятельный стоп-сигнал, а не поле для предположения.</p>\n<p>Зафиксируйте границу операции. Например, candidate обслуживает только чтение заказа через один API-маршрут, а фоновая выгрузка остаётся на control. Тогда результат среза относится к конкретному маршруту и набору запросов, а не ко всей платформе. Если границы различаются, их сравнивают отдельно.</p>\n<h2>Совместимость начинается с формата записи</h2>\n<p>Для изменения имени поля примените expand/contract-последовательность. На этапе expand добавьте <code>state</code>, не удаляя <code>status</code>, и разрешите чтение обеих форм. Затем выберите источник истины: например, новое значение вычисляется из старого, пока двойная запись не станет проверяемой. При каждой записи сохраняйте правило преобразования, а не только итоговое значение.</p>\n<p>На этапе двойной записи обработчик должен быть идемпотентным: повтор одной операции не создаёт новую сущность и не меняет результат непредсказуемо. Это требование зависит от ключа и бизнес-операции; универсальная функция «перезаписать всё» его не обеспечивает. Отдельно проверьте null, неизвестное значение, смену регистра, часовой пояс и округление, если они участвуют в преобразовании.</p>\n<p>После сверки новый читатель может стать primary, но старый писатель ещё должен оставаться совместимым на время окна наблюдения. Contract закрывается последним: удаление поля допустимо только после поиска читателей, писателей, миграционных скриптов и восстановительных процедур. Откат приложения в этот момент уже не вернёт удалённую колонку.</p>\n<h2>Сверка должна ловить смысловые расхождения</h2>\n<p>Сравнить количество строк недостаточно. Две таблицы могут иметь одинаковый размер, но разные ключи, пропущенные значения или разные нормализованные статусы. Для выборки задайте стабильный ключ, момент среза и правило сравнения. Результат должен содержать количество проверенных записей, число расхождений, тип расхождения и ссылку на повторяемый запрос.</p>\n<p>Учебный SQL ниже показывает форму проверки, а не готовую команду для вашей схемы. Он отдельно считает отсутствующий ключ и сравнивает значения null-safe. На реальном стенде добавьте фильтр по согласованному срезу, лимит нагрузки, обработку удаления и защиту от чтения незавершённой записи.</p>\n<pre><code>WITH compared AS (\n  SELECT\n    old.id AS old_id,\n    new.id AS new_id,\n    old.status AS old_value,\n    new.state AS new_value\n  FROM orders_old AS old\n  FULL OUTER JOIN orders_new AS new ON new.id = old.id\n)\nSELECT\n  count(*) AS checked,\n  count(*) FILTER (WHERE old_id IS NULL) AS missing_old,\n  count(*) FILTER (WHERE new_id IS NULL) AS missing_new,\n  count(*) FILTER (\n    WHERE old_id IS NOT NULL\n      AND new_id IS NOT NULL\n      AND old_value IS DISTINCT FROM new_value\n  ) AS mismatched\nFROM compared;</code></pre>\n<p>Ожидаемый результат нужно определить до запуска: допустимое число расхождений, перечень разрешённых преобразований и действие при каждом типе. Если <code>normalize</code> скрывает потерю информации, нулевой результат всё равно не доказывает эквивалентность. Для критичных полей полезны выборочная проверка исходных значений и обратное преобразование.</p>\n<h2>Контрольный срез сравнивает одинаковые условия</h2>\n<p>Процент трафика сам по себе не является доказательством безопасности. Нужны две стороны: control на старом чтении и candidate на новом чтении, одна граница маршрута, сопоставимые ключи и одно окно наблюдения. Не смешивайте в одном числе ошибки API, расхождения данных, задержку и повторные запросы: у каждого сигнала должен быть владелец и порог.</p>\n<p>До включения candidate запишите базовую линию control. В течение окна фиксируйте объём запросов, долю ошибок, p95 или другой согласованный показатель задержки, mismatches и обращения к fallback. Порог не следует выдумывать в статье: его определяет SLO и риск конкретной операции. Важно, чтобы команда заранее знала, какое событие останавливает расширение.</p>\n<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>Новый читатель получает пустое поле</td><td>Схема или двойная запись</td><td>Сопоставить ключи и момент первой записи в обеих формах</td><td>Остановить candidate; восстановить запись и повторить сверку</td></tr><tr><td>Старый и новый отчёт расходятся</td><td>Преобразование или собственный потребитель</td><td>Сравнить одну запись по исходному ключу и правилам нормализации</td><td>Исправить контракт отчёта до расширения потока</td></tr><tr><td>Ошибок API нет, но растут mismatches</td><td>Семантика данных</td><td>Разложить расхождения на null, ключ, значение и время записи</td><td>Не считать HTTP 2xx разрешением на cutover</td></tr><tr><td>После возврата маршрута появляются новые расхождения</td><td>Write state</td><td>Проверить, какой писатель принимал данные в окне</td><td>Вернуть совместимый писатель или применить проверенное преобразование</td></tr><tr><td>Нельзя определить момент остановки</td><td>Решение и наблюдаемость</td><td>Найти порог, окно, owner и команду остановки</td><td>Оставить control и не расширять candidate</td></tr></tbody></table></div>\n<h2>Rollback нужно разделить на три действия</h2>\n<p>Возврат кода меняет исполняемую версию. Возврат маршрута меняет, куда идут запросы. Восстановление данных меняет, какой писатель и какой формат принимают новые записи. Эти действия могут выполняться в разном порядке. Поэтому runbook должен содержать три отдельные команды, три проверки результата и одного ответственного за решение.</p>\n<p>Документация Kubernetes уточняет границу rollback Deployment: ревизия создаётся при изменении Pod template, а возврат к предыдущей ревизии откатывает именно эту часть Deployment. Это возвращает образ, параметры и другие элементы шаблона Pod, но не SQL-транзакции, сообщения очереди, записи во внешнем сервисе или уже опубликованный контракт. Их состояние описывается отдельными шагами.</p>\n<p>Если data state необратим, откат должен быть не «вернуть старое», а заранее проверенный способ продолжить работу: dual-read, обратное преобразование, остановка записи или восстановление из согласованной копии. Выбор зависит от потерь и бизнес-операции. До среза выполните его на тестовом наборе и зафиксируйте, как обнаруживаются частичные результаты.</p>\n<h2>Карточка перехода делает решение воспроизводимым</h2>\n<p>Соберите перед запуском одну карточку. В ней должны быть route boundary, owner, source, target, версия преобразования, запрос сверки, контрольные метрики, окно, trigger остановки и действия для кода, маршрута и данных. Пример ниже намеренно возвращает <code>stop</code>, если обязательное поле отсутствует. Положительный ответ говорит только о полноте карточки, а не о готовности production-среды.</p>\n<pre><code>function evaluateMigration(card) {\n  const required = [\n    'route', 'owner', 'source', 'target',\n    'reconciliation', 'writeRecovery', 'rollbackTrigger'\n  ];\n\n  const missing = required.filter((key) =&gt; !card[key]);\n  if (missing.length &gt; 0) {\n    return { status: 'stop', reason: 'missing-fields', missing };\n  }\n\n  if (card.control === card.candidate) {\n    return { status: 'stop', reason: 'same-traffic-boundary' };\n  }\n\n  return { status: 'review', reason: 'card-is-complete' };\n}\n\nconsole.log(evaluateMigration({\n  route: 'orders-read',\n  owner: 'orders-team',\n  source: 'orders.status',\n  target: 'orders.state',\n  reconciliation: 'key-and-normalized-value',\n  writeRecovery: 'resume-compatible-writer',\n  rollbackTrigger: 'mismatch-over-threshold',\n  control: 'orders-read-v1',\n  candidate: 'orders-read-v2'\n}));\n// { status: 'review', reason: 'card-is-complete' }</code></pre>\n<p>Для воспроизводимости сохраните входные параметры и результат проверки рядом с запуском. Если повторная команда получила другой результат, сравните версии схемы, выборку и конфигурацию маршрута. Такой журнал не заменяет метрики, но помогает отделить изменение входа от изменения поведения.</p>\n<h2>Порядок действий перед расширением</h2>\n<ol><li>Выбрать одну границу операции и записать владельца, читателей, писателей, хранилище, кэш, очередь и внешние зависимости.</li><li>Добавить новую форму без удаления старой; проверить чтение старой, новой и смешанной записи.</li><li>Зафиксировать источник истины, правило преобразования, идемпотентность и обработку неизвестных значений.</li><li>Включить двойную запись на тестовой выборке и повторить операцию, чтобы проверить повторяемость результата.</li><li>Сформировать контрольный запрос: ключ, срез, нормализация, допустимые расхождения и лимит нагрузки.</li><li>Снять базовую линию control, затем включить небольшой candidate с известным владельцем и окном наблюдения.</li><li>При каждом стоп-триггере остановить расширение, записать сигнал и выполнить отдельные действия для кода, маршрута и данных.</li><li>Расширять поток только после сверки фактических данных и решения владельца сервиса; не удалять старый контракт в том же изменении.</li><li>После окна наблюдения повторить поиск зависимостей, выключить старую запись и только затем удалить совместимость по плану.</li></ol>\n<h2>Ограничения применимости</h2>\n<p>Эта схема подходит для постепенного изменения совместимого контракта, но не является универсальным планом восстановления. Она не решает конкурентные записи, задержку репликации, несовместимую семантику удаления, смену ключа, перестроение индексов, миграцию файлов или восстановление внешнего сервиса. Для каждой такой границы нужен отдельный план данных и тест отказа.</p>\n<p>PostgreSQL описывает конкретные ограничения логической репликации: конфликт ограничения может остановить репликацию до ручного разрешения, а отсутствующая строка при <code>UPDATE</code> или <code>DELETE</code> может быть пропущена. Поэтому одинаковое число строк не доказывает, что два состояния равны. Проверьте версию PostgreSQL, replica identity, права, фильтры публикации и статистику конфликтов на целевой конфигурации.</p>\n<p>Учебный SQL и JavaScript не подключаются к базе, не управляют трафиком и не подтверждают безопасность реального cutover. Они показывают форму проверки. Перед production-запуском нужны rehearsal на близком объёме данных, резервный план, доступ к остановке потока, журнал результата и человек, который имеет право отменить расширение.</p>\n<h2>Критерий готовности</h2>\n<p>Переход можно выносить на решение владельца, когда для одной границы воспроизводятся исходная запись, новая запись и правило их сравнения; control и candidate измеряются в сопоставимом окне; а отказ приводит к заранее названным действиям для кода, маршрута и данных. Отдельно должны быть проверены неизвестный писатель, частичная запись и конфликт при восстановлении.</p>\n<p>Если команда способна вернуть только контейнер, но не объясняет судьбу записей, это не rollback миграции. Если есть нулевая сверка, но неизвестно, кто писал в окно, это не доказательство совместимости. Готовность — это не зелёный deploy, а повторяемая проверка с понятным стоп-триггером и обратимым состоянием.</p>\n<h2>Проверяемые источники</h2><ul><li><a href=\"https://kubernetes.io/docs/concepts/workloads/controllers/deployment/\" target=\"_blank\" rel=\"noopener noreferrer\">Kubernetes Documentation: Deployments</a> — официальная документация описывает ревизии Deployment, rollback и то, что при возврате откатывается Pod template. Источник не обещает возврат данных, очередей или внешних контрактов.</li><li><a href=\"https://www.postgresql.org/docs/current/logical-replication-conflicts.html\" target=\"_blank\" rel=\"noopener noreferrer\">PostgreSQL 18 Documentation: Conflicts</a> — официальная документация описывает остановку логической репликации на части конфликтов и пропуск операций для отсутствующих строк. Источник не задаёт стратегию конкретного перехода.</li><li><a href=\"https://www.postgresql.org/docs/current/logical-replication-publication.html\" target=\"_blank\" rel=\"noopener noreferrer\">PostgreSQL 18 Documentation: Publication</a> — официальная документация объясняет требование replica identity для поиска строк при репликации <code>UPDATE</code> и <code>DELETE</code>. Это ограничение нужно учитывать при выборе ключа сверки.</li></ul>"
}