升级到 Prisma ORM 4

当你从早期的 Prisma ORM 版本升级时，Prisma ORM 4 引入了许多重大更改。本指南解释了此升级可能如何影响你的应用，并提供有关如何处理任何更改的说明。

¥Prisma ORM 4 introduces a number of breaking changes when you upgrade from an earlier Prisma ORM version. This guide explains how this upgrade might affect your application and gives instructions on how to handle any changes.

重大变化

¥Breaking changes

本节概述了 Prisma ORM 4 中的重大更改，这些更改分组在 一般变化 下，这些更改同时影响 Prisma 架构和 Prisma 客户端、架构变更 和 客户端变更。

¥This section gives an overview of breaking changes in Prisma ORM 4, grouped under general changes that affect both the Prisma Schema and Prisma Client, Schema changes and Client changes.

我们建议你首先解决任何 Prisma 架构验证错误，然后提取数据库以反映新的 Prisma 架构功能，最后修复 Prisma Client 中的任何类型错误并通过运行测试套件进行验证。

¥We recommend that you first address any Prisma schema validation errors, then pull your database to reflect new Prisma schema capabilities, and finally fix any type errors in Prisma Client and validate by running your test suite.

升级你的 Prisma 架构

¥Upgrade your Prisma Schema

1. 仔细浏览更改列表并检查你是否受到重大更改的影响。

   ¥Carefully skim the list of changes and check if you are impacted by a breaking change.

2. 检查 Prisma 架构验证错误（通过 npx prisma validate 或通过 Prisma VS Code 扩展）。

   ¥Review the Prisma schema validation errors (via npx prisma validate, or via the Prisma VS Code extension).

   1. 如果没有验证错误，请继续步骤 3。

      ¥If you don't have validation errors, continue with step 3.

   2. 如果你遇到验证错误：

      ¥If you have validation errors:

      1. 尝试将验证错误映射到下面列表中的更改，以了解哪个更改导致无效的 Prisma 架构，并阅读链接的说明以了解如何升级。它只能来自：

         ¥Try to map the validation error to a change from the list below to understand which change caused the invalid Prisma schema, and read the linked instructions for how to upgrade. It can only come from:

         • 1:1 关系的显式唯一约束

           ¥Explicit unique constraints for 1:1 relations

         • 删除了对在隐式多对多关系上使用 references 的支持

           ¥Removed support for usage of references on implicit many-to-many relations

         • 在 MySQL 和 MongoDB 的一对一和一对多关系中，强制执行 references 参数中引用字段的唯一性

           ¥Enforced uniqueness of referenced fields in the references argument in one-to-one and one-to-many relations for MySQL and MongoDB

         • 删除对 type 别名的无证支持

           ¥Removal of undocumented support for the type alias

         • 删除 SQLite URL 的 sqlite 协议

           ¥Removal of the sqlite protocol for SQLite URLs

         • 更好的字符串字面量语法

           ¥Better grammar for string literals

3. 重复此操作，直到你的 Prisma 架构有效。

   ¥Repeat until your Prisma schema is valid.

4. 运行 npx prisma db pull 将 Prisma 架构升级到所有新功能（例如 extendedIndexes）。

   ¥Run npx prisma db pull to upgrade the Prisma schema to all new capabilities (e.g. extendedIndexes).

5. 检查 Prisma 架构的更改并验证有效性。

   ¥Review changes of the Prisma schema and verify validity.

6. 继续执行 Prisma 客户端步骤。

   ¥Continue with Prisma Client steps.

升级你对 Prisma 客户端的使用

¥Upgrade your use of Prisma Client

1. 仔细浏览 变更清单，了解你是否受到重大变更的影响。

   ¥Carefully skim the list of changes to understand if you are impacted by a breaking change.

   1. 如果是，请阅读详细的升级说明。

      ¥If yes, read the detailed upgrade instructions.

   2. 如果否，请继续 2。

      ¥If no, proceed with 2.

2. Prisma Client 中的一些 API 更改正在影响运行时行为，因此请运行你的测试套件。

   ¥Some API changes in Prisma Client are impacting runtime behavior, so please run your test suite.

