Pura Database Migrations

Workflow (local dev)

1) Design the change

• Identify affected models and relationships.
• Decide if you need:
  • a new model
  • a new field (nullable vs required)
  • a new enum
  • an index or unique constraint

2) Edit the schema

Modify packages/database/prisma/schema.prisma:

• Prefer additive changes.
• When adding required fields to existing models, consider:
  • default values
  • transitional nullable field + backfill step + follow-up to make required

3) Generate client and apply schema to DB (choose method)

PURA uses Prisma Migrate as the primary workflow:

• Generate client: pnpm --filter database exec prisma generate
• Dev migration: pnpm --filter database exec prisma migrate dev
• Prod migration: pnpm --filter database exec prisma migrate deploy (see DEPLOYMENT.md)

Rules of thumb:

• Development: use prisma migrate dev so migration history stays consistent.
• Production: use prisma migrate deploy (never db push).

4) Seed and verify

Use existing scripts (see packages/database/package.json):

• pnpm --filter database db:seed
• pnpm --filter database db:seed-financial
• pnpm --filter database db:verify-seed

When changing financial schema, update seed-financial.ts and add a verification step (either in verify-seed.mts or DB tests).

5) Add/adjust database tests

Where:

• packages/database/prisma/*.test.ts

Minimum expectations:

• constraints/uniqueness behave as intended
• relationships are correct
• financial invariants (businessDate indexes, void/correction fields exist) are covered where relevant

Run:

• pnpm --filter database test

Workflow (deployment)

Follow DEPLOYMENT.md:

• build database package before API (@pura/database build generates Prisma client)
• run migrations:
  • pnpm --filter database exec prisma migrate deploy

“Done” criteria

• Prisma schema compiles and Prisma client generates
• DB apply step completed (push/migrate)
• Seed and verify scripts still pass (when relevant)
• DB tests updated and passing
• API/Web code updated to match schema changes (types, DTOs, UI)