wip
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
---
|
||||
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 Next. Triggers on "upgrade prisma mongodb", "prisma 7 mongodb", "mongodb prisma migration", "prisma next mongodb".
|
||||
license: MIT
|
||||
metadata:
|
||||
author: prisma
|
||||
version: "0.1.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 Next](https://github.com/prisma/prisma-next), where MongoDB support is in Early
|
||||
Access with GA planned after Postgres. This skill frames the real decision — migrate to
|
||||
Prisma Next (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 Next | MongoDB support in **Early Access**, actively developed, GA planned after Postgres — the successor path for MongoDB projects |
|
||||
|
||||
## The decision, up front
|
||||
|
||||
**Migrating to Prisma Next is the encouraged path.** MongoDB support in Prisma Next is Early
|
||||
Access: functional and moving quickly, with GA planned after Postgres — 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: the Next Mongo façade does not wrap transactions yet (the underlying driver
|
||||
is available directly; this is expected to change soon), and pre-1.0 minors can carry
|
||||
breaking changes with published upgrade recipes.
|
||||
|
||||
### Decision table
|
||||
|
||||
| Signal | Direction |
|
||||
|--------|-----------|
|
||||
| No blockers below apply | Migrate to Next; run the `verify-cutover-checklist` and share feedback with the Prisma team |
|
||||
| Greenfield / prototype / internal tool | Migrate to Next |
|
||||
| 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 the façade wrapper lands |
|
||||
| Team cannot absorb pre-1.0 breaking upgrades between minors | Stay on v6 until GA |
|
||||
| Risk-averse but interested | Run a staged Next round-trip on a copy (see `verify-cutover-checklist`), then migrate |
|
||||
|
||||
Note: the transactions gap is expected to close soon — this section will be updated when
|
||||
façade transactions merge in Prisma Next.
|
||||
|
||||
### 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-database-setup` for the v6 MongoDB shape).
|
||||
- Re-evaluate when Prisma Next's MongoDB is GA, or when blockers for trying EA 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) → Next contract concepts |
|
||||
| `references/client-api-mapping.md` | v6 client calls → Next equivalents, incl. raw escape hatches and transactions — names map, parity does not |
|
||||
| `references/migrations-mapping.md` | v6 `db push`-only story → Next'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
|
||||
|
||||
Behavioral claims about Prisma Next in this skill were verified against
|
||||
[prisma/prisma-next](https://github.com/prisma/prisma-next) at commit
|
||||
`a2791c5dd59d579b4b3052942ae7f8fe5e2ee852` (pre-1.0, ~v0.14/0.15 line). Prisma Next moves
|
||||
quickly in Early Access: **before acting on any Next-side claim, verify it against the
|
||||
version actually installed** (check the project's `@prisma-next/*` versions and the
|
||||
prisma-next skills installed with it). Next's Mongo target requires MongoDB 8.0+ and expects
|
||||
`mongodb@^7` as a user-supplied peer dependency.
|
||||
|
||||
## Hand-off rule
|
||||
|
||||
This skill is the **discovery bridge**, not a replacement for Prisma Next's own
|
||||
documentation. After a project switches to Prisma Next, run Prisma Next's `init`/skill
|
||||
installation and follow its own skills (quickstart, contract, queries, migrations, runtime)
|
||||
for day-to-day work — do not keep working from this skill's summaries.
|
||||
@@ -0,0 +1,61 @@
|
||||
# client-api-mapping
|
||||
|
||||
How v6 Prisma Client calls map to Prisma Next's Mongo client — names map, parity does not.
|
||||
|
||||
## Priority
|
||||
|
||||
CRITICAL
|
||||
|
||||
## Why It Matters
|
||||
|
||||
The v6 and Next 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 façade wrapper. Assuming parity produces
|
||||
code that does not compile — or, in the transactions case, code that silently loses
|
||||
atomicity.
|
||||
|
||||
## The mapping
|
||||
|
||||
| v6 call | Prisma Next equivalent | Notes |
|
||||
|---------|------------------------|-------|
|
||||
| `prisma.user.findMany(...)` | `db.orm.users.where(...).all()` | Fluent ORM lane; storage-name keys (see `schema-contract-mapping.md`) |
|
||||
| `prisma.user.findFirst(...)` | `db.orm.users.where(...).first()` | |
|
||||
| `create` / `update` / `upsert` / `delete` / `updateMany` / `deleteMany` | `create` / `update` / `upsert` / `delete` / `updateAll` / `deleteAll` on `db.orm.<collection>` | See Prisma Next's `prisma-next-queries` skill |
|
||||
| `prisma.user.aggregate(...)`, `groupBy(...)` | **No ORM equivalent.** Use the typed aggregation-pipeline builder: `db.query.from(...).match(...).group(...).build()` | Prisma Next's `prisma-next-queries` skill covers the builder lane |
|
||||
| `$runCommandRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#runcommandraw)) | **Name does not exist in Next.** Raw lane is `mongoRaw(...)` → a raw collection with `aggregate`, `insertOne/Many`, `updateOne/Many`, `deleteOne/Many`, `findOneAndUpdate/Delete`. For arbitrary database commands, use the underlying `mongodb` driver directly — it is a user-supplied peer dependency and fully accessible | Check the installed version's raw surface |
|
||||
| `<model>.findRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#findraw)) | `mongoRaw(...)` collection reads (e.g. `aggregate` with a `$match` stage) | No direct `findRaw` name |
|
||||
| `<model>.aggregateRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#aggregateraw)) | `mongoRaw(...).aggregate(...)` or the typed pipeline builder | |
|
||||
| `$transaction(...)` — works on v6 with a replica set ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)) | The façade does not wrap `db.transaction(...)` yet, **but the underlying `mongodb` driver is directly available** (user-supplied peer dependency): multi-document atomicity works today via driver sessions (`client.startSession()` / `session.withTransaction(...)`) on a replica set | A façade wrapper is expected soon; this row will be updated when it merges |
|
||||
| `$connect` / `$disconnect` | `connect()` / `close()` on the Mongo façade client | |
|
||||
|
||||
## Bad
|
||||
|
||||
```typescript
|
||||
// Assuming v6 names exist in Prisma Next:
|
||||
await db.user.$runCommandRaw({ collStats: 'users' }); // no such method
|
||||
await db.transaction(async (tx) => { ... }); // no such method on the Mongo façade
|
||||
```
|
||||
|
||||
## Good
|
||||
|
||||
```typescript
|
||||
// Raw lane under its Next name:
|
||||
const raw = mongoRaw(db);
|
||||
await raw.users.aggregate([{ $match: { status: 'active' } }]);
|
||||
|
||||
// Aggregation through the typed pipeline builder:
|
||||
const stats = await db.query.from('users').group({ _id: '$role', n: { $count: {} } }).build();
|
||||
|
||||
// Multi-document atomicity today: the mongodb driver (a direct dependency of the
|
||||
// project) exposes sessions and transactions as usual:
|
||||
const session = mongoClient.startSession();
|
||||
await session.withTransaction(async () => {
|
||||
// ...writes...
|
||||
});
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [v6 MongoDB raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#raw-queries-with-mongodb)
|
||||
- [v6 replica set requirement for transactions](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)
|
||||
- Prisma Next queries + runtime skills (`skills/prisma-next-queries`, incl. its dedicated `mongo.md`; `skills/prisma-next-runtime`) — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`
|
||||
@@ -0,0 +1,87 @@
|
||||
# decision-stay-or-migrate
|
||||
|
||||
How to decide between migrating a MongoDB project to Prisma Next 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 Next. Advising an impossible v7 upgrade, or
|
||||
silently rewriting the app onto SQL, are both serious failure modes. The encouraged path is
|
||||
migrating to Prisma Next — 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 Next side (verified against prisma/prisma-next @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`;
|
||||
status confirmed by the Prisma team 2026-07):
|
||||
|
||||
- **MongoDB support is Early Access**, actively developed, with GA planned after Postgres.
|
||||
- The implementation is deep, not a stub: a full package family (ORM, typed
|
||||
aggregation-pipeline builder, raw lane, driver over the official `mongodb` package),
|
||||
first-class contract-driven migrations, and extensive tests against real in-memory MongoDB.
|
||||
- **The Mongo client façade does not wrap `db.transaction(...)` yet** — multi-document
|
||||
atomicity is done through the MongoDB driver's session API, which is directly available
|
||||
(the `mongodb` package is a user-supplied peer dependency). A façade wrapper is expected;
|
||||
this skill will be updated when it merges.
|
||||
- Early Access means pre-1.0 minors can carry breaking changes, with published upgrade
|
||||
recipes (e.g. 0.11→0.12 changed Mongo validator emission and made `mongodb` a
|
||||
user-supplied peer dependency). Floor: 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 the façade wrapper lands.
|
||||
- **Check the MongoDB server version** (must be 8.0+ for Next; v6 tolerated older).
|
||||
- **Confirm the team can absorb pre-1.0 upgrades.** Next publishes versioned upgrade recipes
|
||||
between minors; someone has to run them. 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 Next, 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 Next's MongoDB is GA, or when blockers for trying EA are resolved.
|
||||
|
||||
## References
|
||||
|
||||
- [Prisma Next repository](https://github.com/prisma/prisma-next)
|
||||
- [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)
|
||||
@@ -0,0 +1,65 @@
|
||||
# migrations-mapping
|
||||
|
||||
How the v6 MongoDB "no migrations" story maps onto Prisma Next'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 Next MongoDB participates in the full migration lifecycle.
|
||||
Teams porting a `db push` habit into Next 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 Next: first-class, contract-driven migrations (Mongo included)
|
||||
|
||||
Migration authoring in Next is first-class for Postgres **and Mongo** (prisma-next
|
||||
`skills/prisma-next-migrations/SKILL.md`) — MongoDB is not a push-only special case:
|
||||
|
||||
- **Flow:** contract *emit* → diff → *plan* (writes a content-hashed migration package) →
|
||||
*migrate* (apply in graph order) → *verify* (live schema vs destination contract) →
|
||||
*sign* (advance the marker after a verify pass).
|
||||
- **Mongo migration ops** come from dedicated factories: `createCollection`,
|
||||
`dropCollection`, `validatedCollection`, `setValidation`, `createIndex`, `dropIndex`,
|
||||
`collMod`, and `dataTransform` for data backfills.
|
||||
- **Marker storage:** Next records migration state in a document in the
|
||||
`_prisma_migrations` collection (per space) — the same collection name family v6 users
|
||||
know from SQL, repurposed for Mongo state.
|
||||
- **DDL is not transactional on Mongo:** the runner applies operations, verifies the live
|
||||
schema against the destination contract, and only advances the marker on a verify pass —
|
||||
making interrupted runs resumable rather than atomic (see Prisma Next's
|
||||
`prisma-next-migrations` skill).
|
||||
- **Push-style alternative still exists:** `db update` diffs the live database against the
|
||||
contract and applies directly without writing a migration directory — the closest
|
||||
analogue to the v6 `db push` habit, at the cost of no history.
|
||||
- Validators: Next emits closed `$jsonSchema` validators by default since 0.12 (prisma-next
|
||||
`CHANGELOG.md`) — collections gain schema enforcement v6 never applied.
|
||||
|
||||
## Bad
|
||||
|
||||
```text
|
||||
Porting the v6 habit: run the Next equivalent of `db push` for every change in production,
|
||||
accumulating no migration history, and hand-editing collections when verification fails.
|
||||
```
|
||||
|
||||
## Good
|
||||
|
||||
```text
|
||||
Adopt the Next lifecycle: emit the contract, plan a migration package, apply it with
|
||||
migrate, let verify gate the marker, and sign. Reserve `db update` for local prototyping,
|
||||
mirroring how `db push` was used on v6.
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [v6: no Prisma Migrate for MongoDB](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)
|
||||
- Prisma Next migrations skill (`skills/prisma-next-migrations`) — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`
|
||||
@@ -0,0 +1,52 @@
|
||||
# schema-contract-mapping
|
||||
|
||||
How v6 MongoDB schema concepts map onto Prisma Next's contract model.
|
||||
|
||||
## Priority
|
||||
|
||||
HIGH
|
||||
|
||||
## Why It Matters
|
||||
|
||||
Prisma Next does not consume the v6 `schema.prisma` as-is: the schema becomes a *contract*
|
||||
(authored in PSL or TypeScript via the contract builder), and several v6 MongoDB idioms have
|
||||
different — or deliberately absent — equivalents. Translating mechanically without knowing
|
||||
the mapping produces contracts that fail verification or, worse, silently change collection
|
||||
addressing.
|
||||
|
||||
## The mapping
|
||||
|
||||
| v6 concept | Prisma Next equivalent | Notes |
|
||||
|------------|------------------------|-------|
|
||||
| `datasource db { provider = "mongodb" }` + `url = env(...)` ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#example)) | `defineConfig` from `@prisma-next/mongo/config` wiring the mongo family/target/adapter/driver descriptors | Next selects MongoDB by importing the `@prisma-next/mongo` façade, not by a provider string in the schema; `prisma-next init` accepts `mongodb` as a target name |
|
||||
| `@id @default(auto()) @map("_id") @db.ObjectId` ([using ObjectId](https://www.prisma.io/docs/orm/overview/databases/mongodb#using-objectid)) | ObjectId-typed id field in the Next contract (PSL or TS builder) | Verify the exact attribute surface against the installed Next version's `prisma-next-contract` skill — the contract builder also exposes `index` and `valueObject` |
|
||||
| Composite (embedded) types — MongoDB-only in v6 ([composite types](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types)) | Value objects / embedded shapes in the Next contract (`valueObject` in the Mongo contract builder) | Same conceptual role: documents embedded in a parent document |
|
||||
| Model names address the client (`prisma.user`) | **Collection storage names** address the ORM: `db.orm.users`, i.e. the `@@map(...)` name or the lowercased model name — not `db.orm.User` | prisma-next `skills/prisma-next/SKILL.md`, `skills/prisma-next-quickstart/SKILL.md`; the most common porting mistake |
|
||||
| Indexes declared in schema, applied by `db push` | Indexes are contract-declared and applied through migrations (`createIndex`/`dropIndex` factories) | See `migrations-mapping.md` |
|
||||
| No native polymorphism | No schema-layer polymorphism on Mongo either: `@@base`/`@@discriminator` are SQL-only in Next; model an explicit `discriminator` field | prisma-next `skills/prisma-next-contract/SKILL.md` |
|
||||
|
||||
## Bad
|
||||
|
||||
```typescript
|
||||
// Ported from v6 and addressed by model name:
|
||||
const user = await db.orm.User.first(); // undefined — Mongo ORM keys are storage names
|
||||
```
|
||||
|
||||
## Good
|
||||
|
||||
```typescript
|
||||
// Mongo ORM keys are collection storage names (@@map or lowercased model name):
|
||||
const user = await db.orm.users.first();
|
||||
```
|
||||
|
||||
## Environment requirements
|
||||
|
||||
Prisma Next's Mongo target requires MongoDB 8.0+ and `mongodb@^7` installed by the user as a
|
||||
peer dependency (prisma-next `CHANGELOG.md`, 0.11→0.12). v6 supports older MongoDB servers,
|
||||
so check the server version before planning a migration.
|
||||
|
||||
## References
|
||||
|
||||
- [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)
|
||||
- Prisma Next contract skill (`skills/prisma-next-contract`) in the prisma-next repository — authoritative for the Next side
|
||||
@@ -0,0 +1,60 @@
|
||||
# verify-cutover-checklist
|
||||
|
||||
Verification checklist for a v6 → Prisma Next cutover: the data never moves — only the code does.
|
||||
|
||||
## Priority
|
||||
|
||||
CRITICAL
|
||||
|
||||
## Why It Matters
|
||||
|
||||
A v6 → Next 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 Next 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 Next config points at the same connection string /
|
||||
database name the v6 app uses (minus v6-specific URL parameters that the `mongodb@^7`
|
||||
driver rejects — validate the URL with the driver first).
|
||||
2. **Server floor:** MongoDB server is 8.0+ (Next's requirement; v6 tolerated older).
|
||||
Confirm before authoring any contract.
|
||||
3. **Contract round-trip on a copy:** on a staging copy (or `mongodb-memory-server`), emit
|
||||
the contract, run plan → migrate → verify → sign, and confirm `verify` passes against
|
||||
data copied from production shape. Verification failures here are contract-mapping bugs,
|
||||
not database problems.
|
||||
4. **Index parity:** enumerate indexes on every collection (`db.collection.getIndexes()`)
|
||||
and confirm the Next 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:** Next 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
|
||||
driver-session equivalent (the `mongodb` driver is directly available; the façade wrapper
|
||||
is expected soon — see `client-api-mapping.md`).
|
||||
8. **Raw call inventory mapped:** every `$runCommandRaw` / `findRaw` / `aggregateRaw` call
|
||||
has an explicit Next-side replacement (`mongoRaw(...)` lane or pipeline builder).
|
||||
9. **Staged read-only soak:** run the Next stack read-only against staging/production data
|
||||
alongside v6 and compare outputs before allowing writes.
|
||||
10. **Cutover + rollback:** switch writes to Next 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, install and follow Prisma Next's own skills 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 Next migrations + queries skills — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`
|
||||
Reference in New Issue
Block a user