如何升级

概述

¥Overview

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

¥This page helps you make an informed decision on when and how to upgrade from Prisma 1 to Prisma ORM version 2.x and later.

升级文档

¥Upgrade documentation

升级文档由几页组成，以下是如何使用它们的概述：

¥The upgrade documentation consists of several pages, here's an overview of how to use them:

• 如何升级（你在这里）：了解一般升级过程的起点。

  ¥How to upgrade (you are here): Starting point to learn about the upgrade process in general.

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

  ¥Schema incompatibilities: A reference page about the schema incompatibilities between Prisma 1 and Prisma ORM 2.x (and later versions). Reading this page is optional but it will give you a better understanding of certain steps in the upgrade process.

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

¥In addition to these two pages, there are various practical guides that walk you through an example scenario of the upgrade process:

• 升级 Prisma 层：无论你的 Prisma 1 设置如何，你都应该始终按照本指南开始升级过程。

  ¥Upgrading the Prisma layer: No matter what your Prisma 1 setup looks like, you should always start your upgrade process by following this guide.

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

¥Once you're done with that guide, you can choose one of the following four guides to upgrade your application layer:

• 从旧到新的 Nexus：如果你当前正在使用 GraphQL Nexus 运行 Prisma 1，请选择本指南。

  ¥Old to new Nexus: Choose this guide if you're currently running Prisma 1 with GraphQL Nexus.

• prisma 绑定到 Nexus：如果你当前正在运行带有 prisma-binding 的 Prisma 1 并且想要升级到 关系，请选择本指南。

  ¥prisma-binding to Nexus: Choose this guide if you're currently running Prisma 1 with prisma-binding and want to upgrade to Nexus.

• prisma 绑定到 SDL 优先：如果你当前正在运行带有 prisma-binding 的 Prisma 1 并且想要升级到 SDL 优先 GraphQL 服务器，请选择本指南。

  ¥prisma-binding to SDL-first: Choose this guide if you're currently running Prisma 1 with prisma-binding and want to upgrade to an SDL-first GraphQL server.

• 剩余 API：如果你当前正在使用 Prisma Client 1 运行 Prisma 1 并正在构建 REST API，请选择本指南。

  ¥REST API: Choose this guide if you're currently running Prisma 1 using Prisma Client 1 and are building a REST API.

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

¥Main differences between Prisma 1 and Prisma ORM version 2.x and later

从高层次来看，Prisma 1 和 Prisma ORM 版本 2.x 及更高版本之间的最大差异总结如下。

¥On a high-level, the biggest differences between Prisma 1 and Prisma ORM versions 2.x and later are summarized below.

Prisma ORM 2.x 及更高版本：

¥Prisma ORM 2.x and later versions:

• 不需要托管数据库代理服务器（即 Prisma 服务器）。

  ¥don't require hosting a database proxy server (i.e., the Prisma server).

• 使 Prisma 1 的功能更加模块化，并将其拆分为专用工具：

  ¥make the features of Prisma 1 more modular and splits them into dedicated tools:

  • Prisma 客户端：Prisma Client 1.0 的改进版本

    ¥Prisma Client: An improved version of Prisma Client 1.0

  • Prisma 迁移：数据建模和迁移（以前称为 prisma deploy）。

    ¥Prisma Migrate: Data modeling and migrations (formerly prisma deploy).

• 使用 Prisma 架构，Prisma 1 数据模型和 prisma.yml 的合并。

  ¥use the Prisma schema, a merge of Prisma 1 datamodel and prisma.yml.

• 使用自己的 建模语言，而不是基于 GraphQL SDL。

  ¥use its own modeling language instead of being based on GraphQL SDL.

• 不再公开 "适用于你的数据库的 GraphQL API"，但仅允许通过 Prisma 客户端 API 进行编程访问。

  ¥don't expose "a GraphQL API for your database" anymore, but only allows for programmatic access via the Prisma Client API.

  • 不再支持 Prisma ORM 绑定。

    ¥don't support Prisma ORM binding any more.

• 允许通过更强大的内省将 Prisma ORM 2.x 及更高版本连接到任何现有数据库

  ¥allows connecting Prisma ORM 2.x and later version to any existing database, via more powerful introspection

