Как запускать миграции и seed в Docker
На этой странице
Миграции — отдельный шаг, а не часть старта каждой реплики. Локально их запускают через docker compose exec или run --rm; в Compose-окружении — отдельным одноразовым сервисом migrate, от которого API зависит через condition: service_completed_successfully; в production — один раз в CI/CD перед выкаткой новой версии. Запуск migrate && node в CMD каждой реплики приводит к гонкам, медленному старту и падению всех экземпляров при ошибке миграции.
Вопрос
Как правильно запускать миграции и seed базы данных в Docker?
Локальная разработка
docker compose exec api npx prisma migrate dev --name add_orders # создать миграцию
docker compose exec api npx prisma db seed
docker compose run --rm api npx prisma migrate deploy # применить, контейнер удалитсяexec выполняет команду в уже работающем контейнере, run --rm создаёт одноразовый контейнер из того же сервиса — удобно, если API ещё не запущен или упал из-за отсутствующей таблицы.
Одноразовый сервис в Compose
services:
migrate:
build: .
command: ["npx", "prisma", "migrate", "deploy"]
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
depends_on:
db:
condition: service_healthy
restart: "no"
api:
build: .
depends_on:
migrate:
condition: service_completed_successfullyЕсли миграция упадёт, api не запустится, а причина будет в docker compose logs migrate. Для Prisma нужно, чтобы в образе был CLI prisma (часто он в devDependencies) — тогда для migrate используют build-stage или отдельный target.
Почему не в CMD каждого контейнера
CMD ["sh", "-c", "npx prisma migrate deploy && node dist/main.js"]Для pet-проекта с одной репликой это допустимо, но в production:
- несколько реплик стартуют одновременно и запускают миграции параллельно (часть инструментов берёт advisory lock, но не все);
- ошибка миграции роняет все реплики разом, а не одну задачу;
- старт и автоматическое масштабирование замедляются;
- в shell-форме ломается пересылка сигналов.
Production-схема
собрать образ ─▶ push ─▶ migrate (один раз, тем же образом) ─▶ деплой новой версииМиграции запускают отдельной задачей CI/CD, Kubernetes Job или release-командой платформы — тем же образом и с той же версией кода.
Обратная совместимость (expand/contract)
Во время выкатки старая и новая версии приложения работают с одной схемой. Поэтому изменения делают в несколько шагов:
- Expand: добавить новую колонку (nullable), не удаляя старую.
- Выкатить код, который пишет в обе и читает новую.
- Перенести данные.
- Contract: удалить старую колонку отдельной миграцией в следующем релизе.
Переименование колонки одной миграцией сломает старые реплики, ещё обслуживающие трафик.
Seed
| Окружение | Подход |
|---|---|
| Локально | Тестовые данные, можно пересоздавать |
| CI | Детерминированные фикстуры для тестов |
| Production | Только справочники; seed идемпотентен (upsert), запускается осознанно |
await prisma.role.upsert({
where: { name: "admin" },
update: {},
create: { name: "admin" },
});Частые ошибки
- Миграции в
CMDкаждой реплики. prisma migrate devв production — команда для разработки, она может сбросить базу.- Запуск миграций до готовности БД.
- Деструктивные миграции без expand/contract.
- Неидемпотентный seed, создающий дубликаты при каждом запуске.
Что важно помнить
- Миграция — отдельная задача с собственным статусом и логами.
migrate deployприменяет готовые миграции,migrate dev— создаёт новые.- Схема должна быть совместима с предыдущей версией кода на время выкатки.
Мини-шпаргалка
- Dev:
execилиrun --rm. - Compose: сервис
migrate+service_completed_successfully. - Production: один раз в CI/CD перед деплоем.
- Expand → migrate data → contract.
- Seed — идемпотентный.
Документация
Prisma: Deploying database changes, Docker: Control startup order.