Безопасные миграции схемы и откат

Почему миграция ломает откат

Откат работает на коде, потому что деплой — это просто подмена одного неизменяемого артефакта предыдущим: старый образ контейнера всё ещё существует, ты возвращаешь на него трафик, готово за секунды. У базы нет предыдущего артефакта. Это одна изменяемая stateful-сущность, и миграция мутирует её на месте. Как только DROP COLUMN legacy_name выполнился, «вернуться назад» не имеет смысла: колонка и её данные ушли, и даже если ты воссоздашь колонку, строки будут пустыми. Деплой и изменение схемы связаны в релизе, но обратима только одна половина этой пары. Поэтому «просто откати деплой» молча предполагает, что старый код всё ещё может прочитать схему, которую найдёт, — а деструктивное изменение, уехавшее с новым кодом, ломает ровно это предположение.

Это острее, чем кажется, из-за того, как раскатываются современные релизы. Rolling-, canary- или blue-green-деплой (разобранный в прошлом уроке) гоняет две версии твоего кода одновременно против одной базы. Есть окно — иногда минуты, иногда весь прогрев канарейки, — где vN-1 и vN обе обслуживают живой трафик. Если миграция vN изменила схему так, что vN-1 этого не переносит, ты сломал ещё работающую старую версию до того, как вообще нажал откат. Схема обязана удовлетворять каждую живую версию одновременно.

Expand/contract: никогда не меняй колонку за один шаг

Дисциплина, которая делает это безопасным, — параллельное изменение, обычно называемое expand/contract (расширение/сужение: сначала аддитивно расширяй схему, потом деструктивно убирай старое). Ты никогда не мутируешь колонку деструктивно в одной миграции. Ты разбиваешь изменение по релизам так, чтобы в каждый отдельный момент любая работающая версия кода могла читать и писать схему такой, какая она сейчас.

-- РЕЛИЗ 1, шаг EXPAND: только аддитивно, выполняется ДО деплоя нового кода.
-- Старый код игнорирует новую колонку; новый код может начать её использовать. Обратно совместимо.
ALTER TABLE users ADD COLUMN full_name text;        -- nullable, без переписывания
CREATE INDEX CONCURRENTLY idx_users_full_name ON users (full_name);

// РЕЛИЗ 1, код приложения: DUAL-WRITE — пиши и старое, и новое на каждой мутации,
// и читай пока из старой колонки. Бэкфилл существующих строк батчами, не одним UPDATE.
async function setName(id: string, name: string) {
  await db.query(
    `UPDATE users SET legacy_name = $2, full_name = $2 WHERE id = $1`,
    [id, name],
  );
}
// задача бэкфилла: копируй существующие данные ограниченными батчами (например, 1k–10k строк за цикл)
//   UPDATE users SET full_name = legacy_name
//   WHERE full_name IS NULL AND id IN (<следующий батч>);   -- повторяй, пока не кончатся

-- РЕЛИЗ 2: переключи ЧТЕНИЯ на full_name (изменение только кода, без изменения схемы).
-- РЕЛИЗ 3, шаг CONTRACT: дропни старую колонку — ТОЛЬКО после того, как R2 полностью
-- раскатан и проверен, когда legacy_name больше никто не читает. Это единственный деструктивный шаг.
ALTER TABLE users DROP COLUMN legacy_name;

Переименование — каноничный случай, и это не один RENAME COLUMN — это добавь новую колонку + бэкфилл + dual-write + переключи чтения + дропни старую, растянутое на три или более релизов. Ни в один момент работающая версия не встречает схему, которую не умеет обработать, поэтому предыдущий артефакт всегда всё ещё запускается, и откат остаётся настоящим на всём пути.

Порядок: аддитивное до деплоя, деструктивное после

Expand/contract диктует, когда каждая миграция выполняется относительно деплоя, и ошибка тут заново порождает исходный инцидент. Аддитивная миграция (expand) обязана выполниться до деплоя нового кода — колонка должна существовать в тот миг, как новый код стартует, иначе новый код падает на отсутствующей колонке. Деструктивная миграция (contract) обязана выполниться после того, как новый код полностью раскатан и ты уверен, что откатываться не будешь, — к этому моменту старую колонку никто не читает. Запуск деструктивного изменения вместе с деплоем — ровно то, что делает откат невозможным, потому что в момент, когда ты откатываешь деплой, старый код встречает схему, которую оставил после себя новый код.

Online DDL: сама миграция может положить таблицу

Ты написал правильную expand/contract-последовательность — и тут твой CREATE INDEX на таблице в 50 миллионов строк блокирует все записи на три минуты в утренний пик. Последовательность была верна; механика — нет.

Даже аддитивная миграция может вызвать простой, если DDL блокирует таблицу. В Postgres ADD COLUMN с неволатильным дефолтом быстрый и безопасный, но обычный CREATE INDEX берёт блокировку, останавливающую записи на всё время построения, — используй CREATE INDEX CONCURRENTLY, чтобы записи продолжали течь. Долгие ALTER берут блокировку ACCESS EXCLUSIVE и за очередью активных запросов могут застопорить всю таблицу под нагрузкой. А бэкфилл обязан быть батчевым — один гигантский UPDATE users SET full_name = legacy_name переписывает каждую строку в одной транзакции, держа блокировки, раздувая таблицу и работая достаточно долго, чтобы заблокировать autovacuum. Гоняй его ограниченными батчами в несколько тысяч строк, коммитя между ними.

Накат-вперёд против отката

Поскольку база часто не может вернуться назад, сеньорский дефолт для плохого релиза, привёзшего изменение схемы, — нередко накат-вперёд (отгрузить исправленную версию вперёд), а не откат. Но это вариант, который ты держишь открытым только тем, что с самого начала делаешь каждую миграцию обратно совместимой: если каждое изменение схемы — expand/contract, предыдущий артефакт всё ещё запускается против новой схемы, так что откат тоже остаётся настоящим выбором, а не кнопкой, кладущей прод в 500. Обратно совместимые миграции не заменяют откат накатом-вперёд; они делают оба безопасными, чтобы ты выбирал по инциденту.