享受 Prisma ORM 4！

¥Enjoy Prisma ORM 4!

一般变化

¥General changes

本节包括影响 Prisma 架构和 Prisma 客户端的更改。

¥This section includes changes that affect both the Prisma Schema and Prisma Client.

Node.js 最低版本变更

¥Node.js minimum version change

从 Prisma ORM 版本 4.0.0 开始，我们支持的 Node.js 最低版本是 14.17.x。如果你使用早期版本的 Node.js，则需要更新它。

¥From Prisma ORM version 4.0.0, the minimum version of Node.js that we support is 14.17.x. If you use an earlier version of Node.js, you will need to update it.

请参阅我们的 系统要求 了解所有最低版本要求。

¥See our system requirements for all minimum version requirements.

架构变更

¥Schema changes

本节包括影响 Prisma 架构的更改。

¥This section includes changes that affect the Prisma Schema.

索引配置

¥Index configuration

在 Prisma ORM 4 中，extendedIndexes 预览功能现在将普遍可用。这包括以下索引配置选项：

¥In Prisma ORM 4, the extendedIndexes Preview feature will now become generally available. This includes the following index configuration options:

• MySQL 的索引长度配置、唯一约束和主键约束（3.5.0 及更高版本中的预览版）

  ¥Length configuration of indexes, unique constraints and primary key constraints for MySQL (in Preview in versions 3.5.0 and later)

• 索引、唯一约束和主键约束的排序顺序配置（3.5.0 及更高版本的预览版）

  ¥Sort order configuration of indexes, unique constraints and primary key constraints (in Preview in versions 3.5.0 and later)

• PostgreSQL 的新索引类型：Hash（3.6.0 及更高版本中的预览版）和 GIN、GiST、SP-GiST 和 BRIN（3.14.0 及更高版本中的预览版）

  ¥New index types for PostgreSQL: Hash (in Preview in versions 3.6.0 and later) and GIN, GiST, SP-GiST and BRIN (in Preview in versions 3.14.0 and later)

• SQL Server 的索引集群（版本 3.13.0 及更高版本中的预览版）

  ¥Index clustering for SQL Server (in Preview in versions 3.13.0 and later)

有关这些功能的更多详细信息，请参阅有关 索引配置 的文档。

¥See our documentation on Index configuration for more details of these features.

升级路径

¥Upgrade path

如果你之前在数据库级别配置这些属性，那么这些都可能是重大更改。在这种情况下，你将需要：

¥These can all be breaking changes if you were previously configuring these properties at the database level. In this case, you will need to:

1. 升级到 这些说明 之后的新 Prisma ORM 4 软件包

   ¥Upgrade to the new Prisma ORM 4 packages following these instructions

2. 之后运行 npx prisma db pull 以检索索引和约束的任何现有配置。这需要在运行任何 npx prisma db push 或 npx prisma migrate dev 命令之前完成，否则你可能会丢失数据库中定义但之前未在 Prisma 架构中表示的任何配置。

   ¥Run npx prisma db pull afterwards to retrieve any existing configuration of indexes and constraints. This needs to be done before running any npx prisma db push or npx prisma migrate dev command, or you may lose any configuration that was defined in the database but not previously represented in the Prisma schema.

有关更多详细信息，请参阅索引配置文档的 从以前的版本升级 部分。

¥For more details, see the Upgrading from previous versions section of our index configuration documentation.

标量列表默认值

¥Scalar list defaults

对于支持标量列表（PostgreSQL、CockroachDB 和 MongoDB）的数据库连接器，Prisma ORM 4 引入了使用 @default 属性在 Prisma 模式中设置默认值的功能：

¥For database connectors that support scalar lists (PostgreSQL, CockroachDB and MongoDB), Prisma ORM 4 introduces the ability to set a default value in your Prisma schema with the @default attribute:

Relational databases

model User {
  id             Int      @id @default(autoincrement())
  posts          Post[]
  favoriteColors String[] @default(["red", "yellow", "purple"])
}

MongoDB

