如何升级

概述

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

升级文档

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

• 如何升级（您在此处）：了解一般升级过程的起点。
• Schema 不兼容性：关于 Prisma 1 和 Prisma ORM 2.x（及更高版本）之间 Schema 不兼容性的参考页面。阅读此页面是可选的，但它将使您更好地理解升级过程中的某些步骤。

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

• 升级 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 schema，Prisma 1 数据模型和 prisma.yml 的合并。
• 使用其自己的 建模语言，而不是基于 GraphQL SDL。
• 不再公开 “数据库的 GraphQL API”，但仅允许通过 Prisma Client API 进行程序化访问。
  • 不再支持 Prisma ORM binding。
• 允许通过更强大的内省将 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 订阅，您可以考虑在您的mutation resolvers中手动触发订阅。

Schema 不兼容性

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

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

以下是不同列的概述

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

问题	SQL	Prisma schema	破坏 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 schema	否	是	否
CUID 长度不匹配	是	否	否
标量列表（数组）使用额外的表维护	取决于情况	否	取决于情况

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

Prisma 1 升级 CLI

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

在高层面上，使用升级 CLI 的升级工作流程如下所示。

对于初始设置

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

对于修复 schema 不兼容性

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

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

升级策略

有两种主要的升级策略

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

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

何时选择哪种策略

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

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

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

升级路径

无论您选择哪种策略，在高层面上，设想的升级路径如下所示

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

后续步骤

一旦您决定升级，请继续阅读 升级 Prisma ORM 层 指南。