升级到 Prisma ORM 6

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

¥Prisma ORM v6 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.

将 `prisma` 和 `@prisma/client` 包升级到 v6

¥Upgrade the prisma and @prisma/client packages to v6

要从早期版本升级到 Prisma ORM v6，你需要更新 prisma 和 @prisma/client 包：

¥To upgrade to Prisma ORM v6 from an earlier version, you need to update both the prisma and @prisma/client packages:

npm
yarn
pnpm
bun

npm install @prisma/client@6
npm install -D prisma@6

yarn up prisma@6 @prisma/client@6

pnpm upgrade prisma@6 @prisma/client@6

bun add @prisma/client@6
bun add prisma@6 --dev

危险

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

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

重大变化

¥Breaking changes

本节概述了 Prisma ORM v6 中的重大更改。

¥This section gives an overview of breaking changes in Prisma ORM v6.

支持的最低 Node.js 版本

¥Minimum supported Node.js versions

Prisma ORM v6 支持的新的最低 Node.js 版本为：

¥The new minimum supported Node.js versions for Prisma ORM v6 are:

对于 Node.js 18，支持的最低版本为 18.18.0

¥for Node.js 18 the minimum supported version is 18.18.0
对于 Node.js 20，支持的最低版本为 20.9.0

¥for Node.js 20 the minimum supported version is 20.9.0
对于 Node.js 22，支持的最低版本为 22.11.0

¥for Node.js 22 the minimum supported version is 22.11.0

Node.js 16、17、19 和 21 没有官方支持。

¥There is no official support for Node.js 16, 17, 19 and 21.

支持的最低 TypeScript 版本

¥Minimum supported TypeScript version

Prisma ORM v6 支持的最低 TypeScript 版本是：5.1.0.

¥The new minimum supported TypeScript version for Prisma ORM v6 is: 5.1.0.

信息

此架构更改仅适用于 PostgreSQL。如果你正在使用 CockroachDB，则无需采取任何措施 - 隐式 m-to-n 关系的架构保持不变。

¥This schema change only applies to PostgreSQL.\ If you are using CockroachDB, you do not need to take any action—the schema for implicit m-to-n relationships remains unchanged.

PostgreSQL 上隐式 m-n 关系的架构更改

¥Schema change for implicit m-n relations on PostgreSQL

如果你使用的是 PostgreSQL 并在 Prisma 模式中定义隐式多对多关系，则 Prisma ORM 会在后台为你维护关系表。此关系表具有 A 和 B 列，用于表示属于此关系的模型的表。

¥If you're using PostgreSQL and are defining implicit many-to-many relations in your Prisma schema, Prisma ORM maintains the relation table for you under the hood. This relation table has A and B columns to represent the tables of the models that are part of this relation.

以前版本的 Prisma ORM 用于在这两列上创建唯一索引。在 Prisma v6 中，此唯一索引正在更改为主键以实现简化默认副本身份行为。

¥Previous versions of Prisma ORM used to create a unique index on these two columns. In Prisma v6, this unique index is changing to a primary key in order to simplify for the default replica identity behaviour.

Expand for an example

例如，考虑以下 Prisma 模式，其中 Post 和 Tag 模型之间存在隐式 m-n 关系：

¥As an example, consider the following Prisma schema with an implicit m-n relation between Post and Tag models:

model Post {
  id         Int    @id @default(autoincrement())
  title      String
  categories Tag[]
}

model Tag {
  id    Int    @id @default(autoincrement())
  name  String
  posts Post[]
}

在这种情况下，Prisma ORM 在后台为你维护以下关系表：

¥In this case, Prisma ORM maintains the following relation table for you under the hood:

-- CreateTable
CREATE TABLE "_PostToTag" (
    "A" INTEGER NOT NULL,
    "B" INTEGER NOT NULL
);

-- CreateIndex
CREATE UNIQUE INDEX "_PostToTag_AB_unique" ON "_PostToTag"("A", "B");

-- CreateIndex
CREATE INDEX "_PostToTag_B_index" ON "_PostToTag"("B");

-- AddForeignKey
ALTER TABLE "_PostToTag" ADD CONSTRAINT "_PostToTag_A_fkey" FOREIGN KEY ("A") REFERENCES "Post"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "_PostToTag" ADD CONSTRAINT "_PostToTag_B_fkey" FOREIGN KEY ("B") REFERENCES "Tag"("id") ON DELETE CASCADE ON UPDATE CASCADE;

在 Prisma v6 中，UNIQUE INDEX 正在更改为 PRIMARY KEY：

¥In Prisma v6, the UNIQUE INDEX is changing into a PRIMARY KEY:

-- CreateTable
CREATE TABLE "_PostToTag" (
    "A" INTEGER NOT NULL,
    "B" INTEGER NOT NULL,

    CONSTRAINT "_PostToTag_AB_pkey" PRIMARY KEY ("A","B")
);

