跳到主要内容

升级到 Prisma ORM 3

如果您从早期版本（任何 2.x 版本）升级，Prisma ORM 3 会引入一些**破坏性变更**。因此，了解本次升级可能如何影响您的应用程序并进行任何必要的调整以确保顺利过渡非常重要。

下面列出了这些破坏性变更以及如何处理它们。

破坏性变更​

引用操作​

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

因此，取决于您用于开发应用程序的工作流，您可能会受到影响。我们建议您检查您的 Schema 并决定是否需要显式定义引用操作。

请参阅引用操作升级路径以了解如何操作。

命名约束​

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

这意味着当您运行 Prisma migrate 或 db pull 时会注意到影响，因为它们将遵循这一新约定。我们建议您调整您的 Schema 以适当地反映您的约束和索引名称。

您可以查看命名约束升级路径了解更多操作信息。

$queryRaw​

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

这意味着如果您的应用程序依赖于使用*字符串*的 $queryRaw 调用，这些调用将**不再**起作用。出于安全考虑，我们建议您尽可能使用模板字面量，否则请改用 $queryRawUnsafe，并在使用前仔细转义查询以防止 SQL 注入。

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

Json Null Equality​

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

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

  • JsonNull：选择 JSON 中的 null 值。
  • DbNull：选择数据库中的 NULL 值。
  • AnyNull：选择 null JSON 值和 NULL 数据库值。

假设您的 Prisma Schema 中有以下模型

model Log {
  id Int @id
  meta Json
}

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

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

要解决此问题，您需要导入并使用新的 null 类型之一

import { Prisma } from '@prisma/client'

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

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

import { Prisma } from '@prisma/client'

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

要将数据库 NULL 值插入 Json 字段，您可以这样写

import { Prisma } from '@prisma/client'

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

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

它们也不适用于 array_contains 操作符，因为在 JSON 数组中只能存在 JSON null。由于 JSON 数组中不能存在数据库 NULL，所以 { array_contains: null } 不会产生歧义。

具体升级路径​

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

要从 2.x 版本升级到 3.x 版本，您需要同时更新 prisma 和 `@prisma/client` 包。prisma 和 `@prisma/client` 包在版本号中都带有一个插入符号 ^，以防止破坏性变更。

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

danger

在升级之前，请检查每项**破坏性变更**，了解本次升级可能如何影响您的应用程序。

npm install prisma@3 @prisma/client@3