Expand-contract: нулевой простой для ломающих изменений схемы

Команда переименовывает users.username в users.handle одним запросом ALTER TABLE во время деплоя. Миграция коммитится мгновенно. Но rolling deploy ещё продолжается — старые поды всё ещё выполняют SQL, ссылающийся на users.username. Каждый запрос от старого пода завершается ошибкой “column does not exist”. Быстрая миграция вызвала реальный инцидент.

Почему rename/drop/type-change нельзя сделать за один шаг

Rolling deploy — единственная безопасная стратегия деплоя в любом масштабе — запускает старый и новый код одновременно от секунд до минут. Если миграция закоммичена до того, как все старые поды завершили работу:

• Переименование: старый код ссылается на старое имя колонки → ошибки column does not exist.
• Удаление: старый код ссылается на удалённую колонку → то же самое.
• Смена типа: старый код ожидает int, колонка теперь text → ошибки приведения типов.

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

Общий фреймворк expand-contract

Каждое ломающее изменение разбивается на шесть фаз:

Пошаговый разбор переименования колонки: username → handle

Канонический пример. Общая длительность: 3–7 дней.

День 1 — Expand:

-- Миграция 1: мгновенно, без дефолта
ALTER TABLE users ADD COLUMN handle TEXT;

День 1 — Деплой dual-write: Код приложения теперь пишет и username, и handle при каждом INSERT/UPDATE. Старый код всё ещё читает username. Новый код читает username (пока что).

День 2 — Backfill:

-- Вне транзакции миграции (пакетный цикл):
UPDATE users SET handle = username
WHERE handle IS NULL
  AND id BETWEEN :batch_start AND :batch_end;
-- Повторять до SELECT COUNT(*) FROM users WHERE handle IS NULL = 0

Пакеты по 1к–10к строк, каждый в короткой транзакции с pg_sleep(0.1) между ними.

День 3 — Переключение чтений: Деплой кода, который читает только handle. Записи всё ещё идут в обе колонки. Мониторинг дашбордов 24 часа.

День 5 — Остановка dual-write: Деплой кода, который пишет только в handle. Ожидание завершения rolling deploy.

День 7 — Contract:

-- Миграция 4: быстро (только метаданные)
ALTER TABLE users DROP COLUMN username;

Каждый шаг независимо деплоится и отменяется. Нулевой простой на всём пути.

Down-миграции — не откат

Down-миграции (обратный SQL к up-миграции) есть во многих инструментах (файлы-партнёры down.sql). Они работают в разработке, но опасны в продакшне:

• Down-миграция, дропающая handle, уничтожает все данные, которые новый код в неё записал.
• Если up-миграция была ADD COLUMN, down — это DROP COLUMN — деструктивно.

Откат в продакшне идёт вперёд: напишите новую миграцию, исправляющую проблему, задеплойте её и двигайтесь вперёд. Рассматривайте down-миграции только как scaffolding для разработки.