-- CreateIndex
CREATE INDEX "_PostToTag_B_index" ON "_PostToTag"("B");

-- AddForeignKey
ALTER TABLE "_PostToTag" ADD CONSTRAINT "_PostToTag_A_fkey" FOREIGN KEY ("A") REFERENCES "Post"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "_PostToTag" ADD CONSTRAINT "_PostToTag_B_fkey" FOREIGN KEY ("B") REFERENCES "Tag"("id") ON DELETE CASCADE ON UPDATE CASCADE;

如果你定义隐式 m-n 关系在你的 Prisma 模式中，你将创建的下一个迁移将包含属于这些关系的所有关系表的 ALTER TABLE 语句。这些看起来类似于：

¥If you're defining implicit m-n relations in your Prisma schema, the next migration you'll create will contain ALTER TABLE statements for all the relation tables that belong to these relations. These will look similar to this:

-- AlterTable
ALTER TABLE "_PostToTag" ADD CONSTRAINT "_PostToTag_AB_pkey" PRIMARY KEY ("A", "B");

-- DropIndex
DROP INDEX "_PostToTag_AB_unique";

为了隔离这些架构更改（并且不将它们与下一次迁移打包在一起），我们建议你在升级到 Prisma v6 后立即创建新的迁移：

¥In order to isolate these schema changes (and not having them bundled with your next migration), we recommend that you create a new migration right after having upgraded to Prisma v6:

npx prisma migrate dev --name upgrade-to-v6

这样，你就拥有一个专用的迁移来处理此架构更改，并保持迁移历史记录干净。

¥That way, you have a single, dedicated migration that takes care of this schema change and otherwise keeps your migration history clean.

在 PostgreSQL 上进行全文搜索

¥Full-text search on PostgreSQL

fullTextSearch 预览功能仅针对 MySQL 升级到通用可用性。这意味着如果你正在使用 PostgreSQL 并且当前正在使用此预览功能，那么你现在需要使用新的 fullTextSearchPostgres 预览功能：

¥The fullTextSearch Preview feature is promoted to General Availability only for MySQL. This means that if you're using PostgreSQL and currently make use of this Preview feature, you now need to use the new fullTextSearchPostgres Preview feature:

之前

¥Before

schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["fullTextSearch"]
}

之后

¥After

schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["fullTextSearchPostgres"]
}

`Buffer` 的使用

¥Usage of Buffer

为了提高 Prisma 与新的现代 JavaScript 运行时之间的兼容性，我们逐渐放弃 Node.js 特定的 API，转而使用标准 JavaScript。

¥In an effort to improve compatibility between Prisma and new modern JavaScript runtimes, we're gradually moving away from Node.js-specific APIs in favor of standard JavaScript.

Prisma v6 用 Uint8Array 替换 Buffer 的用法以表示 Bytes 类型的字段。确保将所有出现的 Buffer 类型替换为新的 Uint8Array 类型。

¥Prisma v6 replaces the usage of Buffer with Uint8Array to represent fields of type Bytes. Make sure to replace all your occurrences of the Buffer type with the new Uint8Array.

Expand to view how to convert between Buffer and Uint8Array

从 `Buffer` 到 `Uint8Array` 的转换

¥Conversion from Buffer to Uint8Array

你可以直接将 Buffer 实例用作 Uint8Array：

¥You can directly use the Buffer instance as a Uint8Array:

const buffer: Buffer = Buffer.from([1, 2, 3, 4]);
const uint8Array: Uint8Array = buffer; // No conversion needed

从 `Uint8Array` 到 `Buffer` 的转换

¥Conversion from Uint8Array to Buffer

你可以使用 Buffer.from 从 Uint8Array 创建 Buffer：

¥You can create a Buffer from a Uint8Array using Buffer.from:

const uint8Array: Uint8Array = new Uint8Array([1, 2, 3, 4]);
const buffer: Buffer = Buffer.from(uint8Array.buffer);

之前

¥Before

Code
Prisma schema

import { PrismaClient } from '@prisma/client'

async function main() {
  const prisma = new PrismaClient()
  await prisma.user.deleteMany()

  const bytesCreated = await prisma.user.create({
    data: {
      bytes: Buffer.from([1, 2, 3, 4]),
    },
  })
  // ^^^^^^^^^^^^^^^^^^^^^^^^^^
  // `bytesCreated` used to have type: {
  //    bytes: Buffer
  //    id: number
  // }

  for (const bytesFound of await prisma.user.findMany()) {
    bytesFound.bytes // Buffer [ 1, 2, 3, 4 ]
  }
}

main()

model User {
  id    Int   @id @default(autoincrement())
  bytes Bytes
}

之后

