升级到 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 相等性

您不能通过 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,
  },
})

警告

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

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

特定升级路径

命名约束升级路径

升级到 Prisma ORM 3 后，约束和索引名称的默认命名约定将更改，并且您的主键和外键名称现在将成为支持它们的数据库的 schema 的一部分。因此，您现有 Prisma schema 的含义将发生变化。

参照操作升级路径

Prisma ORM 2.x 版本阻止在某些 Prisma Client 函数中删除连接的记录，并且不允许您在 Prisma Schema 中配置参照操作来更改此行为。

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

要从 2.x 版本升级到 3.x，您需要同时更新 prisma 和 @prisma/client 包。 prisma 和 @prisma/client 包都使用插入符号 ^ 安装在其版本号中，以防止重大更改。

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

危险

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

npm
yarn

npm install prisma@3 @prisma/client@3

yarn up prisma@3 @prisma/client@3

重大更改​

参照操作​

命名约束​

$queryRaw​

Json Null 相等性​

特定升级路径​