如何升级

概述

此页面帮助您在何时以及如何从 Prisma 1 升级到 Prisma ORM 2.x 及更高版本方面做出明智的决策。

升级文档

升级文档包含多个页面，以下是使用它们的概述

• 如何升级（您当前所在位置）：了解升级过程总体情况的起点。
• 模式不兼容性：关于 Prisma 1 和 Prisma ORM 2.x（以及更高版本）之间模式不兼容性的参考页面。阅读此页面是可选的，但它将使您更好地理解升级过程中的某些步骤。

除了这两个页面之外，还有各种实用指南引导您完成升级过程的示例场景

• 升级 Prisma 层：无论您的 Prisma 1 设置是什么样的，您都应该始终遵循本指南开始升级过程。

完成该指南后，您可以选择以下四个指南之一来升级您的应用程序层

• 旧版 Nexus 到新版 Nexus：如果您当前正在使用 GraphQL Nexus 运行 Prisma 1，请选择本指南。
• prisma-binding 到 Nexus：如果您当前正在使用 prisma-binding 运行 Prisma 1，并且想要升级到Nexus，请选择本指南。
• prisma-binding 到 SDL-first：如果您当前正在使用 prisma-binding 运行 Prisma 1，并且想要升级到SDL-first GraphQL 服务器，请选择本指南。
• REST API：如果您当前正在使用 Prisma Client 1 运行 Prisma 1 并且正在构建 REST API，请选择本指南。

Prisma 1 与 Prisma ORM 2.x 及更高版本之间的主要区别

从高级别来看，Prisma 1 与 Prisma ORM 2.x 及更高版本之间的最大区别总结如下。

Prisma ORM 2.x 及更高版本

• 不需要托管数据库代理服务器（即Prisma 服务器）。
• 使 Prisma 1 的功能更加模块化，并将其拆分为专用工具
  • Prisma Client：Prisma Client 1.0 的改进版本
  • Prisma Migrate：数据建模和迁移（以前为 prisma deploy）。
• 使用Prisma 模式，这是 Prisma 1 数据模型和 prisma.yml 的合并。
• 使用其自己的建模语言，而不是基于 GraphQL SDL。
• 不再公开“数据库的 GraphQL API”，而只允许通过 Prisma Client API 进行编程访问。
  • 不再支持 Prisma ORM 绑定。
• 允许通过更强大的内省将 Prisma ORM 2.x 及更高版本连接到任何现有的数据库

功能奇偶校验

Prisma ORM 2.x 及更高版本尚未与 Prisma 1 完全功能奇偶校验。Prisma ORM 2.x 及更高版本中仍然缺少的最大功能是实时订阅。

• 实时 API（订阅）：Prisma ORM 2.x 及更高版本目前没有方法订阅数据库中发生的事件并实时收到通知。目前尚不清楚是否、何时以及以何种形式将实时 API 添加到 Prisma ORM 2.x 及更高版本中。目前，您可以使用本机数据库触发器实现实时功能，或者如果您使用的是 GraphQL 订阅，您可以考虑在您的变异解析器中手动触发订阅。

模式不兼容性

在 Prisma 1 中运行 prisma deploy 时创建的数据库模式仅与 Prisma ORM 2.x 及更高版本创建的数据库模式部分兼容。本节概述了常见的不兼容性和潜在的解决方法。-

注意：有关问题和相应解决方法的详细说明，请参阅模式不兼容性页面。

以下是不同列的概述

• 问题：从 Prisma 1 升级到 Prisma ORM 2.x 及更高版本时出现的问题的简要描述
• SQL：可以通过对 SQL 模式进行非破坏性更改来解决此问题吗？
• Prisma 模式：可以通过对 Prisma ORM 2.x 及更高版本中的模式进行非破坏性更改来解决此问题吗？
• 破坏 Prisma 1：SQL 语句是否会破坏 Prisma 1 设置？这仅在您选择逐步并行升级策略时才相关。

