prisma-mongodb-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prisma MongoDB Upgrade Path

Prisma MongoDB 升级路径

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, 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.

MongoDB项目是唯一无法升级到Prisma 7的Prisma用户群体：v6是面向MongoDB的经典ORM最终大版本，v7从未推出MongoDB连接器。后续路径是Prisma Next，其中MongoDB支持处于Early Access（早期访问）阶段，计划在Postgres之后正式发布（GA）。本指南明确了核心决策——迁移至Prisma Next（推荐路径），或是在存在硬性阻碍时停留在v6，并介绍了迁移机制。

绝对不要做以下两件事：

切勿建议MongoDB项目“升级到Prisma 7”。该版本中不存在MongoDB连接器，
```
prisma-upgrade-v7
```
指南不适用于MongoDB项目。
切勿通过将应用重写为SQL数据库来解决版本问题。更换数据库引擎是一个独立且规模大得多的决策，不应由你擅自决定。

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

版本	MongoDB状态
Prisma ORM v6	完全支持（ `mongodb` provider）；最新6.x版本为当前稳定路径；处于维护阶段
Prisma ORM v7	无MongoDB连接器——永远不可选
Prisma Next	MongoDB支持处于Early Access阶段，正在积极开发中，计划在Postgres之后正式发布（GA）——是MongoDB项目的后续路径

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.

迁移至Prisma Next是推荐路径。Prisma Next中的MongoDB支持处于Early Access阶段：功能可用且迭代迅速，计划在Postgres之后正式发布（GA）——Prisma团队希望MongoDB用户尽早迁移并反馈意见。迁移机制详情见参考文件。

在存在硬性阻碍时，停留在最新v6版本仍是合理选择——明确来说：Next的Mongo封装目前尚不支持事务（底层驱动可直接使用；预计此情况很快会改变），且1.0之前的小版本可能包含破坏性变更，并会发布对应的升级方案。

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.

信号	方向
不存在以下阻碍	迁移至Next；执行 `verify-cutover-checklist` 并向Prisma团队反馈意见
新项目/原型/内部工具	迁移至Next
代码库使用多文档事务（ `$transaction` ）——需通过grep检查，不要询问	先规划原生驱动会话的替代方案（见 `client-api-mapping` ），或停留在v6直到封装支持事务
团队无法承受1.0之前小版本间的破坏性升级	停留在v6直到正式发布（GA）
风险厌恶但有迁移意向	在副本上执行分阶段Next往返测试（见 `verify-cutover-checklist` ），然后再迁移

注意：事务缺口预计很快会填补——当Prisma Next的封装事务合并后，本节内容将更新。

If staying on v6: hygiene (a deliberate stay, not neglect)

若停留在v6：维护规范（主动选择，而非忽视）

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.

将Prisma包固定在最新6.x版本系列，并持续安装6.x补丁版本。
关注Prisma 6.x版本系列的发布说明和安全公告。
保留经典v6 MongoDB配置：schema中设置
```
url = env("DATABASE_URL")
```
，使用
```
db push
```
工作流，不使用SQL驱动适配器（v6 MongoDB配置详情见
```
prisma-database-setup
```
）。
当Prisma Next的MongoDB支持正式发布（GA），或是尝试Early Access的阻碍消除时，重新评估迁移方案。

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

参考文件	涵盖内容
`references/decision-stay-or-migrate.md`	完整的决策框架、阻碍检查及停留在v6的维护细节
`references/schema-contract-mapping.md`	v6 schema（ `mongodb` provider、 `@db.ObjectId` 、复合类型）→ Next契约概念的映射
`references/client-api-mapping.md`	v6客户端调用→ Next等效方法的映射，包括原生逃逸舱和事务——名称对应，但功能一致性不对应
`references/migrations-mapping.md`	v6仅 `db push` 的流程→ Next的plan/migrate/verify/sign流程的映射
`references/verify-cutover-checklist.md`	无数据迁移验证：相同数据库、索引一致性、切换前的分阶段往返测试

Verified against

验证依据

Behavioral claims about Prisma Next in this skill were verified against 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.

本指南中关于Prisma Next的行为声明已针对prisma/prisma-next的提交

a2791c5dd59d579b4b3052942ae7f8fe5e2ee852

（1.0之前，约v0.14/0.15版本系列）进行验证。Prisma Next在Early Access阶段迭代迅速：在依据Next相关声明采取行动前，请针对实际安装的版本进行验证（检查项目的

@prisma-next/*

版本及安装的prisma-next技能）。Next的Mongo目标要求MongoDB 8.0+，并期望用户提供

mongodb@^7

作为peer依赖。

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.

本指南是发现阶段的桥梁，不能替代Prisma Next自身的文档。项目切换到Prisma Next后，运行Prisma Next的

init

/技能安装，并遵循其自身的技能（快速入门、契约、查询、迁移、运行时）进行日常工作——不要继续依赖本指南的摘要内容。