Skip to main content

升级到 Prisma ORM 3

如果你从早期版本（任何 2.x 版本）升级，Prisma ORM 3 会引入许多重大更改，因此，了解此升级可能如何影响你的应用并进行任何必要的调整以确保平稳过渡非常重要。

¥Prisma ORM 3 introduces a number of breaking changes if you are upgrading from an earlier version (any 2.x version), therefore, it is important to understand how this upgrade might affect your application and make any needed adjustments to ensure a smooth transition.

你将在下面找到重大更改的列表以及如何处理它们。

¥Below you will find a list of the breaking changes and how to handle them.

重大变化​

¥Breaking changes

参考行动​

¥Referential actions

版本 3.x 中引用操作的引入消除了 Prisma Client 中先前阻止运行时级联删除的安全网。

¥The introduction of referential actions in version 3.x removes the safety net in Prisma Client that had previously prevented cascading deletes at runtime.

因此，根据你用于处理应用的工作流程，你可能会受到影响。我们建议你检查你的架构并决定是否需要显式定义引用操作。

¥As a result, depending on which workflow you are using to work on your application, you could be impacted. We advise you to check your schema and decide if you need to define referential actions explicitly.

请参阅 参考动作升级路径 了解如何继续。

¥See Referential action upgrade path to understand how to proceed.

命名约束​

¥Named constraints

我们更改了 Prisma ORM 所遵循的约定来命名约束和索引。我们还在 PSL 中引入了 map 属性（数据库级名称）和 name 属性（Prisma 客户端 API 名称）之间的明确区别，以明确控制如何在 Prisma 模式中定义约束。

¥We changed the convention followed by Prisma ORM to name constraints and indexes. We also introduced a clear distinction between the map attribute (database-level name) and name attribute (Prisma Client API name) in the PSL to explicitly control how constraints are defined in the Prisma schema.

这意味着你在运行遵循此新约定的 Prisma migrate 或 db pull 时会注意到影响。我们建议你调整架构以适当地反映约束和索引的名称。

¥This means that you will notice an impact when running Prisma migrate or db pull which will follow this new convention. We advise you to adjust your schema to reflect the names of your constraints and indexes appropriately.

你可以查看 命名约束升级路径 以获取有关如何继续的更多信息。

¥You can check out the Named constraints upgrade path for more information on how to proceed.

$queryRaw​

从版本 3.x 开始，$queryRaw 方法现在仅支持模板字面量。

¥From version 3.x onwards, the $queryRaw method now only supports a template literal.

这意味着，如果你的应用依赖于使用字符串的 $queryRaw 调用，那么这些调用将不再起作用。出于安全原因，我们建议你尽可能使用模板字面量，或者在小心转义查询以防止 SQL 注入之后，使用 $queryRawUnsafe。

¥This means that if your application relied on $queryRaw calls using strings, those calls will not work anymore. We advise you to use template literals wherever possible for security reasons or resort to $queryRawUnsafe otherwise, after carefully escaping queries to prevent SQL injections.

你可以在文档的 原始数据库访问 部分了解有关新 $queryRaw 和 $queryRawUnsafe 方法的更多信息。

¥You can learn more about the new $queryRaw and $queryRawUnsafe methods in the Raw database access section of the docs.

Json 空相等​

¥Json Null Equality

你不能按空值过滤 Json 字段。请参阅此 GitHub 问题。这是因为 { equals: null } 检查数据库中的列值是否为 NULL，而不是检查列内的 JSON 值是否等于 null。

¥You cannot filter a Json field by a null value. See this GitHub issue. This is because { equals: null } checks if the column value in the database is NULL, not if the JSON value inside the column equals null.

为了解决这个问题，我们决定将 Json 字段上的 null 拆分为 JsonNull、DbNull 和 AnyNull。

¥To fix this problem, we decided to split null on Json fields into JsonNull, DbNull and AnyNull.

  • 杰森空：选择 JSON 中的空值。

    ¥JsonNull: Selects the null value in JSON.

  • 数据库空：选择数据库中的 NULL 值。

    ¥DbNull: Selects the NULL value in the database.

  • 任何空值：选择空 JSON 值和空数据库值。

    ¥AnyNull: Selects both null JSON values and NULL database values.

给定 Prisma 架构中的以下模型：

¥Given the following model in your Prisma Schema:

model Log {
  id Int @id
  meta Json
}

从 3.0.1 开始，如果你尝试在 Json 字段上按 null 进行过滤，你将看到 TypeError：

¥Starting in 3.0.1, you'll see a TypeError if you try to filter by null on a Json field:

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: null
                ^ TypeError: Type 'null' is not assignable to type
        }
    },
  },
});

要解决此问题，你将导入并使用新的 null 类型之一：

¥To fix this, you'll import and use one of the new null types:

import { Prisma } from '@prisma/client'

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: Prisma.AnyNull,
      },
    },
  },
})

这也适用于 create、update 和 upsert。要将 null 值插入 Json 字段，你可以编写：

¥This also applies to create, update and upsert. To insert a null value into a Json field, you would write:

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.JsonNull,
  },
})

要将数据库 NULL 插入 Json 字段，你可以编写：

¥And to insert a database NULL into a Json field, you would write:

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.DbNull,
  },
})
warning

此 API 更改不适用于 MongoDB 连接器，其中 JSON null 和数据库 NULL 之间没有区别。

¥This API change does not apply to the MongoDB connector where there is not a difference between a JSON null and a database NULL.

它们也不适用于 array_contains 运算符，因为 JSON 数组中只能有 JSON null。由于 JSON 数组中不能存在数据库 NULL，因此 { array_contains: null } 没有歧义。

¥They also do not apply to the array_contains operator because there can only be a JSON null within an JSON array. Since there cannot be a database NULL within a JSON array, { array_contains: null } is not ambiguous.

具体升级路径​

¥Specific upgrade paths

将 prisma 和 @prisma/client 软件包升级到 Prisma ORM 3​

¥Upgrading the prisma and @prisma/client packages to Prisma ORM 3

要从版本 2.x 升级到 3.x，你需要更新 prisma 和 @prisma/client 软件包。prisma 和 @prisma/client 软件包安装时在其版本号中都带有脱字符号 ^，以防止重大更改。

¥To upgrade from version 2.x to 3.x, you need to update both the prisma and @prisma/client packages. Both the prisma and @prisma/client packages install with a caret ^ in their version number to safe guard against breaking changes.

要忽略插入符 ^ 并跨主要版本升级，可以在使用 npm 或 yarn 升级时使用 @3 标签。

¥To ignore the caret ^ and upgrade across major versions, you can use the @3 tag when upgrading with npm, or yarn .

danger

升级之前，请检查每个重大更改，以了解升级可能如何影响你的应用。

¥Before upgrading, check each breaking change to see how the upgrade might affect your application.

npm install prisma@3 @prisma/client@3