model User {
  id             String   @id @default(auto()) @map("_id") @db.ObjectId
  posts          Post[]
  favoriteColors String[] @default(["red", "yellow", "purple"])
}

升级路径

¥Upgrade path

如果你之前在数据库级别为标量列表定义了默认值，那么这是一个重大更改。在这种情况下，你将需要：

¥This is a breaking change if you previously had defaults defined for scalar lists at the database level. In this case, you will need to:

1. 升级到 这些说明 之后的新 Prisma ORM 4 软件包

   ¥Upgrade to the new Prisma ORM 4 packages following these instructions

2. 之后运行 npx prisma db pull 以检索索引和约束的任何现有配置。这需要在运行任何 npx prisma db push 或 npx prisma migrate dev 命令之前完成，否则你将丢失数据库中定义但之前未在 Prisma 架构中表示的任何默认值。

   ¥Run npx prisma db pull afterwards to retrieve any existing configuration of indexes and constraints. This needs to be done before running any npx prisma db push or npx prisma migrate dev command, or you will lose any defaults that are defined in the database but not previously represented in the Prisma schema.

对一对一关系的显式 @unique 约束

¥Explicit @unique constraints on one-to-one relations

在 Prisma ORM 4 中使用一对一关系时，你需要将 @unique 属性显式添加到关系标量字段。例如，对于 User 和 Profile 模型之间的一对一关系，你需要将 @unique 属性添加到 profileId 字段：

¥When using one-to-one relations in Prisma ORM 4, you will need to explicitly add the @unique attribute to the relation scalar field. For example, for this one-to-one relation between a User and a Profile model, you will need to add the @unique attribute to the profileId field:

Relational databases

model User {
  id        Int      @id @default(autoincrement())
  profile   Profile? @relation(fields: [profileId], references: [id])
  profileId Int?     @unique // <-- include this explicitly
}

model Profile {
  id   Int   @id @default(autoincrement())
  user User?
}

MongoDB

model User {
  id        String   @id @default(auto()) @map("_id") @db.ObjectId
  profile   Profile? @relation(fields: [profileId], references: [id])
  profileId String?  @unique @db.ObjectId // <-- include this explicitly
}

model Profile {
  id   String @id @default(auto()) @map("_id") @db.ObjectId
  user User?
}

升级路径

¥Upgrade path

升级到 Prisma ORM 4 后，关系标量上没有 @unique 属性的任何一对一关系都将触发验证错误。要升级，你需要：

¥After you upgrade to Prisma ORM 4, any one-to-one relations without a @unique attribute on the relation scalar will trigger a validation error. To upgrade, you will need to:

1. 升级到 这些说明 之后的新 Prisma ORM 4 软件包

   ¥Upgrade to the new Prisma ORM 4 packages following these instructions

2. 通过将显式 @unique 或 @id 属性添加到数据模型中，手动修复 Prisma 架构中的验证错误。

   ¥Manually fix the validation errors in your Prisma schema by adding the explicit @unique or @id attribute to your data model.

3. 使用 prisma db push（适用于 MongoDB）或 prisma migrate dev（适用于 MySQL）将更改推送到数据库。

   ¥Push the changes to your database using prisma db push for MongoDB or prisma migrate dev for MySQL.

一对一和一对多关系强制使用 @unique 或 @id 属性（MySQL 和 MongoDB）

¥Enforced use of @unique or @id attribute for one-to-one and one-to-many relations (MySQL and MongoDB)

当你在 Prisma ORM 4 中使用一对一和一对多关系时，你需要在关系字段上使用 @unique 属性来保证关系的单侧只有一条记录。现在，MySQL 和 MongoDB 已强制执行此操作，使它们与其他连接器保持一致。缺少 @unique 属性现在将触发验证错误。

¥When you use one-to-one and one-to-many relations in Prisma ORM 4, you will need to use a @unique attribute on the relation field to guarantee that the singular side(s) of the relation has only one record. This is now enforced for MySQL and MongoDB, bringing them into line with other connectors. Missing @unique attributes will now trigger a validation error.

在以下 User 和 Post 模型之间的一对多关系示例中，必须将 @unique 属性添加到 email 字段：

