• Оглавление

• Зачем бизнесу миграции без простоя
• Что ломает прод при миграциях: типовые риски
• Принципы безопасных изменений: обратная совместимость и «расширяй–сжимай»
• Практические рецепты для PostgreSQL
  • Добавление колонок и значений по умолчанию
  • NOT NULL без блокировок
  • Внешние ключи и CHECK через NOT VALID
  • Индексы CONCURRENTLY и их удаление
  • Переименование и перенос данных: двойная запись, триггеры, представления
  • Удаление колонок и старых артефактов
  • Типы и ENUM: что можно, а что лучше заменить
• Пошаговый пример: переезд с login на email с уникальным индексом
• Фоновый перенос данных батчами: готовый скрипт
• Настройки сессии, долгие транзакции и защита от «стоп‑мира»
• Автоматизация и проверки в CI
• Откаты без паники: как вернуться к рабочему состоянию
• Чек‑лист перед выкаткой
• Итоги

Зачем бизнесу миграции без простоя

Простой во время миграции — это потерянные заказы и нервы поддержки. «Без простоя» означает, что изменения в схеме можно выкатывать днём, вместе с кодом, без ночных окон и риска остановить приём платежей. Это снижает стоимость релизов, ускоряет развитие продукта и упрощает планирование.

Что ломает прод при миграциях: типовые риски

• Долгие блокировки таблиц и индексов: конкурентные ALTER могут заморозить записи и чтение.
• Переписывание больших таблиц: добавление колонки с DEFAULT в старых версиях, изменение типа с преобразованием.
• Индексы: создание «в лоб» держит эксклюзивную блокировку, запросы встают в очередь.
• Ограничения: проверка FOREIGN KEY или CHECK на весь объём — минуты и часы.
• Необратимые шаги: удалили колонку — код ещё её читает. Итог — падения.

Все эти риски лечатся шаблоном «расширяй–сжимай» и приёмами PostgreSQL, которые снижают блокировки до миллисекунд.

Принципы безопасных изменений: обратная совместимость и «расширяй–сжимай»

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

Дополнительно:

• Миграции — это код. Храним в репозитории, запускаем через один инструмент, откаты документируем.
• Любой шаг должен быть коротким и безопасным к повторному запуску.

Практические рецепты для PostgreSQL

Добавление колонок и значений по умолчанию

В PostgreSQL 11+ добавление колонки с константным DEFAULT не переписывает таблицу и обычно занимает миллисекунды. На проде всё равно лучше действовать аккуратно:

-- Безопасные таймауты на сессию
SET lock_timeout = '1s';
SET statement_timeout = '15min';

ALTER TABLE users ADD COLUMN phone_verified_at timestamptz; -- быстро
-- Значение по умолчанию лучше проставлять в приложении или отдельно
ALTER TABLE users ALTER COLUMN phone_verified_at SET DEFAULT NULL; -- метаданные

Если версия PostgreSQL ниже 11 или DEFAULT вычисляемый, используйте подход «добавить nullable → фоновая заливка → NOT NULL».

NOT NULL без блокировок

Прямой ALTER TABLE ... SET NOT NULL может сканировать таблицу. Безопаснее так:

-- 1) Добавляем ограничение как NOT VALID — оно не проверяет прошлые строки и не блокирует запись
ALTER TABLE users ADD CONSTRAINT users_country_nn CHECK (country_code IS NOT NULL) NOT VALID;

-- 2) Фоновая заливка пропущенных значений (см. пример скрипта ниже)
-- 3) Валидируем ограничение онлайн: допускает запись
ALTER TABLE users VALIDATE CONSTRAINT users_country_nn;

-- 4) Делаем колонку NOT NULL — операция быстрая, т.к. условие уже гарантировано
ALTER TABLE users ALTER COLUMN country_code SET NOT NULL;

Внешние ключи и CHECK через NOT VALID

Аналогично внешним ключам:

ALTER TABLE orders
  ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES users(id) NOT VALID;

-- Фоново приводим данные к целостному виду
ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;

Индексы CONCURRENTLY и их удаление

Создавайте и удаляйте индексы без остановки записи:

-- Создание онлайн
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_created_at ON orders (created_at);

-- Удаление онлайн
DROP INDEX CONCURRENTLY IF EXISTS idx_orders_created_at;

Важно: операции CONCURRENTLY нельзя запускать внутри транзакции. Скрипт миграции должен учитывать это.

