manicanldes-backend/docs/migrations.md

Append-only migrations

Never edit or rename a committed migration. Correct mistakes with the next migration. New directories use Prisma's UTC timestamp prefix: YYYYMMDDHHmmss_description.

1. Change the relevant schema file under prisma/.
2. Run pnpm db:migrate --name descriptive_change against a disposable development database and review the generated SQL.
3. Run node scripts/check-migrations.mjs --record-new. This verifies recorded checksums before adding new entries.
4. Run pnpm db:generate, pnpm db:test and pnpm check. Commit schema, SQL, checksums and tests together.

The check normalizes line endings and rejects modified or missing recorded migrations and invalid new timestamp names. Review manifest changes against the base branch; replacing an old checksum is not an acceptable repair.

Production uses pnpm db:deploy, then pnpm db:status. Never use db push in production. Schema diff tooling targets the whole prisma directory. Destructive changes need an expand/backfill/contract rollout and recovery planning.

Phase 1C appends four migrations after the original three: catalog/addresses, inventory, commerce integrity and inventory actor scope. SQL maintains additional integrity constraints and the append-only ledger trigger. Phase 1D appends checkout tables, reservation ownership, immutable snapshot guards and deferred order/line reconciliation. Earlier migrations are unchanged.