¥In the following example of a one-to-many relation between a User and Post model, the @unique attribute must be added to the email field:

Relational databases

model User {
  id    Int    @id @default(autoincrement())
  email String @unique // <-- we enforce this attribute
  posts Post[]
}

model Post {
  id          Int    @id @default(autoincrement())
  authorEmail String
  author      User   @relation(fields: [authorEmail], references: [email])
}

MongoDB

model User {
  id    Int    @id @default(auto()) @map("_id") @db.ObjectId
  email String @unique // <-- we enforce this attribute
  posts Post[]
}

model Post {
  id          Int    @id @default(auto()) @map("_id") @db.ObjectId
  authorEmail String
  author      User   @relation(fields: [authorEmail], references: [email])
}

在以下 User 和 Profile 模型之间一对一关系的示例中，必须将 @unique 属性添加到 email 字段：

¥In the following example of a one-to-one relation between a User and Profile model, the @unique attribute must be added to the email field:

Relational databases

model User {
  id        Int     @id @default(autoincrement())
  email     String  @unique // <- we enforce this unique attribute
  profile   Profile @relation(fields: [profileId], references: [id])
  profileId Int
}

model Profile {
  id        Int     @id @default(autoincrement())
  userEmail String? @unique
  user      User?
}

MongoDB

model User {
  id        Int     @id @default(auto()) @map("_id") @db.ObjectId
  email     String  @unique // <- we enforce this unique attribute
  profile   Profile @relation(fields: [profileId], references: [id])
  profileId Int     @db.ObjectId
}

model Profile {
  id        Int     @id @default(auto()) @map("_id") @db.ObjectId
  userEmail String? @unique
  user      User?   @relation(fields: [userEmail], references: [email])
}

升级路径

¥Upgrade path

升级到 Prisma ORM 4 后，关系字段上没有 @unique 或 @id 属性的任何一对一或一对多关系都将触发验证错误。要升级，你需要：

¥After you upgrade to Prisma ORM 4, any one-to-one or one-to-many relations without a @unique or @id attribute on the relation field will trigger a validation error. To upgrade, you will need to:

1. 升级到 这些说明 之后的新 Prisma ORM 4 软件包

   ¥Upgrade to the new Prisma ORM 4 packages following these instructions

2. 手动修复 Prisma 架构中的验证错误。或者，如果你有最新的实时数据库，运行 npx prisma db pull 将自动添加 @unique 属性。

   ¥Manually fix the validation errors in your Prisma schema. Alternatively, if you have an up-to-date live database, running npx prisma db pull will add the @unique attributes automatically.

禁止隐式多对多关系使用 references 语法

¥Disallow references syntax for implicit many-to-many relations

在 Prisma ORM 4 中使用 隐式多对多关系 时，你将无法再使用 references 参数，该参数以前是可选的。例如，以下关系现在将触发验证错误：

¥When using implicit many-to-many relations in Prisma ORM 4, you will no longer be able to use the references argument, which was previously optional. For example, the following relation would now trigger a validation error:

schema.prisma

model Post {
  id         Int        @id @default(autoincrement())
  categories Category[] @relation("my-relation", references: [id]) // <-- validation error
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[] @relation("my-relation", references: [id]) // <-- validation error
}

相反，你可以写：

¥Instead, you can write:

schema.prisma

model Post {
  id         Int        @id @default(autoincrement())
  categories Category[] @relation("my-relation")
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[] @relation("my-relation")
}

这是因为 references 的唯一有效值是 id，因此删除此参数可以更清楚哪些可以更改，哪些不能更改。

¥This is because the only valid value for references was id, so removing this argument makes it clearer what can and cannot be changed.

升级路径

¥Upgrade path

升级到 Prisma ORM 4 后，任何带有 references 参数的隐式多对多关系都将触发验证错误。要升级，你需要：

¥After you upgrade to Prisma ORM 4, any implicit many-to-many relations with a references argument will trigger a validation error. To upgrade, you will need to:

1. 升级到 这些说明 之后的新 Prisma ORM 4 软件包

   ¥Upgrade to the new Prisma ORM 4 packages following these instructions