Переименование и перенос данных: двойная запись, триггеры, представления

Переименование «в лоб» (ALTER TABLE ... RENAME COLUMN) может сломать старый код. Безопаснее:

1. Добавить новый столбец.
2. Настроить двойную запись (приложение пишет и в старый, и в новый столбец). Если сложно — временный триггер на таблицу:

CREATE OR REPLACE FUNCTION sync_user_email() RETURNS trigger AS $$
BEGIN
  IF NEW.email IS NULL AND NEW.login IS NOT NULL THEN
    NEW.email := NEW.login; -- упрощённый пример
  ELSIF NEW.email IS NOT NULL AND NEW.login IS NULL THEN
    NEW.login := NEW.email;
  END IF;
  RETURN NEW;
END;$$ LANGUAGE plpgsql;

DROP TRIGGER IF EXISTS trg_sync_user_email ON users;
CREATE TRIGGER trg_sync_user_email
BEFORE INSERT OR UPDATE ON users
FOR EACH ROW EXECUTE FUNCTION sync_user_email();

3. Фоново перелить исторические данные.
4. Переключить чтение на новый столбец.
5. Убрать двойную запись и старый столбец.

Иногда удобно сделать совместимое представление:

-- Сохраняем старый контракт для части кода/отчётов
CREATE OR REPLACE VIEW v_users AS
SELECT id, email AS login, created_at FROM users;

Удаление колонок и старых артефактов

Удаляйте только после того, как:

• приложение версии N+1 живёт в проде и не читает колонку;
• метрики ошибок стабильны;
• есть резервный план (см. раздел про откаты).

ALTER TABLE users DROP COLUMN IF EXISTS login;

Типы и ENUM: что можно, а что лучше заменить

• ALTER TYPE ... ADD VALUE — дёшево и безопасно. Но удалить значение нельзя.
• Если значения меняются часто, вместо ENUM используйте справочную таблицу + внешний ключ.

-- Добавить новое значение безопасно
ALTER TYPE order_status ADD VALUE IF NOT EXISTS 'archived';

Пошаговый пример: переезд с login на email с уникальным индексом

Задача: перейти с поля login на email, сделать уникальность по email, не останавливая запись.

Шаг 1. Расширение схемы

SET lock_timeout = '1s';

ALTER TABLE users ADD COLUMN IF NOT EXISTS email text; -- nullable, без ограничений
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (lower(email));

Шаг 2. Двойная запись

• Приложение при любом изменении пользователя пишет и в login, и в email (если одно из полей пустое — копирует значение).
• Временный триггер, если сложно быстро обновить все места записи (см. выше).

Шаг 3. Фоновая заливка email из login

• Скриптом заполняем email там, где он ещё пуст.

Шаг 4. Уникальность без падений

-- Добавим частичный уникальный индекс только на заполненные email
CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS uq_users_email
  ON users (lower(email)) WHERE email IS NOT NULL;

Шаг 5. Переключаем чтение на email, мониторим ошибки.

Шаг 6. Ужесточаем схему

-- Проверка не-null в два шага
ALTER TABLE users ADD CONSTRAINT users_email_nn CHECK (email IS NOT NULL) NOT VALID;
ALTER TABLE users VALIDATE CONSTRAINT users_email_nn;

-- Теперь можно сделать столбец NOT NULL (операция быстрая)
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

Шаг 7. Очистка

-- Больше не нужен старый столбец и индекс
DROP INDEX CONCURRENTLY IF EXISTS idx_users_login;
ALTER TABLE users DROP COLUMN IF EXISTS login;

Фоновый перенос данных батчами: готовый скрипт

Безопаснее обновлять данные порциями. Пример на Python (psycopg), обновляем по первичному ключу батчами по 1000 строк:

# requirements: psycopg[binary]==3.*
import os
import time
import psycopg

DSN = os.getenv("DSN", "dbname=app user=app host=/var/run/postgresql")
BATCH_SIZE = int(os.getenv("BATCH", 1000))
SLEEP = float(os.getenv("SLEEP", 0.05))  # пауза между батчами

SQL_SELECT = """
  SELECT id, login FROM users
  WHERE email IS NULL AND login IS NOT NULL
  ORDER BY id
  LIMIT %s
"""

SQL_UPDATE = """
  UPDATE users u
  SET email = s.login
  FROM (VALUES %s) AS s(id, login)
  WHERE u.id = s.id AND u.email IS NULL
"""

