docs: add MongoDB migration guide from v6 to Prisma Next

[RaschidJFR]

Added mongodb.mdx under /docs/guides/next/upgrade-prisma-orm/mongodb

Summary by CodeRabbit

• Documentation
  • Added a new Prisma ORM upgrade guide for MongoDB.
  • Documented migration steps from Prisma v6 to Prisma Next, including setup, schema conversion, client APIs, queries, transactions, raw operations, and connection handling.
  • Added guidance for migration workflows, production readiness, prerequisites, and known MongoDB considerations.
  • Added the new guide to the Next documentation navigation.

[vercel]

@RaschidJFR is attempting to deploy a commit to the Prisma Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

Adds a published “Upgrade Prisma ORM” guide for migrating Prisma v6 MongoDB projects to Prisma Next, covering setup, contracts, client APIs, migration commands, production cutover, and ongoing workflows.

Changes

MongoDB migration documentation

Layer / File(s)	Summary
Migration scope and project setup apps/docs/content/docs/guides/next/meta.json, apps/docs/content/docs/guides/next/upgrade-prisma-orm/meta.json, apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx	Adds the guide to navigation, defines its metadata, and documents prerequisites, MongoDB configuration, contract generation, and Prisma Next runtime initialization.
Contract and schema translation apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx	Maps Prisma v6 MongoDB schema concepts to Prisma Next contracts, including storage names, ObjectId identifiers, indexes, uniques, and polymorphic models.
Client operations and runtime APIs apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx	Documents Prisma Next CRUD, relation, polymorphism, aggregation, transaction, and raw-operation replacements for Prisma v6 APIs.
Migration lifecycle and cutover apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx	Documents database update and migration commands, verification, signing, production pre-flight checks, cutover, rollback, and post-migration workflows.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a MongoDB migration guide from Prisma v6 to Prisma Next.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx`:
- Around line 388-401: Update the pre-flight checklist in the migration guide to
restore the two missing safety checks: verify the configuration uses the same
database and connection string as v6, and verify MongoDB is version 8.0 or
newer. Keep the existing checklist items and wording unchanged otherwise.
- Around line 334-364: Update the raw-command documentation around the
“Commands” section and Quick reference table to document the existing
db.query.rawCommand(...) API for supported whole-command operations. Replace the
inaccurate mongo({ mongoClient, dbName, contractJson }) reference, while keeping
arbitrary generic commands described separately through the standalone
MongoClient example; ensure the surrounding prose and table consistently match
these examples.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bcee30fb-3643-44bc-a44c-199dd8d2ee41

📥 Commits

Reviewing files that changed from the base of the PR and between 324e21f and a8fcfb6.

📒 Files selected for processing (4)

• MIGRATION.md
• apps/docs/content/docs/guides/next/meta.json
• apps/docs/content/docs/guides/next/upgrade-prisma-orm/meta.json
• apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx

[ankur-arch]

Validated this guide end to end against @prisma-next/mongo@0.16.0: a Prisma v6 app (CRUD, groupBy, findRaw/aggregateRaw, $runCommandRaw, $transaction) running on a mongodb-memory-server 8.0.4 replica set, then migrated following the guide literally. Everything in sections 1-3 held up as written except two things, both fixed in 50e24b1 along with the CodeRabbit feedback:

1. Step 4 didn't work on a populated v6 database. db init refuses to add validators to existing collections (classed destructive), and migration plan/migrate baseline from empty, so the prechecks fail against existing collections. The verified adoption path is db update --db ... --advance-ref db (previews with --dry-run, prompts on the validator adds, signs the database), with plan/migrate/verify for every change after that. Step 4 is restructured around that flow and the checklist rehearsal commands now match.
2. The 3c aggregation example silently returned []. The typed pipeline builder passes ObjectId values through as plain strings, so .match((f) => f.authorId.eq(authorId)) matches nothing. The example no longer filters on an ObjectId field and a warning documents the working escape: db.query.rawCommand(new RawAggregateCommand(...)) with a real ObjectId, or the ORM client which encodes ids correctly (verified for both _id and foreign keys).

Also aligned the snippets with what prisma-next init actually scaffolds (./contract.d import, non-null env assertions), documented that every discriminator value present in existing data needs a declared variant (the strict validators reject undeclared values on write, and a variant needs at least one field), and made the $runCommandRaw mapping consistent: share one MongoClient with the binding via mongo({ contractJson, mongoClient, dbName }), verified working. pnpm --filter docs lint:links passes; the docs typecheck failure is the pre-existing @prisma/eclipse resolution issue, not this page.

🤖 Generated with Claude Code

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx (1)

299-319: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Close caller-owned MongoClient instances explicitly.

A binding constructed with mongoClient does not close the client when db.close() is called; the caller owns that pool. The transaction example also creates a local driver client without closing it after the session.

• apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx#L299-L319: close client after await session.endSession().
• apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx#L365-L366: document closing mongoClient during application shutdown or script teardown.
• apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx#L393-L393: distinguish URL-owned db.close() from externally owned mongoClient.close().

Proposed fix

 } finally {
   await session.endSession();
+  await client.close();
 }

-| `$connect` / `$disconnect` | lazy connect on first use; `db.close()` to disconnect |
+| `$connect` / `$disconnect` | lazy connect on first use; use `db.close()` for a URL-bound client, or `mongoClient.close()` when supplying `mongoClient` |

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx` around
lines 299 - 319, Update the MongoDB documentation at
apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx lines 299-319
to close the locally created client after session.endSession() in the
transaction example. At lines 365-366, document that externally supplied
mongoClient instances must be closed during application shutdown or script
teardown. At line 393, distinguish URL-owned db.close() cleanup from explicitly
calling mongoClient.close() for externally owned clients.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx`:
- Around line 299-319: Update the MongoDB documentation at
apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx lines 299-319
to close the locally created client after session.endSession() in the
transaction example. At lines 365-366, document that externally supplied
mongoClient instances must be closed during application shutdown or script
teardown. At line 393, distinguish URL-owned db.close() cleanup from explicitly
calling mongoClient.close() for externally owned clients.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2dadefb1-fe3d-4a2b-9b60-b3cb6d8823c8

📥 Commits

Reviewing files that changed from the base of the PR and between a8fcfb6 and 50e24b1.

📒 Files selected for processing (1)

• apps/docs/content/docs/guides/next/upgrade-prisma-orm/mongodb.mdx

[ankur-arch]

@coderabbitai resolve

[coderabbitai]

✅ Action performed

Comments resolved and changes approved.