feat: 完成现有小程序接口的全部迁移至新后端

2026-10-19 13:17:51 +08:00
parent 8827110f2f
commit d30cf25890
148 changed files with 13287 additions and 34 deletions
@@ -0,0 +1,97 @@
+---
+name: prisma-mongodb-upgrade
+description: Decision and migration guide for Prisma ORM MongoDB projects on v6, which have no upgrade path to v7. Use when a MongoDB project asks about upgrading Prisma, when "upgrade to prisma 7" comes up in a project with provider = "mongodb", or when evaluating a move to Prisma 8. Triggers on "upgrade prisma mongodb", "prisma 7 mongodb", "mongodb prisma migration", "prisma 8 mongodb".
+license: MIT
+metadata:
+  author: prisma
+  version: "0.2.0"
+---
+
+# Prisma MongoDB Upgrade Path
+
+MongoDB projects are the one Prisma cohort with no road into Prisma 7: **v6 is the terminal
+classic-ORM major for MongoDB, and v7 never ships a MongoDB connector**. The successor path
+is Prisma 8, where MongoDB support is in [Early Access](https://www.prisma.io/docs/orm/supported-databases)
+while PostgreSQL is a release candidate. The official
+[Prisma ORM 6 to 8 (MongoDB) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb)
+is the source of truth for the migration steps. This skill frames the real decision — migrate to
+Prisma 8 (the encouraged path), or stay on v6 where a hard blocker applies — and carries
+the migration mechanics.
+
+**Never do either of these:**
+
+- Never advise a MongoDB project to "upgrade to Prisma 7". The connector does not exist
+  there. The `prisma-upgrade-v7` guide does not apply to MongoDB projects.
+- Never solve the version question by rewriting the app onto a SQL database. Changing the
+  database engine is a separate, much larger decision that is not yours to make implicitly.
+
+## The version landscape
+
+| Version | MongoDB status |
+|---------|----------------|
+| Prisma ORM v6 | Fully supported (`mongodb` provider); latest 6.x is the current stable path; maintenance line |
+| Prisma ORM v7 | **No MongoDB connector — not an option, ever** |
+| Prisma 8 | MongoDB support in **Early Access** through `@prisma/orm-mongo`; still changes between release candidates — the successor path for MongoDB projects |
+
+## The decision, up front
+
+**Migrating to Prisma 8 is the encouraged path.** MongoDB support in Prisma 8 is Early
+Access: functional and moving quickly — and the Prisma team wants MongoDB users to migrate
+early and share feedback. The migration mechanics are
+detailed in the references.
+
+**Staying on the latest v6 remains a legitimate choice where a hard blocker applies** —
+stated plainly: Prisma 8 has no MongoDB transaction method yet (multi-document writes use
+the `mongodb` driver's sessions directly), and MongoDB behavior can still change between
+Prisma 8 release candidates.
+
+### Decision table
+
+| Signal | Direction |
+|--------|-----------|
+| No blockers below apply | Migrate to Prisma 8; run the `verify-cutover-checklist` and share feedback with the Prisma team |
+| Greenfield / prototype / internal tool | Migrate to Prisma 8 |
+| Codebase uses multi-document transactions (`$transaction`) — check with grep, do not ask | Plan raw-driver session equivalents first (see `client-api-mapping`), or stay on v6 until Prisma 8 adds a MongoDB transaction method |
+| Team cannot absorb breaking changes between release candidates | Stay on v6 until MongoDB support leaves Early Access |
+| Risk-averse but interested | Point Prisma 8 at the v6 schema with `prisma6Schema(...)` (see `schema-contract-mapping`), rehearse on a copy (see `verify-cutover-checklist`), then migrate |
+
+Note: this section will be updated when Prisma 8 adds a MongoDB transaction method.
+
+### If staying on v6: hygiene (a deliberate stay, not neglect)
+
+- Pin the Prisma packages to the latest 6.x line and keep taking 6.x patch releases.
+- Track Prisma release notes and security advisories for the 6.x line.
+- Keep the classic v6 MongoDB setup: `url = env("DATABASE_URL")` in the schema, `db push`
+  workflow, no SQL driver adapters (see [`prisma-orm-setup`](../prisma-orm-setup/references/v6-mongodb.md) for the v6 MongoDB shape).
+- Re-evaluate when Prisma 8's MongoDB support leaves Early Access, or when the blockers are resolved.
+
+## Reference files
+
+| Reference | What it covers |
+|-----------|----------------|
+| `references/decision-stay-or-migrate.md` | The full decision framing, blocker checks, and stay-hygiene detail |
+| `references/schema-contract-mapping.md` | v6 schema (`mongodb` provider, `@db.ObjectId`, composite types) → Prisma 8 contract concepts |
+| `references/client-api-mapping.md` | v6 client calls → Prisma 8 equivalents, incl. raw escape hatches and transactions — names map, parity does not |
+| `references/migrations-mapping.md` | v6 `db push`-only story → Prisma 8's plan/migrate/verify/sign flow |
+| `references/verify-cutover-checklist.md` | No-data-moves verification: same DB, index parity, staged round-trip before cutover |
+
+## Verified against
+
+Prisma 8 claims in this skill were checked against the
+[Prisma ORM 6 to 8 (MongoDB) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb),
+written for `@prisma/orm-mongo` 8.0.0-rc.13, and the `prisma-8` skill in
+[prisma/orm](https://github.com/prisma/orm/tree/main/skills/prisma-8) at commit
+`75c1460515fa2f11971533f6a1dec5dab35d4123`. MongoDB support still changes between release
+candidates: **before acting on any Prisma 8 claim, check the installed version**
+(`npm ls @prisma/orm-mongo`) and its synced `prisma-8` skill.
+
+Prisma 8 on MongoDB requires Node.js 22.18+ (24.11+ on the 24 line; 24 recommended),
+TypeScript 5.9+, MongoDB 8.0+, and `mongodb@7` as a peer dependency. The `mongodb@7` driver
+no longer accepts AWS credentials in the connection string.
+
+## Hand-off rule
+
+This skill is the **discovery bridge**, not a replacement for Prisma 8's own
+documentation. After a project switches to Prisma 8, run `prisma skills sync`, read the
+synced `prisma-8/SKILL.md`, and follow it for day-to-day work — do not keep working from
+this skill's summaries.
@@ -0,0 +1,75 @@
+# client-api-mapping
+
+How v6 Prisma Client calls map to Prisma 8's Mongo client — names map, parity does not.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+The v6 and Prisma 8 client APIs look superficially similar, but none of the v6 MongoDB raw
+methods exist under their old names, aggregation moved to a different lane entirely, and
+transactions go through the driver rather than a Prisma method. Assuming parity produces
+code that does not compile — or, in the transactions case, code that silently loses
+atomicity.
+
+## The mapping
+
+| v6 call | Prisma 8 equivalent | Notes |
+|---------|------------------------|-------|
+| `prisma.user.findMany(...)` | `db.orm.users.where({ ... }).all()` | Chained API; collection-name keys (see `schema-contract-mapping.md`) |
+| `prisma.user.findFirst(...)` | `db.orm.users.where({ ... }).first()` | `.where(...)` takes a plain equality object, not `{ equals: ... }` |
+| `create` / `update` / `upsert` / `delete` | Same names on `db.orm.<collection>` | Every mutation except `create` needs a `.where(...)` first |
+| `updateMany` / `deleteMany` | `updateAll` / `deleteAll` | |
+| `prisma.user.aggregate(...)`, `groupBy(...)` | **No ORM equivalent.** Build a plan with `db.query.from(...).group(...).build()` and run it with `(await db.runtime()).query(plan)` | Group totals come from `acc` in `@prisma/orm-mongo/query-builder` |
+| `<model>.findRaw(...)`, `<model>.aggregateRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#findraw)) | `db.raw.collection('<name>').aggregate([...]).build()`, or `db.query.rawCommand(...)` | Run the plan with `(await db.runtime()).query(plan)` |
+| `$runCommandRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#runcommandraw)) | **No Prisma equivalent.** Create a `MongoClient`, pass it to the `mongo(...)` binding as `mongoClient`, and call `mongoClient.db(...).command(...)` | `db.raw` is collection-scoped; database-level commands go through the driver |
+| `$transaction(...)` — works on v6 with a replica set ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)) | **No Prisma method yet.** Use `mongodb` driver sessions (`client.startSession()` / `session.withTransaction(...)`) on a replica set | Pass `{ session }` to every operation; an operation without it runs outside the transaction |
+| `$connect` / `$disconnect` | Connects lazily on first use; `db.close()` disconnects | |
+
+**ObjectId filters in the pipeline builder:** `.match((f) => f.authorId.eq(authorId))` sends
+the id as a plain string and matches nothing. Filter ObjectId fields through the ORM client
+(`db.orm.posts.where({ authorId })`), or use `db.query.rawCommand(...)` with a real
+`ObjectId`.
+
+## Bad
+
+```typescript
+// Assuming v6 names exist in Prisma 8:
+await db.users.$runCommandRaw({ collStats: 'users' }); // no such method
+await db.transaction(async (tx) => { ... });          // no such method on the MongoDB client
+```
+
+## Good
+
+```typescript
+import { acc } from '@prisma/orm-mongo/query-builder';
+
+// Aggregation through the typed pipeline builder:
+const plan = db.query
+  .from('users')
+  .group((f) => ({ _id: f.role, n: acc.count() }))
+  .build();
+const byRole = await (await db.runtime()).query(plan).toArray();
+
+// Database-level commands through the MongoClient shared with the binding:
+await mongoClient.db('my-app-db').command({ ping: 1 });
+
+// Multi-document atomicity through a driver session:
+const session = mongoClient.startSession();
+try {
+  await session.withTransaction(async () => {
+    // ...writes, each with { session }...
+  });
+} finally {
+  await session.endSession();
+}
+```
+
+## References
+
+- [Prisma ORM 6 to 8 (MongoDB) guide, step 3](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb#3-port-client-calls)
+- [Prisma 8 transactions on MongoDB](https://www.prisma.io/docs/orm/fundamentals/transactions#transactions-on-mongodb)
+- [v6 MongoDB raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#raw-queries-with-mongodb)
+- The `prisma-8` skill's `references/queries-mongo.md` — authoritative for the Prisma 8 side
@@ -0,0 +1,86 @@
+# decision-stay-or-migrate
+
+How to decide between migrating a MongoDB project to Prisma 8 and staying on Prisma v6.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+MongoDB projects cannot follow the general "upgrade Prisma" advice: Prisma 7 has no MongoDB
+connector, so the forward path is Prisma 8. Advising an impossible v7 upgrade, or
+silently rewriting the app onto SQL, are both serious failure modes. The encouraged path is
+migrating to Prisma 8 — its MongoDB support is Early Access and the Prisma team wants
+early adopters' feedback — with a deliberate stay on v6 where a hard blocker applies.
+
+## The facts the decision rests on
+
+Prisma 8 side ([supported databases](https://www.prisma.io/docs/orm/supported-databases),
+[6 to 8 MongoDB guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb)):
+
+- **MongoDB support is Early Access** in `@prisma/orm-mongo`; PostgreSQL is a release
+  candidate.
+- The implementation is not a stub: an ORM client, a typed aggregation-pipeline builder, a
+  raw lane, and first-class contract-driven migrations.
+- **Prisma 8 has no MongoDB transaction method yet** — there is no `db.transaction(...)` on
+  the MongoDB client. Multi-document atomicity uses the `mongodb` driver's session API on a
+  replica set. This skill will be updated when a transaction method ships.
+- Early Access means MongoDB behavior can change between release candidates. Floor:
+  Node.js 22.18+, TypeScript 5.9+, MongoDB 8.0+, and `mongodb@7`.
+
+Prisma v6 side:
+
+- v6 fully supports MongoDB, including transactions on replica sets — "MongoDB only allows
+  you to start a transaction on a replica set. Prisma ORM uses transactions internally"
+  ([replica set configuration](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)).
+- v6 MongoDB has no Prisma Migrate; the workflow is `db push`
+  ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)).
+
+## Blocker checks before migrating
+
+Run these checks yourself — from the codebase, not by asking the user:
+
+- **Search the codebase for `$transaction` usage** (grep for `$transaction`). If present,
+  plan the raw-driver session equivalents before migrating (see `client-api-mapping.md`) —
+  or stay on v6 until Prisma 8 adds a MongoDB transaction method.
+- **Check the MongoDB server version** (must be 8.0+ for Prisma 8; v6 tolerated older).
+- **Confirm the team can absorb changes between release candidates.** Someone has to
+  follow the release notes and update the code. For a production app, confirm the user accepts
+  Early Access status before migrating.
+
+## Bad
+
+```text
+User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
+Agent: "Yes — here's the v7 upgrade guide. Step 1: install a driver adapter..."
+```
+
+Prisma 7 has no MongoDB connector; this migration is impossible and the SQL driver-adapter
+steps corrupt a working v6 setup.
+
+## Good
+
+```text
+User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
+Agent: "Prisma 7 does not support MongoDB — v6 is the last classic-ORM
+major for MongoDB. The path forward is Prisma 8, the successor: its MongoDB support is
+Early Access and migrating is encouraged. Let me check the codebase for blockers first —
+searching for $transaction usage and checking the MongoDB server version..."
+```
+
+## Stay-on-v6 hygiene
+
+Staying is a decision, not a default-by-neglect:
+
+- Pin `prisma` and `@prisma/client` to the latest 6.x and keep taking 6.x patches.
+- Watch Prisma release notes and security advisories for the 6.x maintenance line.
+- Keep the classic setup (`url = env("DATABASE_URL")` in the schema; `db push`; no SQL
+  driver adapters).
+- Re-evaluate when Prisma 8's MongoDB support leaves Early Access, or when the blockers are resolved.
+
+## References
+
+- [Prisma ORM 6 to 8 (MongoDB) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb)
+- [Prisma 8 supported databases](https://www.prisma.io/docs/orm/supported-databases)
+- [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)
@@ -0,0 +1,83 @@
+# migrations-mapping
+
+How the v6 MongoDB "no migrations" story maps onto Prisma 8's first-class migration flow.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+This is the largest workflow change in the migration — in v6, MongoDB explicitly has no
+Prisma Migrate, while in Prisma 8 MongoDB participates in the full migration lifecycle.
+Teams porting a `db push` habit into Prisma 8 without understanding the plan/verify/sign flow
+will fight the tooling or bypass its safety rails.
+
+## v6: `db push` only
+
+MongoDB on v6 has no Prisma Migrate and no plans to add it — "MongoDB projects do not rely
+on internal schemas" ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)).
+The workflow is `prisma db push` to sync indexes and unique constraints, with no migration
+history on disk.
+
+## Prisma 8: bring the existing database under management
+
+The database already has collections and data, so bootstrap it with `db update`. It diffs the
+live database against the contract, applies the difference (strict validators, plus indexes
+the contract declares that v6 never created), and signs the database:
+
+```bash
+npx prisma contract emit
+npx prisma db update --db "$DATABASE_URL" --dry-run
+npx prisma db update --db "$DATABASE_URL" --advance-ref db
+```
+
+`--advance-ref db` records the result as the `db` ref that later migration plans diff from.
+
+**Do not use `db init` here.** It only applies additive changes, and adding a validator to a
+collection with existing documents counts as destructive, so it refuses.
+
+## Prisma 8: every later schema change
+
+```bash
+npx prisma contract emit
+npx prisma migration plan --name add_posts_indexes
+npx prisma db migrate --db "$DATABASE_URL" --advance-ref db
+npx prisma db verify --db "$DATABASE_URL"
+```
+
+- **Declare, do not hand-write:** indexes and validators live in the contract, and
+  `migration plan` derives the operations. Rendered MongoDB migrations import their factories
+  (`createCollection`, `validatedCollection`, `setValidation`, `createIndex`, `dropIndex`,
+  `collMod`, `dataTransform`) from `@prisma/orm-mongo/target/migration`.
+- **Marker storage:** Prisma 8 records the database's contract state in a document in the
+  `_prisma_migrations` collection.
+- **DDL is not transactional on MongoDB:** an interrupted `db migrate` is resumed by running
+  it again. After fixing anything by hand, run `prisma db sign` so the signature matches the
+  database.
+- **Push-style alternative:** `db update` without a migration plan is the `db push` analogue
+  for local experiments. It keeps no history.
+- **Validators:** Prisma 8 adds strict `$jsonSchema` validators to each collection by default.
+  Once they are live, writes to documents that do not match the contract fail with
+  `Document failed validation`.
+
+## Bad
+
+```text
+Porting the v6 habit: run `db update` for every change in production, accumulating no
+migration history, and hand-editing collections when verification fails.
+```
+
+## Good
+
+```text
+Bootstrap once with `db update --advance-ref db`. Then emit the contract, plan a migration,
+apply it with `db migrate`, and check with `db verify`. Reserve plain `db update` for local
+experiments, mirroring how `db push` was used on v6.
+```
+
+## References
+
+- [Prisma ORM 6 to 8 (MongoDB) guide, step 4](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb#4-adopt-the-migration-lifecycle)
+- [v6: no Prisma Migrate for MongoDB](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)
+- The `prisma-8` skill's `references/migrations.md` — authoritative for the Prisma 8 side
@@ -0,0 +1,65 @@
+# schema-contract-mapping
+
+How v6 MongoDB schema concepts map onto Prisma 8's contract model.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+Prisma 8 describes the database with a *contract* (authored in PSL or TypeScript), and
+several v6 MongoDB idioms have different equivalents. Translating mechanically without
+knowing the mapping produces contracts that fail `contract emit` or verification, or that
+silently change collection addressing.
+
+## Start without porting
+
+Prisma 8 can read the v6 `schema.prisma` directly: set
+`contract: prisma6Schema('prisma/schema.prisma')` in `prisma.config.ts`, with `prisma6Schema`
+from `@prisma/orm-mongo/config`. v6 keeps owning the database; after each schema change there,
+run `prisma contract emit` and `prisma db sign`. A construct Prisma 8 cannot express fails
+`contract emit` with a `PSL.PRISMA6_MONGO_*` diagnostic. Port the schema to a contract when
+you need what v6 syntax cannot express, such as polymorphism.
+
+## The mapping
+
+| v6 concept | Prisma 8 equivalent | Notes |
+|------------|------------------------|-------|
+| (nothing) | `// use prisma-8` as the first line of `contract.prisma` | Without it, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED` |
+| `datasource db { provider = "mongodb" }` + `url = env(...)` ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#example)) | No provider in the contract. `prisma.config.ts` wraps `defineConfig` from `@prisma/orm-mongo/config` in `definePrismaConfig`, with `db.connection` | `prisma orm init --target mongodb` scaffolds it; point the connection at the same database v6 uses |
+| `id String @id @default(auto()) @map("_id") @db.ObjectId` ([using ObjectId](https://www.prisma.io/docs/orm/overview/databases/mongodb#using-objectid)) | `id ObjectId @id @map("_id")` | |
+| `Int`, `Float`, `Boolean`, `DateTime` | `Int32`, `Double`, `Bool`, `Date` | The v6 names still work with a `PSL_DEPRECATED_SCALAR_NAME` warning; a later release removes them |
+| `BigInt`, `Decimal`, `Bytes`, `Json` | `Int64`, `Decimal128`, `Binary`, `Json` | `Json` holds only JSON values; type a field that holds other BSON values, such as a `Date`, as `Bson` |
+| `@default(now())`, `@updatedAt` | `temporal.createdAt()`, `temporal.updatedAt()` | |
+| Composite types: `type Address { ... }` ([composite types](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types)) | `type Address { ... }` | Unchanged |
+| Enums read and written by key | Enums read and write their **storage value** (`role: 'author'`, not `'Author'`) | Declare the storage value in the enum, for example `Author = "author"` |
+| Model names address the client (`prisma.user`) | **Collection names** address the ORM: `db.orm.users` — the `@@map(...)` value, or the model name exactly as written when there is no `@@map`. `db.orm.User` does not exist for a model mapped to `users` | The most common porting mistake |
+| Indexes declared in schema, applied by `db push` | `@@index(...)` / `@@unique(...)` in the contract, applied by migrations | See `migrations-mapping.md` |
+| No native polymorphism | `@@discriminator(field)` on the base model and `@@base(Base, "value")` on each variant | Declare a variant for **every** value the field has in existing data: the generated validator rejects writes to documents with an undeclared value. A variant must declare at least one field |
+
+## Bad
+
+```typescript
+// Ported from v6 and addressed by model name:
+const user = await db.orm.User.where({ email }).first(); // no such key — the collection is mapped to "users"
+```
+
+## Good
+
+```typescript
+// Mongo ORM keys are collection names (@@map value, or the model name as written):
+const user = await db.orm.users.where({ email }).first();
+```
+
+## Environment requirements
+
+Prisma 8 on MongoDB requires MongoDB 8.0+ and `mongodb@7` as a peer dependency. v6 supports
+older MongoDB servers, so check the server version before planning a migration.
+
+## References
+
+- [Prisma ORM 6 to 8 (MongoDB) guide, step 2](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb#2-port-the-schema-to-a-contract)
+- [v6 MongoDB schema documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)
+- [v6 composite types (MongoDB-only)](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types)
+- The `prisma-8` skill's `references/contract.md` — authoritative for the Prisma 8 side
@@ -0,0 +1,60 @@
+# 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)