From 8932c0e2a27bc04d99cf241e14929fbca66cf5a1 Mon Sep 17 00:00:00 2001 From: Alexey Orlenko's AI Agent Date: Mon, 6 Jul 2026 12:04:26 +0200 Subject: [PATCH 1/4] feat: add prisma-mongodb-upgrade skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MongoDB projects are the one Prisma cohort with no path to Prisma 7 (v6 is the terminal classic-ORM major for MongoDB; v7 ships no connector). Agents routinely mis-advise these projects: recommending an impossible v7 upgrade or silently rewriting apps onto SQL. This skill frames the real decision — stay on the latest v6 deliberately (the default for production today) or migrate to Prisma Next — and carries the migration mechanics: schema-to-contract mapping, client API mapping including the raw lanes and the transactions gap, migrations story, and a no-data-moves cutover checklist. Prisma Next claims are verified against prisma/prisma-next at commit a2791c5dd59d579b4b3052942ae7f8fe5e2ee852; v6 claims cite released v6 documentation. Cross-links added: prisma-upgrade-v7 and prisma-database-setup now route MongoDB version questions to this skill, and the README gains the skill entry. Signed-off-by: Alexey Orlenko's AI Agent --- README.md | 18 ++++ prisma-database-setup/SKILL.md | 2 +- prisma-mongodb-upgrade/SKILL.md | 90 +++++++++++++++++++ .../references/client-api-mapping.md | 55 ++++++++++++ .../references/decision-stay-or-migrate.md | 87 ++++++++++++++++++ .../references/migrations-mapping.md | 65 ++++++++++++++ .../references/schema-contract-mapping.md | 52 +++++++++++ .../references/verify-cutover-checklist.md | 60 +++++++++++++ prisma-upgrade-v7/SKILL.md | 8 +- 9 files changed, 435 insertions(+), 2 deletions(-) create mode 100644 prisma-mongodb-upgrade/SKILL.md create mode 100644 prisma-mongodb-upgrade/references/client-api-mapping.md create mode 100644 prisma-mongodb-upgrade/references/decision-stay-or-migrate.md create mode 100644 prisma-mongodb-upgrade/references/migrations-mapping.md create mode 100644 prisma-mongodb-upgrade/references/schema-contract-mapping.md create mode 100644 prisma-mongodb-upgrade/references/verify-cutover-checklist.md diff --git a/README.md b/README.md index 41c86d7..852739a 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,23 @@ Step-by-step migration guide from Prisma v6 to v7, covering all breaking changes --- +### prisma-mongodb-upgrade + +Decision and migration guide for MongoDB projects on Prisma v6, which have no path to Prisma 7. + +**Use when:** +- A MongoDB project asks about upgrading Prisma versions +- Evaluating a move from Prisma v6 to Prisma Next +- Preventing an impossible "upgrade MongoDB to v7" plan + +**Topics covered:** +- The version landscape (v6 terminal for MongoDB; v7 has no connector; Prisma Next is the successor path) +- Stay-on-v6 vs migrate-now decision table with no-go signals +- Schema/contract, client API, and migrations mapping between v6 and Prisma Next +- No-data-moves cutover verification checklist + +--- + ### prisma-client-api Comprehensive Prisma Client API reference. @@ -160,6 +177,7 @@ Or install specific skills: ```bash npx skills add prisma/skills --skill prisma-cli npx skills add prisma/skills --skill prisma-upgrade-v7 +npx skills add prisma/skills --skill prisma-mongodb-upgrade npx skills add prisma/skills --skill prisma-client-api npx skills add prisma/skills --skill prisma-driver-adapter-implementation npx skills add prisma/skills --skill prisma-database-setup diff --git a/prisma-database-setup/SKILL.md b/prisma-database-setup/SKILL.md index 1de91a6..51643e7 100644 --- a/prisma-database-setup/SKILL.md +++ b/prisma-database-setup/SKILL.md @@ -170,7 +170,7 @@ generator client { } ``` -For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup. +For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup. If a MongoDB project asks about upgrading Prisma versions, route to the `prisma-mongodb-upgrade` skill (stay-on-v6 vs Prisma Next is the real decision; Prisma 7 is not an option). ## Rule Files diff --git a/prisma-mongodb-upgrade/SKILL.md b/prisma-mongodb-upgrade/SKILL.md new file mode 100644 index 0000000..0d3cdfd --- /dev/null +++ b/prisma-mongodb-upgrade/SKILL.md @@ -0,0 +1,90 @@ +--- +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), which has a working MongoDB target +in active development. This skill frames the real decision — stay on v6 deliberately, or +migrate to Prisma Next now — and carries the migration mechanics for teams that choose to +move. + +**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 production path; maintenance line | +| Prisma ORM v7 | **No MongoDB connector — not an option, ever** | +| Prisma Next | MongoDB target exists and is well-built, but is roadmap-classified as a POC: pre-1.0, Early Access at best, excluded from the current EA/GA target sets | + +## The decision, up front + +**Default: production MongoDB apps stay on Prisma v6 today — deliberately, not by neglect.** +Prisma Next's own roadmap classifies its MongoDB target as a proof-of-concept and excludes it +from the Early Access and GA target sets; its package line is pre-1.0 with breaking changes +between minors; and its Mongo client façade does not yet expose transactions. + +**The migrate-now branch is real** and mechanically detailed in the references — appropriate +for greenfield projects, experiments, and teams that knowingly accept Early Access churn. + +### Decision table + +| Signal | Direction | +|--------|-----------| +| Production app, availability matters | Stay on v6 | +| App uses multi-document transactions (`$transaction`) | **Stay on v6 — hard no-go for Next today** (the Next Mongo façade has no `db.transaction(...)`; only raw driver sessions) | +| Team cannot absorb pre-1.0 breaking upgrades between minors | Stay on v6 | +| Greenfield / prototype / internal tool | Migrating to Next now is reasonable | +| Team wants to be early on the successor stack and can track releases | Migrate now, with the verification checklist | +| Curious but risk-averse | Stay on v6; run a staged Next round-trip on a copy (see `verify-cutover-checklist`) and revisit each quarter | + +### Stay-on-v6 hygiene (the default is active, not passive) + +- 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). +- Put a revisit date on the decision (e.g. quarterly): the trigger to re-evaluate is Prisma + Next's MongoDB target entering the officially supported Early Access/GA set and façade + transactions landing. + +## Reference files + +| Reference | What it covers | +|-----------|----------------| +| `references/decision-stay-or-migrate.md` | The full decision framing, no-go signals, 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 is Early +Access and its surface moves: **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. diff --git a/prisma-mongodb-upgrade/references/client-api-mapping.md b/prisma-mongodb-upgrade/references/client-api-mapping.md new file mode 100644 index 0000000..6ec38f1 --- /dev/null +++ b/prisma-mongodb-upgrade/references/client-api-mapping.md @@ -0,0 +1,55 @@ +# 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 are not wrapped at all. 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.` | prisma-next `packages/2-mongo-family/5-query-builders/orm/src/collection.ts` | +| `prisma.user.aggregate(...)`, `groupBy(...)` | **No ORM equivalent.** Use the typed aggregation-pipeline builder: `db.query.from(...).match(...).group(...).build()` | prisma-next `skills/prisma-next-queries/SKILL.md` ("Mongo ORM aggregates" gap) | +| `$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 `RawMongoCollection` with `aggregate`, `insertOne/Many`, `updateOne/Many`, `deleteOne/Many`, `findOneAndUpdate/Delete` | prisma-next `packages/2-mongo-family/5-query-builders/orm/src/mongo-raw.ts`; there is no general run-any-command method — check the installed version | +| `.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 | +| `.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)) | **Not wrapped.** The Next Mongo façade exposes no `db.transaction(...)`; multi-document atomicity requires the MongoDB driver's session API directly | prisma-next `skills/prisma-next-runtime/SKILL.md`, `skills/prisma-next-queries/SKILL.md`; treat as a migrate-now no-go signal if the app needs it | +| `$connect` / `$disconnect` | `connect()` / `close()` on the Mongo façade client | prisma-next `packages/3-extensions/mongo/src/runtime/mongo.ts` | + +## 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's session API (not wrapped by Next). +``` + +## 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` diff --git a/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md new file mode 100644 index 0000000..4348d64 --- /dev/null +++ b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md @@ -0,0 +1,87 @@ +# decision-stay-or-migrate + +How to decide between staying on Prisma v6 and migrating a MongoDB project to Prisma Next. + +## Priority + +CRITICAL + +## Why It Matters + +MongoDB projects cannot follow the general "upgrade Prisma" advice: Prisma 7 has no MongoDB +connector, so the only forward path is Prisma Next — which is Early Access. Advising a +production team onto a pre-1.0 stack, or silently rewriting their app onto SQL, are both +serious failure modes. The correct default today is a deliberate stay on v6. + +## The facts the decision rests on + +Prisma Next side (verified against prisma/prisma-next @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`): + +- The MongoDB target is one of two roadmap **POCs** ("validating that non-SQL targets work + within the framework"); the Early Access target set is Postgres plus one SQL database, and + GA is Postgres-only — MongoDB is in neither (`ROADMAP.md`, `README.md`). +- The implementation itself 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 has no `db.transaction(...)`** — multi-document atomicity + requires the MongoDB driver's session API directly (prisma-next + `skills/prisma-next-queries/SKILL.md`, `skills/prisma-next-runtime/SKILL.md`). +- Pre-1.0 churn is real: the 0.11→0.12 release changed Mongo validator emission and made + `mongodb` a user-supplied peer dependency (`CHANGELOG.md`); floor is 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)). + +## No-go signals for migrating now + +Treat each of these as a hard stop for the migrate-now branch: + +- **The app relies on `$transaction` / multi-document atomicity.** Next's Mongo façade does + not wrap transactions yet; the only workaround is hand-written raw driver sessions. +- **The team cannot absorb pre-1.0 breaking upgrades.** Next publishes versioned upgrade + recipes between minors; someone has to run them. +- **The operator has not explicitly accepted Early Access status.** Do not migrate a + production app to a POC-classified target on your own initiative. + +## 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, and never will — v6 is the last classic-ORM +major for MongoDB. Your real options are: (a) stay on the latest 6.x deliberately (the +right default for production today), or (b) migrate to Prisma Next, the successor, whose +MongoDB target is functional but Early Access. Does your app use $transaction? That is +currently a no-go for Next..." +``` + +## 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). +- Schedule a revisit (quarterly is reasonable). Re-evaluate when Prisma Next's MongoDB + target joins the supported EA/GA set and façade transactions land. + +## References + +- [Prisma Next repository (roadmap, README)](https://github.com/prisma/prisma-next) +- [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb) diff --git a/prisma-mongodb-upgrade/references/migrations-mapping.md b/prisma-mongodb-upgrade/references/migrations-mapping.md new file mode 100644 index 0000000..dd6791f --- /dev/null +++ b/prisma-mongodb-upgrade/references/migrations-mapping.md @@ -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 (prisma-next + `packages/3-mongo-target/1-mongo-target/src/core/mongo-runner.ts`). +- **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` diff --git a/prisma-mongodb-upgrade/references/schema-contract-mapping.md b/prisma-mongodb-upgrade/references/schema-contract-mapping.md new file mode 100644 index 0000000..f649a45 --- /dev/null +++ b/prisma-mongodb-upgrade/references/schema-contract-mapping.md @@ -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 `packages/3-extensions/mongo/src/config/define-config.ts`); `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 diff --git a/prisma-mongodb-upgrade/references/verify-cutover-checklist.md b/prisma-mongodb-upgrade/references/verify-cutover-checklist.md new file mode 100644 index 0000000..66b3299 --- /dev/null +++ b/prisma-mongodb-upgrade/references/verify-cutover-checklist.md @@ -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 is empty:** grep the v6 app for `$transaction`; each hit must be + redesigned (raw driver sessions) or the migration deferred — there is no façade + equivalent in Next today (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` diff --git a/prisma-upgrade-v7/SKILL.md b/prisma-upgrade-v7/SKILL.md index 1ac08b9..5ad44d3 100644 --- a/prisma-upgrade-v7/SKILL.md +++ b/prisma-upgrade-v7/SKILL.md @@ -41,9 +41,15 @@ Reference this skill when: - `removed-features` - removed middleware, metrics, and legacy CLI behavior - `accelerate-users` - migration notes for Accelerate users +## Using MongoDB? This guide does not apply + +Prisma 7 has no MongoDB connector. Do not apply any step in this guide to a project with +`provider = "mongodb"` — see the `prisma-mongodb-upgrade` skill for the actual decision +(stay on v6 deliberately vs migrate to Prisma Next). + ## Important Notes -- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path +- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`) - **Node.js 20.19.0+** required - **TypeScript 5.4.0+** required - **Latest stable Prisma ORM version**: `7.6.0` From 57574e369dfc080c3dffbe5d747d3c72b5921c20 Mon Sep 17 00:00:00 2001 From: Alexey Orlenko's AI Agent Date: Mon, 6 Jul 2026 16:42:48 +0200 Subject: [PATCH 2/4] docs: reframe mongodb skill around Early Access status Correct the maturity framing per review: MongoDB support in Prisma Next is Early Access with GA planned after Postgres, and migrating is the encouraged path for MongoDB users; staying on v6 remains a legitimate choice where hard blockers apply, stated without discouraging framing. Blocker questions become agent self-checks (grep for $transaction instead of asking the user). Transactions guidance now states affirmatively that the underlying mongodb driver is directly available for sessions today, with the facade wrapper expected soon. Internal prisma-next source paths removed from user-facing prose in favor of Prisma Next's own skills. Signed-off-by: Alexey Orlenko's AI Agent --- prisma-mongodb-upgrade/SKILL.md | 52 ++++++++-------- .../references/client-api-mapping.md | 22 ++++--- .../references/decision-stay-or-migrate.md | 60 +++++++++---------- .../references/migrations-mapping.md | 4 +- .../references/schema-contract-mapping.md | 2 +- .../references/verify-cutover-checklist.md | 6 +- 6 files changed, 77 insertions(+), 69 deletions(-) diff --git a/prisma-mongodb-upgrade/SKILL.md b/prisma-mongodb-upgrade/SKILL.md index 0d3cdfd..99e1be7 100644 --- a/prisma-mongodb-upgrade/SKILL.md +++ b/prisma-mongodb-upgrade/SKILL.md @@ -11,10 +11,10 @@ metadata: 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), which has a working MongoDB target -in active development. This skill frames the real decision — stay on v6 deliberately, or -migrate to Prisma Next now — and carries the migration mechanics for teams that choose to -move. +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:** @@ -27,46 +27,48 @@ move. | Version | MongoDB status | |---------|----------------| -| Prisma ORM v6 | Fully supported (`mongodb` provider); latest 6.x is the current production path; maintenance line | +| 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 target exists and is well-built, but is roadmap-classified as a POC: pre-1.0, Early Access at best, excluded from the current EA/GA target sets | +| Prisma Next | MongoDB support in **Early Access**, actively developed, GA planned after Postgres — the successor path for MongoDB projects | ## The decision, up front -**Default: production MongoDB apps stay on Prisma v6 today — deliberately, not by neglect.** -Prisma Next's own roadmap classifies its MongoDB target as a proof-of-concept and excludes it -from the Early Access and GA target sets; its package line is pre-1.0 with breaking changes -between minors; and its Mongo client façade does not yet expose transactions. +**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. -**The migrate-now branch is real** and mechanically detailed in the references — appropriate -for greenfield projects, experiments, and teams that knowingly accept Early Access churn. +**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 | |--------|-----------| -| Production app, availability matters | Stay on v6 | -| App uses multi-document transactions (`$transaction`) | **Stay on v6 — hard no-go for Next today** (the Next Mongo façade has no `db.transaction(...)`; only raw driver sessions) | -| Team cannot absorb pre-1.0 breaking upgrades between minors | Stay on v6 | -| Greenfield / prototype / internal tool | Migrating to Next now is reasonable | -| Team wants to be early on the successor stack and can track releases | Migrate now, with the verification checklist | -| Curious but risk-averse | Stay on v6; run a staged Next round-trip on a copy (see `verify-cutover-checklist`) and revisit each quarter | +| 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 | -### Stay-on-v6 hygiene (the default is active, not passive) +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). -- Put a revisit date on the decision (e.g. quarterly): the trigger to re-evaluate is Prisma - Next's MongoDB target entering the officially supported Early Access/GA set and façade - transactions landing. +- 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, no-go signals, and stay-hygiene detail | +| `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 | @@ -76,8 +78,8 @@ for greenfield projects, experiments, and teams that knowingly accept Early Acce 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 is Early -Access and its surface moves: **before acting on any Next-side claim, verify it against the +`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. diff --git a/prisma-mongodb-upgrade/references/client-api-mapping.md b/prisma-mongodb-upgrade/references/client-api-mapping.md index 6ec38f1..242d2bd 100644 --- a/prisma-mongodb-upgrade/references/client-api-mapping.md +++ b/prisma-mongodb-upgrade/references/client-api-mapping.md @@ -10,8 +10,9 @@ CRITICAL 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 are not wrapped at all. Assuming parity produces code that does not compile — -or, in the transactions case, code that silently loses atomicity. +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 @@ -19,13 +20,13 @@ or, in the transactions case, code that silently loses atomicity. |---------|------------------------|-------| | `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.` | prisma-next `packages/2-mongo-family/5-query-builders/orm/src/collection.ts` | -| `prisma.user.aggregate(...)`, `groupBy(...)` | **No ORM equivalent.** Use the typed aggregation-pipeline builder: `db.query.from(...).match(...).group(...).build()` | prisma-next `skills/prisma-next-queries/SKILL.md` ("Mongo ORM aggregates" gap) | -| `$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 `RawMongoCollection` with `aggregate`, `insertOne/Many`, `updateOne/Many`, `deleteOne/Many`, `findOneAndUpdate/Delete` | prisma-next `packages/2-mongo-family/5-query-builders/orm/src/mongo-raw.ts`; there is no general run-any-command method — check the installed version | +| `create` / `update` / `upsert` / `delete` / `updateMany` / `deleteMany` | `create` / `update` / `upsert` / `delete` / `updateAll` / `deleteAll` on `db.orm.` | 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 | | `.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 | | `.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)) | **Not wrapped.** The Next Mongo façade exposes no `db.transaction(...)`; multi-document atomicity requires the MongoDB driver's session API directly | prisma-next `skills/prisma-next-runtime/SKILL.md`, `skills/prisma-next-queries/SKILL.md`; treat as a migrate-now no-go signal if the app needs it | -| `$connect` / `$disconnect` | `connect()` / `close()` on the Mongo façade client | prisma-next `packages/3-extensions/mongo/src/runtime/mongo.ts` | +| `$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 @@ -45,7 +46,12 @@ 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's session API (not wrapped by Next). +// 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 diff --git a/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md index 4348d64..d186ee4 100644 --- a/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md +++ b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md @@ -1,6 +1,6 @@ # decision-stay-or-migrate -How to decide between staying on Prisma v6 and migrating a MongoDB project to Prisma Next. +How to decide between migrating a MongoDB project to Prisma Next and staying on Prisma v6. ## Priority @@ -9,26 +9,27 @@ CRITICAL ## Why It Matters MongoDB projects cannot follow the general "upgrade Prisma" advice: Prisma 7 has no MongoDB -connector, so the only forward path is Prisma Next — which is Early Access. Advising a -production team onto a pre-1.0 stack, or silently rewriting their app onto SQL, are both -serious failure modes. The correct default today is a deliberate stay on v6. +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`): +Prisma Next side (verified against prisma/prisma-next @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`; +status confirmed by the Prisma team 2026-07): -- The MongoDB target is one of two roadmap **POCs** ("validating that non-SQL targets work - within the framework"); the Early Access target set is Postgres plus one SQL database, and - GA is Postgres-only — MongoDB is in neither (`ROADMAP.md`, `README.md`). -- The implementation itself is deep, not a stub: a full package family (ORM, typed +- **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 has no `db.transaction(...)`** — multi-document atomicity - requires the MongoDB driver's session API directly (prisma-next - `skills/prisma-next-queries/SKILL.md`, `skills/prisma-next-runtime/SKILL.md`). -- Pre-1.0 churn is real: the 0.11→0.12 release changed Mongo validator emission and made - `mongodb` a user-supplied peer dependency (`CHANGELOG.md`); floor is MongoDB 8.0 and - `mongodb@^7`. +- **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: @@ -38,16 +39,17 @@ Prisma v6 side: - 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)). -## No-go signals for migrating now +## Blocker checks before migrating -Treat each of these as a hard stop for the migrate-now branch: +Run these checks yourself — from the codebase, not by asking the user: -- **The app relies on `$transaction` / multi-document atomicity.** Next's Mongo façade does - not wrap transactions yet; the only workaround is hand-written raw driver sessions. -- **The team cannot absorb pre-1.0 breaking upgrades.** Next publishes versioned upgrade - recipes between minors; someone has to run them. -- **The operator has not explicitly accepted Early Access status.** Do not migrate a - production app to a POC-classified target on your own initiative. +- **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 @@ -64,10 +66,9 @@ steps corrupt a working v6 setup. ```text User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?" Agent: "Prisma 7 does not support MongoDB, and never will — v6 is the last classic-ORM -major for MongoDB. Your real options are: (a) stay on the latest 6.x deliberately (the -right default for production today), or (b) migrate to Prisma Next, the successor, whose -MongoDB target is functional but Early Access. Does your app use $transaction? That is -currently a no-go for Next..." +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 @@ -78,10 +79,9 @@ Staying is a decision, not a default-by-neglect: - 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). -- Schedule a revisit (quarterly is reasonable). Re-evaluate when Prisma Next's MongoDB - target joins the supported EA/GA set and façade transactions land. +- Re-evaluate when Prisma Next's MongoDB is GA, or when blockers for trying EA are resolved. ## References -- [Prisma Next repository (roadmap, README)](https://github.com/prisma/prisma-next) +- [Prisma Next repository](https://github.com/prisma/prisma-next) - [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb) diff --git a/prisma-mongodb-upgrade/references/migrations-mapping.md b/prisma-mongodb-upgrade/references/migrations-mapping.md index dd6791f..c666428 100644 --- a/prisma-mongodb-upgrade/references/migrations-mapping.md +++ b/prisma-mongodb-upgrade/references/migrations-mapping.md @@ -36,8 +36,8 @@ Migration authoring in Next is first-class for Postgres **and Mongo** (prisma-ne 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 (prisma-next - `packages/3-mongo-target/1-mongo-target/src/core/mongo-runner.ts`). + 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. diff --git a/prisma-mongodb-upgrade/references/schema-contract-mapping.md b/prisma-mongodb-upgrade/references/schema-contract-mapping.md index f649a45..fae18bb 100644 --- a/prisma-mongodb-upgrade/references/schema-contract-mapping.md +++ b/prisma-mongodb-upgrade/references/schema-contract-mapping.md @@ -18,7 +18,7 @@ addressing. | 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 `packages/3-extensions/mongo/src/config/define-config.ts`); `prisma-next init` accepts `mongodb` as a target name | +| `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 | diff --git a/prisma-mongodb-upgrade/references/verify-cutover-checklist.md b/prisma-mongodb-upgrade/references/verify-cutover-checklist.md index 66b3299..43144c3 100644 --- a/prisma-mongodb-upgrade/references/verify-cutover-checklist.md +++ b/prisma-mongodb-upgrade/references/verify-cutover-checklist.md @@ -40,9 +40,9 @@ the cutover observable and reversible. 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 is empty:** grep the v6 app for `$transaction`; each hit must be - redesigned (raw driver sessions) or the migration deferred — there is no façade - equivalent in Next today (see `client-api-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 From 80fd2763a177fc2be3d220168e08b5a8cc0cb063 Mon Sep 17 00:00:00 2001 From: Alexey Orlenko's AI Agent Date: Mon, 6 Jul 2026 17:34:01 +0200 Subject: [PATCH 3/4] docs: soften the example dialogue line per review suggestion Signed-off-by: Alexey Orlenko's AI Agent --- prisma-mongodb-upgrade/references/decision-stay-or-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md index d186ee4..93feda2 100644 --- a/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md +++ b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md @@ -65,7 +65,7 @@ steps corrupt a working v6 setup. ```text User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?" -Agent: "Prisma 7 does not support MongoDB, and never will — v6 is the last classic-ORM +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..." From 8ac75fdc794a58bcd59256f4edd1eae0df644f21 Mon Sep 17 00:00:00 2001 From: Alexey Orlenko's AI Agent Date: Thu, 9 Jul 2026 17:47:28 +0200 Subject: [PATCH 4/4] docs: clarify MongoDB upgrade path Signed-off-by: Alexey Orlenko's AI Agent --- prisma-upgrade-v7/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prisma-upgrade-v7/SKILL.md b/prisma-upgrade-v7/SKILL.md index 5ad44d3..23d4956 100644 --- a/prisma-upgrade-v7/SKILL.md +++ b/prisma-upgrade-v7/SKILL.md @@ -49,7 +49,7 @@ Prisma 7 has no MongoDB connector. Do not apply any step in this guide to a proj ## Important Notes -- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`) +- **MongoDB projects should stay on Prisma 6.x or migrate to Prisma Next** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`) - **Node.js 20.19.0+** required - **TypeScript 5.4.0+** required - **Latest stable Prisma ORM version**: `7.6.0`