功能对等

¥Feature parity

Prisma ORM 2.x 及更高版本尚未具有与 Prisma 1 相同的完整功能。Prisma ORM 2.x 及更高版本仍然缺少的最大功能是实时订阅。

¥Prisma ORM 2.x and later versions do not yet have full feature parity with Prisma 1. The biggest feature that is still missing from Prisma ORM versions 2.x and later is real-time subscriptions.

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

  ¥Real-time API (Subscriptions): Prisma ORM version 2.x and later currently doesn't have a way to subscribe to events happening in the database and get notified in real time. It is currently unclear if, when, and in what form a real-time API will be added to Prisma ORM versions 2.x and later. For the time being, you can implement real-time functionality using native database triggers, or if you're using GraphQL subscriptions you can consider triggering subscriptions manually inside your mutation resolvers.

架构不兼容

¥Schema incompatibilities

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

¥The database schema that is created when running prisma deploy in Prisma 1 is only partially compatible with the one that Prisma ORM versions 2.x and later creates. This section gives a quick overview of the general incompatibilities and the potential workarounds. -

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

¥Note: For a detailed explanation of the problems and respective workarounds, please refer to the Schema incompatibilities page.

以下是不同列的概述：

¥Here's an overview of the different columns:

• 问题：从 Prisma 1 升级到 Prisma ORM 版本 2.x 及更高版本时出现的问题的简短描述

  ¥Problem: A short description of the problem when upgrading from Prisma 1 to Prisma ORM versions 2.x and later

• SQL:是否可以通过对 SQL 架构进行不间断更改来解决这个问题？

  ¥SQL: Can this be solved by making a non-breaking change to the SQL schema?

• Prisma 架构：可以通过对 Prisma ORM 2.x 及更高版本中的架构进行不间断更改来解决这个问题吗？

  ¥Prisma schema: Can this be solved by making a non-breaking change to the schema in Prisma ORM versions 2.x and later?

• 打破 Prisma 1：SQL 语句是否会破坏 Prisma 1 设置？仅当你选择渐进并排 升级策略 时，这才有意义。

  ¥Breaking Prisma 1: Do the SQL statements break the Prisma 1 setup? This is only relevant when you're choosing the gradual side-by-side upgrade strategy.

问题	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 架构的更改会丢失 需要在每次内省运行后手动重新添加。

¥Note: A general drawback with the workarounds in the Prisma schema is that changes to the Prisma schema get lost after re-introspecting the database and need to be re-added manually after each introspection run.

Prisma 1 升级 CLI

¥Prisma 1 Upgrade CLI

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

¥The Prisma 1 Upgrade CLI helps you apply the workarounds that are explained on the Schema incompatibilities page. It generates the SQL statements to fix the database schema and make it compatible with Prisma ORM versions 2.x and later. Note that you are in full control over the operations that are executed against your database, the Upgrade CLI only generates and prints the statements for you. The Upgrade CLI also takes care of the workarounds in the Prisma schema.

从总体上看，使用升级 CLI 的升级工作流程如下所示。

¥On a high-level, the upgrade workflow using the Upgrade CLI looks as follows.

对于初始设置：

¥For the initial setup:

1. 你可以通过安装 Prisma ORM 版本 2.x 和更高版本的 CLI 并运行 npx prisma init 来设置 Prisma ORM。

   ¥You set up Prisma ORM by installing the Prisma ORM versions 2.x and later CLI and running npx prisma init.

2. 你连接到数据库并使用 npx prisma db pull 进行内省。

   ¥You connect to your database and introspect it with npx prisma db pull.

为了修复架构不兼容性：

¥For fixing the schema incompatibilities:

1. 你使用 npx prisma-upgrade 调用升级 CLI。

   ¥You invoke the Upgrade CLI with npx prisma-upgrade.

2. 升级 CLI 生成 SQL 命令供你在数据库上运行。

   ¥The Upgrade CLI generates SQL commands for you to run on your database.

3. 你对数据库运行 SQL 命令。

   ¥You run the SQL commands against your database.

