re:re:actable
Урок 063 минуты чтения

Что такое миграции базы данных

На этой странице
Кратко

Миграция — версионируемый файл с изменением схемы (или данных), который хранится в репозитории вместе с кодом и применяется инструментом (Prisma Migrate, Drizzle Kit, TypeORM, Knex, Flyway, Liquibase, golang-migrate) в строгом порядке. Инструмент ведёт служебную таблицу применённых версий, поэтому любая среда — локальная, CI, staging, прод — приводится к одинаковому состоянию. Принципы: миграции не редактируют после применения (только новые), каждая маленькая и, по возможности, транзакционная; изменения в проде — обратно совместимые (expand → migrate → contract), потому что во время деплоя старая и новая версии приложения работают одновременно; учитываются блокировки (lock_timeout, CREATE INDEX CONCURRENTLY, NOT VALID).

Вопрос

Что такое миграции базы данных и как их безопасно применять?

Пример миграции

-- migrations/20261024_120000_add_orders_currency.sql
SET lock_timeout = '5s';
 
ALTER TABLE orders ADD COLUMN currency char(3) NOT NULL DEFAULT 'RUB';
ALTER TABLE orders ADD CONSTRAINT orders_currency_check CHECK (currency ~ '^[A-Z]{3}$') NOT VALID;
-- migrations/20261024_120100_validate_orders_currency.sql
ALTER TABLE orders VALIDATE CONSTRAINT orders_currency_check;

Как работает инструмент

schema_migrations
version            | applied_at
20261001_090000    | 2026-10-01 09:01
20261024_120000    | 2026-10-24 12:05

При запуске инструмент сравнивает файлы с таблицей и применяет недостающие по порядку.

Up и down

-- up
CREATE INDEX CONCURRENTLY orders_status_idx ON orders (status);
-- down
DROP INDEX CONCURRENTLY orders_status_idx;

Откат «вниз» в проде используют редко: удалённые данные он не вернёт. Чаще выпускают новую исправляющую миграцию (roll forward).

Expand → migrate → contract

Переименование name → full_name без простоя:

ШагСхемаКод
1. ExpandДобавить full_name (nullable)Пишет в оба столбца, читает старый
2. MigrateПеренести данные пачками—
3. SwitchNOT NULL на full_nameЧитает и пишет только full_name
4. ContractУдалить name (отдельным релизом)—

Прямой RENAME COLUMN сломает инстансы старой версии, которые ещё работают во время rolling deploy.

Опасные операции

ОперацияБезопасная альтернатива
CREATE INDEXCREATE INDEX CONCURRENTLY (вне транзакции)
ADD CONSTRAINT FK/CHECKNOT VALID + VALIDATE CONSTRAINT отдельно
ALTER COLUMN TYPEНовый столбец + перенос + переключение
SET NOT NULL на большой таблицеСначала CHECK (col IS NOT NULL) NOT VALID → VALIDATE → SET NOT NULL (PG 12+ использует проверенный CHECK)
Массовый UPDATE в миграцииОтдельный фоновый скрипт пачками

Подробнее — как безопасно изменить большую таблицу.

Миграции данных

-- небольшой справочник — можно в миграции
INSERT INTO order_statuses (code, title) VALUES ('refunded', 'Возврат') ON CONFLICT DO NOTHING;

Большие переносы данных выносят из миграции схемы в отдельную задачу: миграция должна выполняться секунды, а не часы.

Процесс

  • Миграции проходят code review как обычный код.
  • В CI поднимается чистая БД, применяются все миграции и запускаются тесты.
  • В проде миграции применяются до выкатки нового кода (новые столбцы опциональны для старого кода).
  • prisma db push / synchronize: true — только для прототипов, не для прода.

Частые ошибки

  • Редактировать уже применённую миграцию.
  • Ручные изменения схемы в проде мимо миграций — «дрейф» схемы.
  • RENAME/DROP COLUMN в том же релизе, где меняется код.
  • Миграция без lock_timeout, которая встала в очередь за долгим запросом и заблокировала всех.

Что важно помнить

  • Миграции — история схемы в git, одинаковая для всех сред.
  • Изменения — маленькими шагами и обратно совместимо.
  • Учитывайте блокировки и время выполнения.

Мини-шпаргалка

  • Новая миграция вместо правки старой.
  • SET lock_timeout.
  • CONCURRENTLY, NOT VALID + VALIDATE.
  • Expand → migrate → contract.

Документация

PostgreSQL: ALTER TABLE, Prisma Migrate, Flyway Documentation.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам