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

Как запускать миграции и 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)

Во время выкатки старая и новая версии приложения работают с одной схемой. Поэтому изменения делают в несколько шагов:

  1. Expand: добавить новую колонку (nullable), не удаляя старую.
  2. Выкатить код, который пишет в обе и читает новую.
  3. Перенести данные.
  4. 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.

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

Поиск

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