2. 手动修复 Prisma 架构中的验证错误。或者，如果你有最新的实时数据库，运行 npx prisma db pull 将自动删除 references 参数。

   ¥Manually fix the validation errors in your Prisma schema. Alternatively, if you have an up-to-date live database, running npx prisma db pull will remove the references arguments automatically.

更好的字符串字面量语法

¥Better grammar for string literals

Prisma 模式中的字符串字面量现在需要遵循与 JSON 中的字符串相同的规则。这主要改变了一些特殊字符的转义。更多详细信息可在 JSON 规范 或 JSON 网站 中找到。

¥String literals in your Prisma Schema now need to follow the same rules as strings in JSON. This mostly changes the escaping of some special characters. More details can be found in the JSON specification or on the JSON website.

升级路径

¥Upgrade path

对于某些现有模式来说，这是一个重大变化。升级到 Prisma ORM 4 后，错误转义的字符将触发验证错误。要升级，你需要：

¥This is a breaking change for some existing schemas. After you upgrade to Prisma ORM 4, incorrectly escaped characters will trigger a validation error. To upgrade, you will need to:

1. 升级到 这些说明 之后的新 Prisma ORM 4 软件包

   ¥Upgrade to the new Prisma ORM 4 packages following these instructions

2. 手动修复 Prisma 架构中的验证错误。

   ¥Manually fix the validation errors in your Prisma schema.

客户端变更

¥Client changes

本节包括影响 Prisma 客户端的更改。

¥This section includes changes that affect Prisma Client.

原始查询类型映射：标量值现在被反序列化为其正确的 JavaScript 类型

¥Raw query type mapping: scalar values are now deserialized as their correct JavaScript types

在版本 3.14.x 和 3.15.x 中，原始查询类型映射 与预览功能 improvedQueryRaw 一起提供。在 4.0.0 版本中，我们已将原始查询类型映射设为普遍可用。在 4.0.0 及更高版本中，你不需要使用 improvedQueryRaw 来获得此功能。

¥In versions 3.14.x and 3.15.x, raw query type mapping was available with the Preview feature improvedQueryRaw. In version 4.0.0, we have made raw query type mapping Generally Available. You do not need to use improvedQueryRaw to get this functionality in versions 4.0.0 and later.

原始查询现在将标量值反序列化为其相应的 JavaScript 类型。请注意，Prisma ORM 从值本身而不是 Prisma Schema 类型推断类型。

¥Raw queries now deserialize scalar values to their corresponding JavaScript types. Note that Prisma ORM infers types from the values themselves and not from the Prisma Schema types.

查询和响应示例：

¥Example query and response:

const res =
  await prisma.$queryRaw`SELECT bigint, bytes, decimal, date FROM "Table";`
console.log(res) // [{ bigint: BigInt("123"), bytes: Buffer.from([1, 2]), decimal: new Prisma.Decimal("12.34"), date: Date("<some_date>") }]

升级路径

¥Upgrade path

从 4.0.0 版本开始，queryRaw 或 queryRawUnsafe 返回的部分数据类型有所不同，如下：

¥From version 4.0.0, some data types returned by queryRaw or queryRawUnsafe are different, as follows:

数据类型	4.0.0 版本之前	从 4.0.0 版本开始
DateTime	返回为 String	返回为 Date
Numeric	返回为 Float	返回为 Decimal
Bytes	返回为 String	返回为 Buffer
Int64	返回为 Integer	返回为 BigInt

如果你使用 queryRaw 或 queryRawUnsafe 返回上述任何数据类型，则必须更改代码以处理新类型。

¥If you use queryRaw or queryRawUnsafe to return any of the above data types, then you must change your code to handle the new types.

例如，如果你返回 DateTime 数据，那么你需要考虑以下因素：

¥For example, if you return DateTime data, then you need to take into account the following:

• 你不再需要为返回的数据手动实例化 DateTime 对象。

  ¥You no longer need to manually instantiate a DateTime object for the returned data.

• 如果你的代码当前使用返回的 String 数据，那么你现在需要将 DateTime 对象转换为 String。

  ¥If your code currently uses the returned String data, then you now need to convert the DateTime object to a String.

