Files
it-smi/.agents/skills/prisma-mongodb-upgrade/references/verify-cutover-checklist.md
T
2026-11-16 17:26:19 +03:00

61 lines
3.2 KiB
Markdown

# verify-cutover-checklist
Verification checklist for a v6 → Prisma 8 cutover: the data never moves — only the code does.
## Priority
CRITICAL
## Why It Matters
A v6 → Prisma 8 migration is a *client and workflow* migration against the **same MongoDB
database** — there is no data export/import step, and introducing one (or pointing the new
stack at a fresh database) turns a code migration into an outage. The checklist below keeps
the cutover observable and reversible.
## Ground rules
- **No data moves.** The Prisma 8 contract is authored to describe the existing collections;
both stacks read the same database during the staged phase.
- **v6 stays runnable until cutover is verified.** Do not delete the v6 client, schema, or
dependencies until the checklist passes.
## Checklist
1. **Same database, verified:** the Prisma 8 config points at the same connection string /
database name the v6 app uses. The `mongodb@7` driver rejects some URLs v6 accepted, such
as AWS credentials in the connection string — validate the URL with the driver first.
2. **Server floor:** MongoDB server is 8.0+ (Prisma 8's requirement; v6 tolerated older).
Confirm before authoring any contract.
3. **Rehearsal on a copy:** on a throwaway copy of the database, run `contract emit`,
`db update --dry-run`, `db update`, and `db verify`, and confirm `db verify` passes before
touching production. Verification failures here are contract-mapping bugs, not database
problems.
4. **Index parity:** enumerate indexes on every collection (`db.collection.getIndexes()`)
and confirm the Prisma 8 contract declares the same set — v6 `db push` may have created
indexes the new contract must re-declare, or verification and query performance will
diverge.
5. **Validator impact assessed:** Prisma 8 emits closed `$jsonSchema` validators by default;
confirm legacy documents (extra fields, drifted shapes) pass them on the staging copy
before applying to production.
6. **Storage-name addressing audited:** every ported call site uses collection storage
names (`db.orm.users`), not model names (see `schema-contract-mapping.md`).
7. **Transaction inventory mapped:** grep the v6 app for `$transaction`; each hit gets a
`mongodb` driver-session equivalent on a replica set (see `client-api-mapping.md`).
8. **Raw call inventory mapped:** every `$runCommandRaw` / `findRaw` / `aggregateRaw` call
has an explicit Prisma 8 replacement (`db.raw`, `db.query.rawCommand(...)`, the pipeline
builder, or the shared `MongoClient`).
9. **Staged read-only soak:** run the Prisma 8 stack read-only against staging/production data
alongside v6 and compare outputs before allowing writes.
10. **Cutover + rollback:** switch writes to Prisma 8 only after the soak; keep the v6 branch
deployable as the rollback path. Rolling back is a code rollback — the data was never
moved.
After cutover, follow the synced `prisma-8` skill for ongoing work (see the hand-off rule
in `SKILL.md`).
## References
- [v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)
- [Prisma ORM 6 to 8 (MongoDB) guide, step 5](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb#5-pre-flight-checklist-before-production-cutover)