如何升级

概述

此页面将帮助您了解何时以及如何从 Prisma 1 升级到 Prisma ORM 2.x 及更高版本。

升级文档

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

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

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

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

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

• 旧 Nexus 到新 Nexus：如果您当前正在运行 Prisma 1 和 GraphQL Nexus，请选择此指南。
• prisma-binding 到 Nexus：如果您当前正在运行 Prisma 1 和 prisma-binding，并且想要升级到 Nexus，请选择此指南。
• prisma-binding 到 SDL-first：如果您当前正在运行 Prisma 1 和 prisma-binding，并且想要升级到 SDL-first GraphQL 服务器，请选择此指南。
• REST API：如果您当前正在使用 Prisma 客户端 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 客户端：Prisma 客户端 1.0 的改进版本
  • Prisma Migrate：数据建模和迁移（以前是 prisma deploy）。
• 使用 Prisma 架构，它合并了 Prisma 1 数据模型和 prisma.yml。
• 使用其自身的 建模语言，而不是基于 GraphQL SDL。
• 不再公开 "用于数据库的 GraphQL API"，而只允许通过 Prisma 客户端 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
默认值未在数据库中表示	是	是	否
生成的 CUID 作为 ID 值未在数据库中表示	否	是	否
@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 帮助您应用在 架构不兼容性 页面上解释的解决方法。它会生成 SQL 语句来修复数据库架构并使其与 Prisma ORM 2.x 及更高版本兼容。请注意，您完全控制对数据库执行的操作，升级 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 命令，该 SQL 命令在下一次调用升级 CLI 时将不会显示。这样，您就可以在方便的时候逐步解决所有模式不兼容问题。

升级策略

主要有两种升级策略

• **一次性升级**：完全从您的项目中删除 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 版本 2.x 或更高版本中的 API 调用替换 Prisma Client 1.0 中的 API 调用

后续步骤

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