你必须对上表中的其他数据类型进行等效的代码更改。

¥You must make equivalent code changes for the other data types in the table above.

原始查询映射：PostgreSQL 类型转换

¥Raw query mapping: PostgreSQL type-casts

在版本 3.14.x 和 3.15.x 中，原始查询类型映射 与预览功能 improvedQueryRaw 一起提供。在 4.0.0 版本中，我们已将原始查询类型映射设为普遍可用。在 4.0.0 及更高版本中，你不需要使用 improvedQueryRaw 来获得此功能。

¥In versions 3.14.x and 3.15.x, raw query type mapping was available with the Preview feature improvedQueryRaw. In version 4.0.0, we have made raw query type mapping Generally Available. You do not need to use improvedQueryRaw to get this functionality in versions 4.0.0 and later.

在 4.0.0 版本之前，许多 PostgreSQL 类型转换不起作用。我们收紧了类型强制规则，以便所有类型转换现在都可以工作。因此，一些隐式转换现在会失败。

¥Before version 4.0.0, many PostgreSQL type-casts did not work. We have tightened the type coercion rules so that all type-casts now work. As a result, some implicit casts now fail.

升级路径

¥Upgrade path

我们建议你重新测试 $queryRaw 的使用，以确保传递到原始查询中的类型与 PostgreSQL 期望的类型匹配。

¥We recommend that you re-test your use of $queryRaw to ensure that the types you pass into your raw queries match the types that PostgreSQL expects.

例如，在版本 4.0.0 中，以下查询失败：

¥For example, in version 4.0.0, the following query fails:

await prisma.$queryRaw`select length(${42});`
// ERROR: function length(integer) does not exist
// HINT: No function matches the given name and argument types. You might need to add explicit type casts.

这是因为 PostgreSQL 的 length 函数需要 text 作为输入。Prisma ORM 过去常常默默地将 42 强制转换为 text，但在 4.0.0 版本中不再这样做。要解决此问题，请将 42 显式转换为 text，如下所示：

¥This is because PostgreSQL’s length function expects text as input. Prisma ORM used to silently coerce 42 to text, but does not do this in version 4.0.0. To fix this, explicitly cast 42 to text as follows:

await prisma.$queryRaw`select length(${42}::text);`

原始查询映射：PostgreSQL 和 JavaScript 整数

¥Raw query mapping: PostgreSQL and JavaScript integers

在版本 3.14.x 和 3.15.x 中，原始查询类型映射 与预览功能 improvedQueryRaw 一起提供。在 4.0.0 版本中，我们已将原始查询类型映射设为普遍可用。在 4.0.0 及更高版本中，你不需要使用 improvedQueryRaw 来获得此功能。

¥In versions 3.14.x and 3.15.x, raw query type mapping was available with the Preview feature improvedQueryRaw. In version 4.0.0, we have made raw query type mapping Generally Available. You do not need to use improvedQueryRaw to get this functionality in versions 4.0.0 and later.

Prisma ORM 将 JavaScript 整数作为 INT8 发送到 PostgreSQL。这可能与仅接受 INT4 作为输入的用户定义函数冲突。

¥Prisma ORM sends JavaScript integers to PostgreSQL as INT8. This might conflict with your user-defined functions that accept only INT4 as input.

升级路径

¥Upgrade path

如果你将 $queryRaw 或参数化 $queryRawUnsafe 查询与 PostgreSQL 数据库一起使用，请执行以下操作之一：

¥If you use $queryRaw or parametrized $queryRawUnsafequeries with a PostgreSQL database, do one of the following:

• 将用户定义函数中任何整数的输入类型更新为 INT8，或者

  ¥Update the input types of any integers in your user-defined functions to INT8, or

• 将查询参数中的所有整数转换为 INT4。

  ¥Cast any integers in your query parameters to INT4.

DbNull、JsonNull 和 AnyNull 现在是对象

¥DbNull, JsonNull and AnyNull are now objects