def chunks(rows, size):
    for i in range(0, len(rows), size):
        yield rows[i:i+size]

with psycopg.connect(DSN) as conn:
    with conn.cursor() as cur:
        # Безопасные таймауты на сессию
        cur.execute("SET lock_timeout = '1s'")
        cur.execute("SET statement_timeout = '10min'")

    while True:
        with conn.cursor(row_factory=psycopg.rows.tuple_row) as cur:
            cur.execute(SQL_SELECT, (BATCH_SIZE,))
            rows = cur.fetchall()
            if not rows:
                print("Done")
                break

            # Готовим VALUES для массового апдейта
            values = ",".join(cur.mogrify("(%s,%s)", r).decode() for r in rows)
            cur.execute(SQL_UPDATE % values)
            print(f"updated {cur.rowcount} rows")
        conn.commit()
        time.sleep(SLEEP)

Особенности:

• Короткие транзакции снижают давление на автоочистку (autovacuum).
• Пауза между батчами пропускает продовые запросы.
• Если кластера несколько — не забудьте ограничить параллелизм.

Настройки сессии, долгие транзакции и защита от «стоп‑мира»

Перед любым ALTER:

SET lock_timeout = '1s';
SET idle_in_transaction_session_timeout = '5s';
SET statement_timeout = '15min';

Следите за «залипшими» транзакциями, которые держат старые версии строк и мешают VACUUM:

SELECT pid, usename, now() - xact_start AS age, query
FROM pg_stat_activity
WHERE state <> 'idle' AND xact_start IS NOT NULL
ORDER BY age DESC
LIMIT 20;

-- В крайнем случае
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE pid <> pg_backend_pid() AND application_name = 'проблемный-воркер';

Автоматизация и проверки в CI

• Линтер миграций: запретить CREATE INDEX без CONCURRENTLY, DROP INDEX без CONCURRENTLY, тяжелые ALTER TABLE ... TYPE USING ....
• Тест развёртывания на копии прод‑схемы.
• Шаги пайплайна: подготовка → деплой кода → проверка → очистка.

Пример GitHub Actions (упрощённо):

name: deploy
on: [workflow_dispatch]
jobs:
  prod:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Prepare migrations (expand)
        run: |
          psql "$DSN" -v ON_ERROR_STOP=1 -f migrations/2026-03-09_expand.sql
      - name: Deploy app v2
        run: ./scripts/deploy_app.sh
      - name: Post checks
        run: ./scripts/checks.sh
      - name: Cleanup (contract)
        run: |
          psql "$DSN" -v ON_ERROR_STOP=1 -f migrations/2026-03-09_contract.sql

Где в expand.sql нет операций внутри транзакции для CONCURRENTLY, а в contract.sql — только удаление старых артефактов и ужесточение ограничений.

Откаты без паники: как вернуться к рабочему состоянию

• Откатывайте код быстрее, чем схему. Схема должна быть совместима и с новой, и со старой версией кода хотя бы один релиз.
• Для «опасных» шагов — флажок в админке: быстро вернуть старое поведение без релиза.
• Индексы и ограничения можно удалить CONCURRENTLY. Данные — не всегда. Думайте о возвратном пути ещё в плане миграции.
• Если переносите данные в новую структуру — храните «источник правды» до полной валидации новой. Иногда это «теневая» таблица, иногда дубль столбца.

Чек‑лист перед выкаткой

• План миграции разбит на шаги expand → switch → contract.
• На каждом шаге прописаны таймауты и безопасные блокировки.
• Для больших апдейтов готов скрипт батчевой заливки.
• Для индексов — только CONCURRENTLY.
• Ограничения через NOT VALID → VALIDATE.
• Предусмотрен быстрый откат кода и выключатель новой логики.
• Есть нагрузочные тесты на копии прод‑дампа.
• Мониторинг: время отклика, ошибки 5xx, рост блокировок, автovacuum, размер индексов.

Итоги

Миграции без простоя — это не «магия», а дисциплина: совместимые изменения, короткие шаги и осознанная работа с блокировками. Следуя шаблону «расширяй–сжимай» и используя возможности PostgreSQL — индексы CONCURRENTLY, ограничения с NOT VALID, валидацию онлайн, — можно выкатывать изменения днём, без простоев и ночных дежурств. Для бизнеса это прямые деньги: меньше инцидентов, быстрее вывод фич, предсказуемые релизы.