prisma-mongodb-upgrade

Prisma MongoDB 升级路径

MongoDB 项目是 Prisma 中唯一没有通往 Prisma 7 的路径的用户群：v6 是 MongoDB 经典 ORM 的最后一个主版本，v7 永远不会发布 MongoDB 连接器。后续路径是 Prisma 8，其中 MongoDB 支持处于早期访问阶段，而 PostgreSQL 已是候选版本。官方的 Prisma ORM 6 升级到 8（MongoDB）指南是迁移步骤的权威来源。本技能阐明真正需要做出的选择——迁移到 Prisma 8（推荐路径），或在存在硬性阻碍时留在 v6——并介绍迁移机制。

绝不要做以下任何一项：

• 绝不要建议 MongoDB 项目“升级到 Prisma 7”。那里不存在这个连接器。prisma-upgrade-v7 指南不适用于 MongoDB 项目。
• 绝不要通过将应用改写为使用 SQL 数据库来解决版本问题。更换数据库引擎是一个独立且规模大得多的决定，你不能擅自替用户做出。

版本概况

版本	MongoDB 状态
Prisma ORM v6	完全支持（mongodb provider）；最新的 6.x 是当前稳定路径；维护分支
Prisma ORM v7	没有 MongoDB 连接器——永远不可选
Prisma 8	通过 @prisma/orm-mongo 提供 MongoDB 早期访问支持；候选版本之间仍会变化——MongoDB 项目的后续路径

先说结论

推荐迁移到 Prisma 8。 Prisma 8 的 MongoDB 支持处于早期访问阶段：功能可用且快速迭代——Prisma 团队希望 MongoDB 用户尽早迁移并分享反馈。迁移机制详见参考资料。

在存在硬性阻碍时，继续使用最新的 v6 仍是合理选择——明确来说：Prisma 8 目前还没有 MongoDB 事务方法（多文档写入直接使用 mongodb 驱动的会话），而且 MongoDB 行为在 Prisma 8 的候选版本之间仍可能变化。

决策表

信号	方向
不存在以下任何阻碍	迁移到 Prisma 8；运行 verify-cutover-checklist 并与 Prisma 团队分享反馈
绿地项目／原型／内部工具	迁移到 Prisma 8
代码库使用多文档事务（$transaction）——用 grep 检查，不要询问	先规划原始驱动会话的等效实现（参见 client-api-mapping），或留在 v6，直到 Prisma 8 添加 MongoDB 事务方法
团队无法应对候选版本之间的破坏性变更	留在 v6，直到 MongoDB 支持结束早期访问
风险偏好保守但有兴趣	使用 v6 schema，通过 prisma6Schema(...) 配置 Prisma 8（参见 schema-contract-mapping），在副本上演练（参见 verify-cutover-checklist），然后迁移

注意：本节将在 Prisma 8 添加 MongoDB 事务方法后更新。

如果留在 v6：维护规范（有意选择留下，而非疏于维护）

• 将 Prisma 软件包固定在最新的 6.x 分支，并持续采用 6.x 补丁版本。
• 关注 Prisma 6.x 分支的发行说明和安全公告。
• 保持经典的 v6 MongoDB 设置：在 schema 中使用 url = env("DATABASE_URL")，采用 db push 工作流，不使用 SQL 驱动适配器（参见 prisma-orm-setup 了解 v6 MongoDB 的配置形式）。
• 当 Prisma 8 的 MongoDB 支持结束早期访问，或相关阻碍得到解决时，重新评估。

参考文件

参考	涵盖内容
references/decision-stay-or-migrate.md	完整的决策框架、阻碍项检查和保持现状的卫生细节
references/schema-contract-mapping.md	v6 架构（mongodb 提供程序、@db.ObjectId、复合类型）→ Prisma 8 契约概念
references/client-api-mapping.md	v6 客户端调用 → Prisma 8 对应项，包括原始操作的逃生口和事务——名称可映射，功能一致性则不保证
references/migrations-mapping.md	v6 仅使用 db push 的方式 → Prisma 8 的规划／迁移／验证／签核流程
references/verify-cutover-checklist.md	不迁移数据的验证：同一数据库、索引一致性、切换前分阶段往返验证

验证依据

本技能中关于 Prisma 8 的说明已对照 Prisma ORM 6 to 8 (MongoDB) 指南进行核验。该指南针对 @prisma/orm-mongo 8.0.0-rc.13 编写；同时也对照了 prisma/orm 仓库中的 prisma-8 技能，版本为提交 75c1460515fa2f11971533f6a1dec5dab35d4123。MongoDB 支持仍会随候选发行版变化：采取任何 Prisma 8 相关操作前，请检查已安装的版本 （npm ls @prisma/orm-mongo）及其同步的 prisma-8 技能。

MongoDB 上的 Prisma 8 要求 Node.js 22.18+（24 系列需 24.11+；推荐 24）、TypeScript 5.9+、MongoDB 8.0+，并将 mongodb@7 作为对等依赖。mongodb@7 驱动不再接受连接字符串中的 AWS 凭据。

交接规则

本技能是发现阶段的桥梁，不能替代 Prisma 8 自身的文档。项目切换到 Prisma 8 后，运行 prisma skills sync，阅读同步后的 prisma-8/SKILL.md，并在日常工作中遵循其中的说明——不要继续依赖本技能中的摘要开展工作。