跳到主要内容

如何升级

概述​

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

升级文档​

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

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

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

  • 升级 Prisma 层：无论您的 Prisma 1 设置如何，您都应始终从遵循本指南开始升级过程。

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

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 绑定。
  • 通过更强大的内省功能，允许将 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 1 升级到 Prisma ORM 2.x 及更高版本时问题的简短描述
  • SQL：这可以通过对 SQL schema 进行非破坏性更改来解决吗？
  • Prisma schema：这可以通过对 Prisma ORM 2.x 及更高版本中的 schema 进行非破坏性更改来解决吗？
  • 破坏 Prisma 1：SQL 语句会破坏 Prisma 1 的设置吗？这仅在您选择逐步并行升级策略时相关。
问题SQLPrisma 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 进行内省。

Prisma CLI introspection flow

对于修复 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 及更高版本)。

Fixing the schema incompatibilities

请注意，升级 CLI 的设计方式是您可以随时停止和重新启动该过程。一旦您在数据库上运行了升级 CLI 生成的 SQL 命令，下次调用升级 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 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 层指南。

© . All rights reserved.