feat: add prisma-mongodb-upgrade skill (#20)

tensordreams · web-flow · commit 72aa5e3b6fea · 2026-07-10T16:36:42.000+02:00
* feat: add prisma-mongodb-upgrade skill

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 &lt;robot@aqrln.net&gt;

* 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 &lt;robot@aqrln.net&gt;

* docs: soften the example dialogue line per review suggestion

Signed-off-by: Alexey Orlenko's AI Agent &lt;robot@aqrln.net&gt;

* docs: clarify MongoDB upgrade path

Signed-off-by: Alexey Orlenko's AI Agent &lt;robot@aqrln.net&gt;

---------

Signed-off-by: Alexey Orlenko's AI Agent &lt;robot@aqrln.net&gt;
diff --git 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
@@ -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
@@ -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.
diff --git a/prisma-mongodb-upgrade/references/client-api-mapping.md b/prisma-mongodb-upgrade/references/client-api-mapping.md
@@ -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`
diff --git a/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md b/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md
@@ -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)
diff --git a/prisma-mongodb-upgrade/references/migrations-mapping.md 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 (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`
diff --git a/prisma-mongodb-upgrade/references/schema-contract-mapping.md b/prisma-mongodb-upgrade/references/schema-contract-mapping.md
diff --git a/prisma-mongodb-upgrade/references/verify-cutover-checklist.md b/prisma-mongodb-upgrade/references/verify-cutover-checklist.md
diff --git a/prisma-upgrade-v7/SKILL.md b/prisma-upgrade-v7/SKILL.md

Original file line number	Diff line number	Diff line change
`@@ -170,7 +170,7 @@ generator client {`
`170`	`170`	`}`
`171`	`171`	```
`172`	`172`
`173`		-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.
	`173`	+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).
`174`	`174`
`175`	`175`	`## Rule Files`
`176`	`176`