问题	SQL	Prisma 模式	破坏 Prisma 1
数据库中未表示默认值	是	是	否
数据库中未表示作为 ID 值生成的 CUID	否	是	否
数据库中未表示 @createdAt	是	是	否
数据库中未表示 @updatedAt	否	是	否
内联 1-1 关系被识别为 1-n（缺少 UNIQUE 约束）	是	否	否
所有非内联关系都被识别为 m-n	是	否	是
Json 类型在数据库中表示为 TEXT	是	否	否（MySQL） 是（PostgreSQL）
枚举在数据库中表示为 TEXT	是	否	否（MySQL） 是（PostgreSQL）
数据库中未表示必需的 1-1 关系	否	是	否
Prisma 1 中的 @db 属性未传输到 Prisma 模式	否	是	否
CUID 长度不匹配	是	否	否
标量列表（数组）使用额外表维护	取决于	否	取决于

注意：Prisma 模式中解决方法的普遍缺点是，重新内省数据库后，对 Prisma 模式的更改会丢失，并且需要在每次内省运行后手动重新添加。

Prisma 1 升级 CLI

该Prisma 1 升级 CLI可帮助您应用在模式不兼容性页面上解释的解决方法。它生成用于修复数据库模式并使其与 Prisma ORM 2.x 及更高版本兼容的 SQL 语句。请注意，您可以完全控制对数据库执行的操作，升级 CLI 仅为您生成并打印语句。升级 CLI 还负责 Prisma 模式中的解决方法。

从高级别来看，使用升级 CLI 的升级工作流程如下所示。

对于初始设置

1. 您通过安装 Prisma ORM 2.x 及更高版本 CLI 并运行 npx prisma init 来设置 Prisma ORM。
2. 您连接到数据库并使用 npx prisma db pull 对其进行内省。

对于修复模式不兼容性

1. 您使用 npx prisma-upgrade 调用升级 CLI。
2. 升级 CLI 会为您生成要在数据库上运行的 SQL 命令。
3. 您在数据库上运行 SQL 命令。
4. 您再次运行 prisma db pull 命令。
5. 您再次运行 npx prisma-upgrade 命令。
6. 升级 CLI 通过添加缺失的属性来调整 Prisma 模式（2.x 及更高版本）。

请注意，升级 CLI 的设计方式是您可以随时停止并重新启动该过程。一旦您对数据库运行了由升级 CLI 生成的 SQL 命令，则下次调用升级 CLI 时，该 SQL 命令将不会显示。这样，您就可以在方便的时候逐步解决所有模式不兼容性。

升级策略

主要有两种升级策略

• 一次性升级：完全从您的项目中删除 Prisma 1，并将所有内容一次性迁移到 Prisma ORM 2.x 或更高版本。
• 逐步并行升级：将 Prisma ORM 2.x 及更高版本添加到现有的 Prisma 1 项目中，并在并行运行它们的同时，逐步用更新的 Prisma 功能替换现有的 Prisma 1 功能。

请注意，如果您计划并行运行 Prisma 1 和 Prisma ORM 2.x 或更高版本，则必须尚未解决破坏 Prisma 1 设置的模式兼容性。

何时选择哪种策略

如果您的项目尚未在生产环境中运行或流量和用户数据很少，则建议使用一次性策略。

如果您的项目已经看到大量流量并且在数据库中存储了大量用户数据，您可能需要考虑逐步升级策略，在该策略中，您并行运行 Prisma 1 和 Prisma ORM 2 或更高版本一段时间，直到您用 Prisma ORM 2 或更高版本替换所有以前的 Prisma 1 功能。

请注意，如果您选择逐步升级策略并打算并行运行 Prisma 1 和 Prisma ORM 2.x 或更高版本，则您将无法修复需要“破坏 Prisma 1”更改的模式不兼容性。这是因为这些数据迁移破坏了 Prisma 1 预期的模式。这意味着您的 Prisma Client API 可能感觉不像它可能的那样惯用，但您仍然可以获得 Prisma Client 的完整功能集。

升级路径

无论您选择哪种策略，从高级别来看，设想的升级路径如下所示

1. 将新的 Prisma ORM 2.x 或更高版本 CLI 作为开发依赖项安装
2. 创建您的 Prisma 模式并配置数据库连接 URL
3. 使用 Prisma ORM 2.x 或更高版本 CLI 对您的 Prisma 1 数据库进行内省并生成您的 Prisma 模式
4. 运行Prisma 1 升级 CLI以“修复”Prisma 模式
5. 安装并生成 Prisma Client 2.x 或更高版本
6. 调整您的应用程序代码，特别是将 Prisma Client 1.0 的 API 调用替换为 Prisma Client 2.x 或更高版本的 API 调用

后续步骤

做出升级决定后，请继续使用升级 Prisma ORM 层指南。