4. 你再次运行 prisma db pull 命令。

   ¥You run the prisma db pull command again.

5. 你再次运行 npx prisma-upgrade 命令。

   ¥You run the npx prisma-upgrade command again.

6. 升级 CLI 通过添加缺少的属性来调整 Prisma 架构（版本 2.x 及更高版本）。

   ¥The Upgrade CLI adjusts the Prisma schema (version 2.x and later) by adding missing attributes.

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

¥Note that the Upgrade CLI is designed in a way that you can stop and re-start the process at any time. Once you ran a SQL command that was generated by the Upgrade CLI against your database, the SQL command will not show up the next time you invoke the Upgrade CLI. That way, you can gradually resolve all schema incompatibilities when it's convenient for you.

升级策略

¥Upgrade strategies

主要有两种升级策略：

¥There are two main upgrade strategies:

• 一次性升级：从你的项目中完全删除 Prisma 1，并将所有内容立即转移到 Prisma ORM 版本 2.x 或更高版本。

  ¥Upgrade all at once: Entirely remove Prisma 1 from your project and move everything over to Prisma ORM version 2.x or later at once.

• 并行逐步升级：将 Prisma ORM 版本 2.x 及更高版本添加到现有的 Prisma 1 项目中，并逐步用较新的 Prisma 功能替换现有的 Prisma 1 功能，同时并行运行它们。

  ¥Gradual upgrade side-by-side: Add Prisma ORM version 2.x and later to the existing Prisma 1 project and gradually replace existing Prisma 1 features with the newer Prisma features while running them side-by-side.

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

¥Note that if you are planning to run Prisma 1 and Prisma ORM 2.x or later version side-by-side, you must not yet resolve the schema compatibilities that are breaking the Prisma 1 setup.

何时选择哪种策略

¥When to choose which strategy

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

¥If your project is not yet running in production or has little traffic and user data, the all at once strategy is recommended.

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

¥In case your project already sees a lot of traffic and has a lot of user data stored in the database, you might want to consider the gradual upgrade strategy where you're running Prisma 1 and Prisma ORM 2 or later side-by-side for a certain amount of time until you've replace all former Prisma 1 functionality with Prisma ORM 2 or later version.

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

¥Note that you won't be able to fix the schema incompatibilities that require a "Breaking Prisma 1" change if you choose the gradual upgrade strategy and intend to run Prisma 1 and Prisma ORM version 2.x or later side-by-side. That's because these data migrations are breaking the schema that Prisma 1 expects. This means that your Prisma Client API might not feel as idiomatic as it could, but you still get the full feature set of Prisma Client.

升级路径

¥Upgrade path

无论你选择哪种策略，从高层次来看，设想的升级路径如下：

¥No matter which of the strategies you choose, on a high-level the envisioned upgrade path looks as follows:

1. 安装新的 Prisma ORM 版本 2.x 或更高版本的 CLI 作为开发依赖

   ¥Install the new Prisma ORM version 2.x or later CLI as a development dependency

2. 创建 Prisma 架构并配置数据库连接 URL

   ¥Create your Prisma schema and configure the database connection URL

3. 使用 Prisma ORM 版本 2.x 或更高版本的 CLI 内省你的 Prisma 1 数据库并生成 Prisma 架构

   ¥Use the Prisma ORM version 2.x or later CLI to introspect your Prisma 1 database and generate your Prisma schema

4. 运行 Prisma 1 升级 CLI 到 "fix" Prisma 架构

   ¥Run the Prisma 1 Upgrade CLI to "fix" the Prisma schema

5. 安装并生成 Prisma 客户端版本 2.x 或更高版本

   ¥Install and generate Prisma Client version 2.x or later

6. 调整你的应用代码，特别是将 Prisma Client 1.0 中的 API 调用替换为 Prisma Client 2.x 或更高版本的 API 调用

   ¥Adjust your application code, specifically replace the API calls from the Prisma Client 1.0 with those of Prisma Client version 2.x or later

下一步

¥Next steps

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

¥Once you've made the decision to upgrade, continue with the Upgrading the Prisma ORM layer guide.