JavaScript null 对于 JSON 列是不明确的，因此 Prisma ORM 使用 DbNull、JsonNull 和 AnyNull 来区分数据库 NULL 值和 JSON null 值。在 4.0.0 版本之前，DbNull、JsonNull 和 AnyNull 是字符串常量。从 4.0.0 版本开始，它们是对象。

¥JavaScript null is ambiguous for JSON columns, so Prisma ORM uses DbNull, JsonNull, and AnyNull to distinguish between the database NULL value and the JSON null value. Before version 4.0.0, DbNull, JsonNull, and AnyNull were string constants. From version 4.0.0, they are objects.

请参阅 按空值过滤 了解更多信息。

¥See Filtering by null values for more information.

升级路径

¥Upgrade path

1. 如果你使用字面量字符串来寻址这些值，则必须将它们替换为以下命名常量：

   ¥If you use literal strings to address these values, then you must replace them with the following named constants:

   • DbNull：替换为 Prisma.DbNull

     ¥DbNull: replace with Prisma.DbNull

   • JsonNull：替换为 Prisma.JsonNull

     ¥JsonNull: replace with Prisma.JsonNull

   • AnyNull：替换为 Prisma.AnyNull

     ¥AnyNull: replace with Prisma.AnyNull

   如果你已经使用这些命名常量，则无需执行任何操作。

   ¥If you already use these named constants, then you do not need to take any action.

2. 如果你现在在将 Prisma.DbNull 作为 JSON 字段的值传递时遇到类型错误，那么这可能表明代码中存在我们的类型在版本 4.0.0 之前未捕获的错误。你尝试存储 DbNull 的字段在你的架构中可能不可为空。结果，数据库中存储了文本 DbNull 字符串，而不是 NULL。

   ¥If you now get a type error when you pass Prisma.DbNull as the value of a JSON field, then this probably indicates a bug in your code that our types did not catch before version 4.0.0. The field where you tried to store DbNull is probably not nullable in your schema. As a result, a literal DbNull string was stored in the database instead of NULL.

3. 现在，当你将 Prisma.DbNull、Prisma.JsonNull 或 Prisma.AnyNull 与 MongoDB 结合使用时，你可能会遇到类型错误或运行时验证错误。这从来都不是有效的，但在 Prisma ORM 4 之前就被默默地接受了。你需要检查你的数据并将这些字段更改为 null。

   ¥You might now encounter a type error or runtime validation error when you use Prisma.DbNull, Prisma.JsonNull, or Prisma.AnyNull with MongoDB. This was never valid, but was silently accepted prior to Prisma ORM 4. You need to review your data and change these fields to null.

4. 如果你将动态 JSON 传递到 Prisma 客户端中的 JSON 列（例如 prisma.findMany({where: { jsonColumn: someJson } })），则必须检查 someJson 不能是字符串 "数据库空值"、"JsonNull" 或 "AnyNull"。如果是这些值中的任何一个，则查询将在版本 4.0.0 中返回不同的结果。

   ¥If you pass in dynamic JSON to a JSON column in Prisma Client (for example prisma.findMany({where: { jsonColumn: someJson } })), then you must check that someJsoncannot be the string "DBNull", "JsonNull", or "AnyNull". If it is any of these values, then the query will return different results in version 4.0.0.

MongoDB 中复合类型的默认字段

¥Default fields on composite types in MongoDB

从版本 4.0.0 开始，如果在满足以下所有条件时对复合类型执行数据库读取，则 Prisma 客户端会将默认值插入到结果中。

¥From version 4.0.0, if you carry out a database read on a composite type when all of the following conditions are true, then Prisma Client inserts the default value into the result.

状况：

¥Conditions:

• 复合类型上的字段是必需的，并且

  ¥A field on the composite type is required, and

• 该字段有一个默认值，并且

  ¥this field has a default value, and

• 返回的一个或多个文档中不存在该字段。

  ¥this field is not present in the returned document or documents.

此行为现在与模型字段的行为一致。

¥This behavior is now consistent with the behavior for model fields.

要了解更多信息，请参阅 复合类型上必填字段的默认值。

¥To learn more, see Default values for required fields on composite types.

升级路径

