Миграция колонки в PostgreSQL без остановки приложения
Как заменить поле users.name на users.display_name в работающем приложении: добавить колонку, перенести данные порциями и переключить чтение без рискованного переименования. Разбираем порядок релизов, блокировки и откат.

Задача: заменить колонку, пока приложение работает
Представим проект на PostgreSQL 16: приложение хранит имя пользователя в users.name, а новая версия должна читать users.display_name. Прямое переименование кажется самым коротким путём, но старые экземпляры приложения после него начнут получать ошибку «column does not exist». Если релиз развёртывается постепенно, какое-то время старый и новый код работают одновременно.
Ниже — схема перехода через промежуточное состояние: сначала база и приложение поддерживают оба поля, затем данные копируются, а чтение переключается на новое. Это пример миграции, а не отчёт об измерениях на конкретном сервисе: размер таблицы, допустимую нагрузку и длительность операций нужно проверить в вашей среде.
Исходные условия: PostgreSQL 16, таблица users с первичным ключом id, колонка name заполнена и используется текущей версией приложения. SQL ниже — основа для миграций; способ запуска зависит от вашего инструмента.
Почему не стоит просто переименовать поле
ALTER TABLE users RENAME COLUMN name TO display_name быстро меняет схему, но не обновляет код приложения, фоновые задачи и запросы аналитики. Пока хотя бы один из них обращается к name, переименование может оборвать его работу. А если вернуть колонку обратно, появится вторая миграция и риск потерять изменения, записанные после переключения.
Безопаснее провести несколько совместимых изменений. Каждый промежуточный шаг должен выдерживать и старую, и новую версию приложения — это и есть главное требование при постепенном выкатывании.
Миграция без остановки — не одна команда SQL, а договорённость между схемой базы и всеми версиями приложения, которые одновременно с ней работают.
План перехода
- Добавьте новую nullable-колонку. Это изменение не требует сразу переписывать строки таблицы. Выполните DDL в короткой транзакции и проверьте, что колонка появилась в схеме.
- Разверните совместимую версию приложения. Она продолжает читать
name, но при создании и изменении пользователя записывает значение и вdisplay_name. Пока старые экземпляры ещё могут писать только вname, переключать чтение нельзя. Проверьте, что все процессы старой версии завершились. - Перенесите прежние значения порциями. Обновляйте только строки, где новое поле ещё пустое. Так повторный запуск не перезапишет актуальное значение, уже записанное приложением. После каждой порции проверяйте число обработанных строк; после завершения отдельно проверьте, что пустых значений не осталось.
- Переключите чтение на новое поле. Оставьте запись в обе колонки на время проверки. Сравнивайте результаты чтения и ошибки приложения. Успех — новый код работает на всех экземплярах, а запросы к старому полю больше не нужны.
- Закрепите ограничение и удалите старую колонку отдельным релизом. Удалять
nameможно только после проверки фоновых задач, отчётов и отложенных релизов. Успех — метрики и журналы не показывают обращений к старому полю, а тесты проходят на схеме без него.
SQL для добавления и переноса данных
Добавьте колонку отдельной короткой миграцией:
ALTER TABLE users ADD COLUMN display_name text;
Затем запускайте перенос отдельными транзакциями. Этот запрос обновляет не больше 1000 строк за один проход; выполняйте его повторно, пока он не вернёт «UPDATE 0». Пример предполагает, что name не содержит NULL.
WITH batch AS (
SELECT id
FROM users
WHERE display_name IS NULL
ORDER BY id
LIMIT 1000
FOR UPDATE SKIP LOCKED
)
UPDATE users AS u
SET display_name = u.name
FROM batch
WHERE u.id = batch.id;
Порции сокращают время одной транзакции и объём работы, который нужно откатывать при сбое. Но они не гарантируют заданную нагрузку: на скорость влияют индексы, дисковая подсистема, параллельные запросы и размер строк. Начните с одного процесса переноса, наблюдайте за задержками запросов, блокировками и нагрузкой на диск. Если несколько обработчиков используют SKIP LOCKED, нулевая порция может означать, что подходящие строки временно заняты; перед выводом о завершении проверьте условие отдельным запросом.
Для проверки остатка выполните:
SELECT count(*)
FROM users
WHERE display_name IS NULL;
Ожидаемый результат — ноль. Если он не нулевой, не переключайте чтение: выясните причину пропуска строк или проверьте исходные данные.
Как запретить пустые значения без гонки
Когда перенос закончен, сначала добавьте ограничение, не проверяя сразу всю таблицу, затем проверьте его отдельной командой. В PostgreSQL 16 это можно сделать так:
ALTER TABLE users
ADD CONSTRAINT users_display_name_not_null
CHECK (display_name IS NOT NULL) NOT VALID;
ALTER TABLE users
VALIDATE CONSTRAINT users_display_name_not_null;
Проверка ограничений может занять время, но операция валидации допускает обычные чтения и записи. После неё можно установить атрибут NOT NULL, а временное проверочное ограничение удалить. Получение блокировки для DDL тоже может ждать; задайте короткий тайм-аут на ожидание и повторите операцию позже, если она не выполнилась быстро. Точный уровень блокировки и поведение конкретной команды сверяйте с документацией PostgreSQL 16.
SET lock_timeout = '2s';
ALTER TABLE users
ALTER COLUMN display_name SET NOT NULL;
ALTER TABLE users
DROP CONSTRAINT users_display_name_not_null;
Не запускайте этот блок вслепую в общей миграции, если ваш инструмент оборачивает все шаги в транзакцию: сначала проверьте настройки запуска и стратегию отката. А для удаления name используйте отдельный этап после периода наблюдения.
Три варианта и их цена
| Подход | Что выигрываете | Чем рискуете |
|---|---|---|
| Переименовать колонку сразу | Мало SQL, схема меняется одним шагом | Старый код и фоновые задачи могут перестать работать сразу после изменения |
| Добавить поле и перенести данные порциями | Можно выкатывать совместимый код постепенно и контролировать перенос | Временно нужно поддерживать два поля и согласованную запись |
| Добавить поле и заполнить одной массовой операцией | Меньше шагов и проще сценарий миграции | Длинная транзакция может усилить нагрузку и увеличить время блокировок |
Когда какой вариант выбирать
Прямое переименование подходит, если приложение гарантированно остановлено на время изменения, все потребители схемы известны и есть проверенный откат. Для приложения с несколькими экземплярами, фоновой обработкой или релизом без простоя безопаснее переход через два поля. Однократный перенос выбирайте только после оценки объёма таблицы и допустимой длительности операции; без замера на копии данных считать его безопасным нельзя.
Что ломается чаще всего
- Новая колонка остаётся пустой у части пользователей. Обычно не все процессы старой версии завершились или один путь записи забыли обновить. Проверьте список работающих версий и все места, которые меняют пользователя.
- Перенос перетирает новые значения. Условие
WHERE display_name IS NULLзащищает уже заполненные строки. Если логика поля сложнее простого копирования, отдельно определите, какая версия данных главнее. - Миграция ждёт блокировку и задерживает релиз. Не держите DDL в длинной транзакции с другими действиями. Задайте тайм-аут ожидания, посмотрите активные запросы и повторите миграцию в подходящий момент.
- Старое поле удалили раньше времени. Запрос может остаться в отчёте, скрипте поддержки или задаче, которая запускается раз в неделю. До удаления ищите обращения не только в основном коде, но и в соседних потребителях данных.
Сноска. Expand/contract — схема миграции в два крупных этапа: сначала расширить структуру так, чтобы её понимали старый и новый код, затем после переключения удалить устаревшие элементы.
Что делать дальше
Перед релизом воспроизведите последовательность на копии базы сопоставимого размера: замерьте длительность каждого шага, задержки запросов, число оставшихся строк и время ожидания блокировок. Подготовьте план отката для каждого этапа отдельно. Инвалидация кэша и изменение формата данных — отдельные задачи; здесь рассмотрена только миграция колонки.
Редактор изображений: Убрать лишнее, заменить фон, добавить объект, расширить кадр — на вашем изображении.
Спросить агентаИсточники: PostgreSQL 16: ALTER TABLE, PostgreSQL 16: явная блокировка
Частые вопросы
Можно ли просто переименовать колонку в рабочем приложении?
Что делать, если перенос данных не закончился за один запуск?
Можно ли выполнять такой перенос на PostgreSQL другой версии?
Почему новая колонка не заполняется у части пользователей?
Удаление старой колонки обязательно делать сразу после переноса?
Материал носит информационный характер и подготовлен редакцией «Агентуры». Он не является офертой, рекламой или индивидуальной консультацией. Упомянутые продукты, компании и торговые знаки принадлежат их правообладателям. Перед принятием решений, влекущих юридические или финансовые последствия, обратитесь к профильному специалисту.