¥After

Code
Prisma schema

import { PrismaClient } from '@prisma/client'

async function main() {
  const prisma = new PrismaClient()
  await prisma.user.deleteMany()

  const bytesCreated = await prisma.user.create({
    data: {
      bytes: Uint8Array.from([1, 2, 3, 4]),
    },
  })
  // ^^^^^^^^^^^^^^^^^^^^^^^^^^
  // `bytesCreated` now has type: {
  //    bytes: Uint8Array
  //    id: number
  // }

  for (const bytesFound of await prisma.user.findMany()) {
    bytesFound.bytes // Uint8Array [ 1, 2, 3, 4 ]
  }
}

main()

model User {
  id    Int   @id @default(autoincrement())
  bytes Bytes
}

删除 `NotFoundError`

¥Removed NotFoundError

在 Prisma v6 中，我们删除了 NotFoundError，转而使用 PrismaClientKnownRequestError，findUniqueOrThrow() 和 findFirstOrThrow() 中的错误代码为 P2025。如果你依赖于在代码中捕获 NotFoundError 实例，则需要相应地调整代码。

¥In Prisma v6, we removed the NotFoundError in favor of PrismaClientKnownRequestError with error code P2025 in findUniqueOrThrow() and findFirstOrThrow(). If you've relied on catching NotFoundError instances in your code, you need to adjust the code accordingly.

之前

¥Before

import { PrismaClient, NotFoundError } from '@prisma/client';

// inside an `async` function
try {
  const user = await prisma.user.findUniqueOrThrow({
    where: { id: 42 },
  });
  console.log(user);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("User not found!");
  }
  else {
    console.error("Unexpected error:", error);
  }
}

之后

¥After

import { PrismaClient, Prisma } from '@prisma/client';

// inside an `async` function
try {
  const user = await prisma.user.findUniqueOrThrow({
    where: { id: 42 },
  });
  console.log(user);
} catch (error) {
  if (
    error instanceof Prisma.PrismaClientKnownRequestError &&
    error.code === 'P2025' // Specific code for "record not found"
  ) {
    console.error("User not found!");
  } 
  else {
    console.error("Unexpected error:", error);
  }
}

不能用作模型名称的新关键字：`async`、`await`、`using`

¥New keywords that can't be used as model names: async, await, using

在此版本中，你不能再使用 async、await 和 using 作为模型名称。

¥With this release, you can't use async, await and using as model names any more.

预览功能升级到通用可用性

¥Preview features promoted to General Availability

在此版本中，我们将许多预览功能提升到一般可用性。

¥In this release, we are promoting a number of Preview features to General Availability.

`fullTextIndex`

如果你在应用中使用全文索引功能，现在可以从 Prisma 模式中的 previewFeatures 中删除 fullTextIndex：

¥If you use the full-text index feature in your app, you can now remove fullTextIndex from the previewFeatures in your Prisma schema:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["fullTextIndex"]
}

`fullTextSearch`

如果你在应用中将全文搜索功能与 MySQL 一起使用，现在可以从 Prisma 模式中的 previewFeatures 中删除 fullTextSearch：

¥If you use the full-text search feature with MySQL in your app, you can now remove fullTextSearch from the previewFeatures in your Prisma schema:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["fullTextSearch"]
}

如果你将其与 PostgreSQL 一起使用，则需要将功能标志的名称更新为 fullTextSearchPostgres：

¥If you are using it with PostgreSQL, you need to update the name of the feature flag to fullTextSearchPostgres:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["fullTextSearchPostgres"]
}

将 prisma 和 @prisma/client 包升级到 v6​

重大变化​

支持的最低 Node.js 版本​

支持的最低 TypeScript 版本​

PostgreSQL 上隐式 m-n 关系的架构更改​

在 PostgreSQL 上进行全文搜索​

之前​

之后​

Buffer 的使用​

从 Buffer 到 Uint8Array 的转换​

从 Uint8Array 到 Buffer 的转换​

之前​

之后​

删除 NotFoundError​

之前​

之后​

不能用作模型名称的新关键字：async、await、using​

预览功能升级到通用可用性​

fullTextIndex​

fullTextSearch​

将 `prisma` 和 `@prisma/client` 包升级到 v6

重大变化

支持的最低 Node.js 版本

支持的最低 TypeScript 版本

PostgreSQL 上隐式 m-n 关系的架构更改

在 PostgreSQL 上进行全文搜索

之前

之后

`Buffer` 的使用

从 `Buffer` 到 `Uint8Array` 的转换

从 `Uint8Array` 到 `Buffer` 的转换

之前

之后

删除 `NotFoundError`

之前

之后

不能用作模型名称的新关键字：`async`、`await`、`using`

预览功能升级到通用可用性

`fullTextIndex`

`fullTextSearch`