Что такое миграции базы данных
На этой странице
Миграция — версионируемый файл с изменением схемы (или данных), который хранится в репозитории вместе с кодом и применяется инструментом (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. Switch | NOT NULL на full_name | Читает и пишет только full_name |
| 4. Contract | Удалить name (отдельным релизом) | — |
Прямой RENAME COLUMN сломает инстансы старой версии, которые ещё работают во время rolling deploy.
Опасные операции
| Операция | Безопасная альтернатива |
|---|---|
CREATE INDEX | CREATE INDEX CONCURRENTLY (вне транзакции) |
ADD CONSTRAINT FK/CHECK | NOT 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.