升级到 Prisma ORM 6

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

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

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

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

危险

在升级之前，请查看下面每个重大更改，以了解升级如何影响你的应用程序。

重大更改

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

最低支持的 Node.js 版本

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

对于 Node.js 18，最低支持版本为 **18.18.0**
对于 Node.js 20，最低支持版本为 **20.9.0**
对于 Node.js 22，最低支持版本为 **22.11.0**

不正式支持 Node.js 16、17、19 和 21。

最低支持的 TypeScript 版本

Prisma ORM v6 的新最低支持 TypeScript 版本为：**5.1.0**。

PostgreSQL 上隐式多对多关系的模式更改

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

早期版本的 Prisma ORM 过去会在这两列上创建唯一索引。在 Prisma v6 中，此唯一索引正在更改为主键，以便简化默认副本标识行为。

展开以查看示例

例如，考虑以下 Prisma 模式，其中 Post 和 Tag 模型之间存在隐式多对多关系

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

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

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

-- 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

-- 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;

如果你在 Prisma 模式中定义了隐式多对多关系，你将创建的下一个迁移将包含所有属于这些关系的关系表的 ALTER TABLE 语句。这些将类似于以下内容

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

-- DropIndex
DROP INDEX "_PostToTag_AB_unique";

为了隔离这些模式更改（并且不将其与你的下一个迁移捆绑在一起），我们建议你在升级到 Prisma v6之后立即创建一个新的迁移

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

这样，你就可以拥有一个单独的专用迁移来处理此模式更改，否则可以保持迁移历史记录的整洁。

PostgreSQL 上的全文搜索

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

之前

schema.prisma

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

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

之后

schema.prisma

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

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

`Buffer` 的用法

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

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

展开以查看如何转换 Buffer 和 Uint8Array

从 `Buffer` 转换为 `Uint8Array`

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

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

从 `Uint8Array` 转换为 `Buffer`

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

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

之前

代码
Prisma 模式

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
}

之后

代码
Prisma 模式

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`

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

之前

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);
  }
}

之后

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`

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

预览功能提升为通用可用性

在此版本中，我们正在将许多预览功能提升为通用可用性。

`fullTextIndex`

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

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

`fullTextSearch`

如果你在应用程序中使用带有 **MySQL** 的全文搜索功能，你现在可以从 Prisma 模式中的 previewFeatures 中删除 fullTextSearch

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

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

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

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

重大更改​

最低支持的 Node.js 版本​

最低支持的 TypeScript 版本​

PostgreSQL 上隐式多对多关系的模式更改​

PostgreSQL 上的全文搜索​

之前​

之后​

Buffer 的用法​

从 Buffer 转换为 Uint8Array​

从 Uint8Array 转换为 Buffer​

之前​

之后​

已删除 NotFoundError​

之前​

之后​

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

预览功能提升为通用可用性​

fullTextIndex​

fullTextSearch​