Skip to content

Migrations & Seeding

How schema changes and seed data move through local, dev, staging, and production in dichit-backend.

Principles

  1. prisma/schema.prisma is the single source of truth.
  2. Every schema change ships a migration in the same PR as the code.
  3. Never edit applied migrations in a shared environment.
  4. Keep code, migrations, seeders, and generated client aligned — no drift.

Command matrix

The env file is chosen by NODE_ENV (see environment-variables).

Task Local Dev Staging
Create migration pnpm migrate:local:create — —
Apply (dev) pnpm migrate:local:up pnpm migrate:dev:up —
Apply (deploy) pnpm migrate:local:deploy pnpm migrate:dev:deploy pnpm migrate:staging:up
Status/drift pnpm migrate:local:status pnpm migrate:dev:status —
Reset (destructive) pnpm migrate:local:reset pnpm migrate:dev:reset —
Seed up pnpm seed:local:up pnpm seed:dev:up pnpm seed:staging:up
Seed down pnpm seed:local:down pnpm seed:dev:down pnpm seed:staging:down
Resolve (rolled-back) pnpm migrate:local:resolve:rolled-back pnpm migrate:dev:resolve:rolled-back —
Resolve (applied) pnpm migrate:local:resolve:applied pnpm migrate:dev:resolve:applied —

Local workflow

# 1. change schema.prisma
# 2. create + apply a named migration
pnpm migrate:local:create    # prisma migrate dev --create-only
pnpm migrate:local:up

# 3. regenerate client
pnpm prisma:generate

# 4. seed
pnpm seed:local:up

One-shot bootstrap: pnpm setup:local (generate → migrate → seed).

Production / shared environments

  • Shared environments use prisma migrate deploy — it never prompts and never resets.
  • CI/CD runs migrate deploy before/after image rollout (see deployment/ci-cd.md).
  • Never run migrate reset against dev/staging/prod without coordination; prefer targeted SQL fixes in a new migration.
  • If a shared migration is stuck (e.g. partially applied), use migrate resolve --applied|--rolled-back after confirming DB state.

Seeders

Seeders live in prisma/seeders/{dev,staging,prod,common} with up.ts / down.ts entrypoints:

  • common/ — shared seed content (notification templates, challenges, app-review user).
  • dev/ — rich local dataset (companies, cycles, subscribers, pincodes…).
  • staging/, prod/ — reference data only (banners, FAQs, pincodes, locations, templates, consents) — no synthetic business data.

Verification before opening a PR

pnpm migrate:local:reset      # clean apply + seed on local
pnpm check                    # typecheck + lint
pnpm test:unit                # fast feedback
pnpm docker:test:up && pnpm test:functional   # full contract tests
pnpm docker:test:down

Functional tests reset the test DB and re-apply migrations automatically through tests/helpers/setup-functional-tests.ts.