Миграции без простоя: как менять живую базу
Переименование колонки — одна строка:
alter table users rename column phone to phone_number;На локальной машине это выполняется за секунду. В работающей системе всё выглядит иначе: деплой занимает несколько секунд, и всё это время старый код продолжает запрашивать колонку phone. А её уже нет.
Результат — пачка ошибок и упавшие страницы.
Корень проблемы в том, что вы не можете изменить код и базу одновременно. Всегда есть окно, в котором они не соответствуют друг другу.
Решение — построить изменение так, чтобы каждое промежуточное состояние тоже было рабочим.
Паттерн expand/contract
Основная идея проста: вместо одного ломающего изменения делается несколько неломающих шагов.
Этапов три:
- Expand — добавляете новое, оставляя старое. База поддерживает оба варианта.
- Migrate — переводите код на новое, переносите данные.
- Contract — убираете старое.
Между этапами происходит деплой. И главное: на каждом этапе старый и новый код могут работать одновременно.
Теперь разберём это на конкретных примерах.
Переименование колонки
Сделаем пример из начала статьи правильно.
Шаг 1. Добавить новую колонку.
alter table users add column phone_number text;Новая колонка пуста, ничего не ломается. Старый код продолжает работать с phone.
Шаг 2. Писать в обе.
Меняете код так: при записи пишет в обе колонки, при чтении по-прежнему читает из старой.
await db.update(users).set({
phone: value,
phoneNumber: value,
})Деплоите. Теперь новые записи есть в обеих колонках.
Шаг 3. Перенести старые данные.
update users set phone_number = phone
where phone_number is null and phone is not null;На большой таблице это нужно делать порциями — об этом отдельно ниже.
Шаг 4. Перевести чтение на новую колонку.
Код теперь читает phone_number, но продолжает писать в обе. Деплой. Несколько дней наблюдаете.
Шаг 5. Прекратить запись в старую. Деплой.
Шаг 6. Удалить старую колонку.
alter table users drop column phone;Шесть шагов вместо одной строки. Кажется, что много, но каждый шаг безопасен, и откатиться можно в любой точке.
Добавление колонки NOT NULL
Одна из самых частых ловушек:
alter table orders add column status text not null;Этот запрос сразу выдаст ошибку, потому что в существующих строках значения нет. Даже добавив значение по умолчанию, нужно быть осторожным — в старых версиях PostgreSQL это переписывало всю таблицу и надолго её блокировало.
В современных версиях простое значение по умолчанию выполняется быстро. Но если значение изменчивое (например now() или случайное число), таблица всё равно будет переписана.
Безопасный порядок такой:
-- 1. Добавить nullable (быстро)
alter table orders add column status text;
-- 2. Значение по умолчанию для новых строк
alter table orders alter column status set default 'pending';
-- 3. Заполнить старые порциями
-- 4. Добавить ограничение без проверки
alter table orders add constraint orders_status_not_null
check (status is not null) not valid;
-- 5. Проверить отдельно (без блокировки)
alter table orders validate constraint orders_status_not_null;Последние два шага важны. Ограничение, добавленное с not valid, не проверяет существующие строки — оно выполняется мгновенно. А validate работает отдельно и не блокирует запись в таблицу.
Построение индекса без блокировки
Обычный create index блокирует запись в таблицу на всё время построения. На большой таблице это минуты.
Правильная форма:
create index concurrently idx_orders_created_at
on orders (created_at);concurrently работает медленнее, но не блокирует запись.
Здесь две ловушки. Первая — он не работает внутри транзакции, поэтому ваш инструмент миграций должен выполнять его отдельно. Вторая — он может упасть и оставить после себя невалидный индекс:
select indexrelid::regclass from pg_index where not indisvalid;Сделайте эту проверку привычкой после миграций. Невалидный индекс не используется в запросах, но занимает место и замедляет запись.
Обновление большой таблицы порциями
Один update на таблице в миллион строк — это долгая транзакция, крупная блокировка и отставание репликации.
Правильный путь — разбить на небольшие порции:
update users
set phone_number = phone
where id in (
select id from users
where phone_number is null and phone is not null
limit 5000
);Запускаете это в цикле, пока количество затронутых строк не станет нулём. Между порциями полезно делать короткую паузу — база дышит, а реплика успевает догнать.
Размер порции от 1000 до 10000 обычно работает хорошо. Точное число зависит от ширины таблицы и нагрузки — измерьте один раз.
Ограничьте время ожидания блокировки
Одна строка спасает вас от худшего сценария:
set lock_timeout = '3s';Без неё возможно вот что: alter table ждёт завершения долгого запроса. А пока он ждёт, новые запросы тоже встают в очередь, потому что он уже запросил блокировку. В результате блокируется вся таблица, и эта цепочка останавливает всё приложение.
С lock_timeout миграция просто выдаст ошибку, и вы повторите её позже. Ошибка лучше, чем остановленный сайт.
Я ставлю эту строку в начало каждого файла миграции.
План отката
Для каждой миграции должен быть ответ на один вопрос: что я сделаю, если после деплоя вылезет проблема?
Главная польза паттерна expand/contract в том, что он делает ответ простым. На первых этапах ответ — просто откатить код. База поддерживает обе версии, поэтому старый код продолжит работать.
Сложным откат становится только после последнего шага — удаления старой колонки. Поэтому я всегда откладываю этот шаг: выполняю его через несколько дней стабильной работы новой версии.
Этот шаг не срочный. Лишняя колонка не приносит вам никакого вреда, а её преждевременное удаление вполне может стать причиной ночного подъёма.
Практический чеклист
После написания каждой миграции проверьте:
- Ломает ли это изменение старый код? Если да — разбейте на этапы.
- Есть ли в файле миграции
lock_timeout? - Строится ли индекс с
concurrently? - Разбито ли крупное обновление на порции?
- Добавляется ли ограничение
not nullчерезnot valid+validate? - Есть ли план отката и проверен ли он?
Последний вопрос самый важный. Перед выкаткой в прод прогоните миграцию на копии базы — с сопоставимым объёмом данных. На пустой локальной базе всё работает быстро, и это создаёт ложную уверенность.
Эти шаги кажутся скучными. Но после первого раза, когда миграция остановит работающую систему, они начинают выглядеть совершенно иначе.