如何升级
概述
本页帮助您了解何时以及如何从 Prisma 1 升级到 Prisma ORM 2.x 及更高版本，并做出明智的决定。
升级文档
升级文档包含多个页面，以下是使用这些页面的概述
- 如何升级 (您在这里): 了解升级过程的起点。
- Schema 不兼容性: 关于 Prisma 1 与 Prisma ORM 2.x（及更高版本）之间 schema 不兼容性的参考页面。阅读此页面是可选的，但能让您更好地理解升级过程中的某些步骤。
除了这两个页面外，还有各种实用指南，它们将引导您完成升级过程中的示例场景
- 升级 Prisma 层: 无论您的 Prisma 1 设置如何，您都应始终从遵循本指南开始升级过程。
完成该指南后，您可以选择以下四个指南之一来升级您的应用层
- 旧版到新版 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 Client 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 datamodel 和
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 订阅，可以考虑在变更解析器内部手动触发订阅。
Schema 不兼容性
在 Prisma 1 中运行 prisma deploy 时创建的数据库 schema 与 Prisma ORM 2.x 及更高版本创建的 schema 仅部分兼容。本节快速概述了常见的不兼容性以及可能的解决方法。
注意: 有关问题和相应解决方法的详细说明，请参阅Schema 不兼容性页面。
以下是不同列的概述
- 问题: 升级到 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 对多（缺少 UNIQUE 约束） | 是 | 否 | 否 |
| 所有非内联关系都被识别为多对多 | 是 | 否 | 是 |
Json 类型在数据库中表示为 TEXT | 是 | 否 | 否 (MySQL) 是 (PostgreSQL) |
枚举在数据库中表示为 TEXT | 是 | 否 | 否 (MySQL) 是 (PostgreSQL) |
| 必需的 1 对 1 关系未在数据库中体现 | 否 | 是 | 否 |
Prisma 1 的 @db 属性未迁移到 Prisma schema | 否 | 是 | 否 |
| CUID 长度不匹配 | 是 | 否 | 否 |
| 标量列表（数组）通过额外的表维护 | 取决于情况 | 否 | 取决于情况 |
注意: Prisma schema 中解决方法的普遍缺点是，在重新内省数据库后，对 Prisma schema 的更改会丢失，需要在每次内省运行后手动重新添加。
Prisma 1 Upgrade CLI
Prisma 1 Upgrade CLI 帮助您应用Schema 不兼容性页面中解释的解决方法。它生成 SQL 语句来修复数据库 schema，使其与 Prisma ORM 2.x 及更高版本兼容。请注意，您可以完全控制对数据库执行的操作，Upgrade CLI 只为您生成并打印语句。Upgrade CLI 还负责处理 Prisma schema 中的解决方法。
总体而言，使用 Upgrade CLI 的升级流程如下。
对于初始设置
- 您通过安装 Prisma ORM 2.x 及更高版本的 CLI 并运行
npx prisma init来设置 Prisma ORM。 - 您连接到数据库并使用
npx prisma db pull进行内省。
对于修复 schema 不兼容性
- 您使用
npx prisma-upgrade调用 Upgrade CLI。 - Upgrade CLI 为您生成要在数据库上运行的 SQL 命令。
- 您在数据库上运行 SQL 命令。
- 您再次运行
prisma db pull命令。 - 您再次运行
npx prisma-upgrade命令。 - Upgrade CLI 通过添加缺失的属性来调整 Prisma schema（2.x 及更高版本）。
请注意，Upgrade CLI 的设计方式是您可以随时停止和重新开始该过程。一旦您在数据库上运行了由 Upgrade CLI 生成的 SQL 命令，下次调用 Upgrade CLI 时，该 SQL 命令将不会再次出现。这样，您就可以在方便时逐步解决所有 schema 不兼容性。
升级策略
有两种主要的升级策略
- 一次性全部升级: 完全从项目中移除 Prisma 1，并将所有内容一次性迁移到 Prisma ORM 2.x 或更高版本。
- 渐进式并行升级: 将 Prisma ORM 2.x 及更高版本添加到现有的 Prisma 1 项目中，并逐步用新的 Prisma 特性替换现有的 Prisma 1 特性，同时让它们并行运行。
请注意，如果您计划让 Prisma 1 和 Prisma ORM 2.x 或更高版本并行运行，则此时不得解决会破坏 Prisma 1 设置的schema 兼容性问题。
何时选择哪种策略
如果您的项目尚未投入生产或流量和用户数据很少，建议采用一次性全部升级策略。
如果您的项目已经有大量流量且数据库中存储了大量用户数据，您可能需要考虑渐进式升级策略，即让 Prisma 1 和 Prisma ORM 2 或更高版本并行运行一段时间，直到您用 Prisma ORM 2 或更高版本替换所有旧的 Prisma 1 功能。
请注意，如果您选择渐进式升级策略并打算让 Prisma 1 和 Prisma ORM 2.x 或更高版本并行运行，则无法修复需要“破坏 Prisma 1”更改的schema 不兼容性问题。这是因为这些数据迁移会破坏 Prisma 1 期望的 schema。这意味着您的 Prisma Client API 可能不像本来那样符合习惯用法，但您仍然可以使用 Prisma Client 的全部功能。
升级路径
无论您选择哪种策略，总的来说，设想的升级路径如下所示
- 安装新的 Prisma ORM 2.x 或更高版本的 CLI 作为开发依赖。
- 创建 Prisma schema 并配置数据库连接 URL。
- 使用 Prisma ORM 2.x 或更高版本的 CLI 内省 Prisma 1 数据库并生成 Prisma schema。
- 运行 Prisma 1 Upgrade CLI 来“修复”Prisma schema。
- 安装并生成 Prisma Client 2.x 或更高版本。
- 调整应用程序代码，特别是用 Prisma Client 2.x 或更高版本的 API 调用替换 Prisma Client 1.0 的 API 调用。
下一步
决定升级后，请继续阅读升级 Prisma ORM 层指南。