¥Upgrade path

如果你当前依赖返回值 null，那么你需要重构代码以处理现在在 Prisma ORM 4 中返回的默认值。

¥If you currently rely on a return value of null, then you need to refactor your code to handle the default value that is now returned in Prisma ORM 4.

SQLite 中大数的舍入错误

¥Rounding errors on big numbers in SQLite

SQLite 是一个松散类型的数据库。如果你的架构有一个类型为 Int 的字段，则 Prisma ORM 会阻止你插入大于整数的值。但是，没有什么可以阻止数据库直接接受更大的数字。这些手动插入的大数字在查询时会导致舍入错误。

¥SQLite is a loosely-typed database. If your schema has a field with type Int, then Prisma ORM prevents you from inserting a value larger than an integer. However, nothing prevents the database from directly accepting a bigger number. These manually-inserted big numbers cause rounding errors when queried.

为了避免此问题，Prisma ORM 版本 4.0.0 及更高版本会检查从数据库中流出的数字，以验证它们是否符合整数的边界。如果数字不适合，Prisma ORM 会抛出 P2023 错误，例如：

¥To avoid this problem, Prisma ORM version 4.0.0 and later checks numbers on the way out of the database to verify that they fit within the boundaries of an integer. If a number does not fit, then Prisma ORM throws a P2023 error, such as:

Inconsistent column data: Conversion failed:
Value 9223372036854775807 does not fit in an INT column,
try migrating the 'int' column type to BIGINT

升级路径

¥Upgrade path

如果你将 Prisma ORM 与 SQLite 结合使用，那么你需要找到查询 Int 字段的任何代码，并确保它处理可能返回的任何 P2023 错误。

¥If you use Prisma ORM in conjunction with SQLite, then you need to find any code that queries Int fields and ensure that it handles any P2023 errors that might be returned.

Prisma ORM 不再将 Prisma.dmmf.schema 导出到生成的 Prisma 客户端

¥Prisma ORM no longer exports Prisma.dmmf.schema into the generated Prisma Client

从版本 4.0.0 开始，Prisma ORM 不再将 Prisma.dmmf.schema 导出到生成的 Prisma 客户端中。这使得生成的 Prisma 客户端更加高效，并且还避免了 Jest 的一些内存泄漏。

¥From version 4.0.0, Prisma ORM no longer exports Prisma.dmmf.schema into the generated Prisma Client. This makes the generated Prisma Client much more efficient, and also avoids some memory leaks with Jest.

注意：

¥Note:

• 此更改不会影响 Prisma ORM 传递给生成器的 DMMF。

  ¥This change does not affect the DMMF that Prisma ORM passes to the generators.

• 你可以使用 getDmmf()from @prisma/internals 来访问架构属性。

  ¥You can use getDmmf()from @prisma/internals to access the schema property.

• 我们仍然将 Prisma.dmmf.datamodel 导出到生成的 Prisma 客户端中。

  ¥We still export Prisma.dmmf.datamodel into the generated Prisma Client.

将 prisma 和 @prisma/client 软件包升级到版本 4

¥Upgrade the prisma and @prisma/client packages to version 4

要从早期版本升级到 Prisma ORM 4，你需要更新 prisma 和 @prisma/client 软件包。prisma 和 @prisma/client 软件包安装时其版本号中都带有脱字符号 ^。这允许升级到新的次要版本，但不允许升级到主要版本，以防止重大更改。

¥To upgrade to Prisma ORM 4 from an earlier version, 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. This allows upgrades to new minor versions, but not major versions, to safeguard against breaking changes.

要忽略脱字符 ^ 并跨主要版本升级，可以在使用 npm 或 yarn 升级时使用 @4 标签：

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

danger

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

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

npm

npm install prisma@4 @prisma/client@4

yarn

yarn up prisma@4 @prisma/client@4

视频指南

¥Video guide

有关升级过程的视频演练和升级场景示例，请观看我们录制的有关升级到 Prisma ORM 4 的直播：

¥For a video walkthrough of the upgrade process and examples of upgrade scenarios, see our recorded livestream on upgrading to Prisma ORM 4: