跳至主要内容

升级到 Prisma ORM 6

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

本页面回答的问题
  • Prisma 6 有哪些变化？
  • 如何安全升级？
  • 哪些重大更改会影响我的应用程序？

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

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

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

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

重大更改​

本节概述了 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。
如果您使用的是 CockroachDB，则无需采取任何措施 — 隐式多对多关系的模式保持不变。

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

如果您正在使用 PostgreSQL 并在 Prisma 模式中定义隐式多对多关系，Prisma ORM 会在底层为您维护关系表。此关系表包含 A 和 B 列，用于表示此关系中模型的表。

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

展开查看示例

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

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 模式中定义隐式 m-n 关系，您将创建的下一个迁移将包含针对所有属于这些关系的关系表的 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 用 Uint8Array 替换了 Buffer 的用法来表示 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);

之前​

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

之后​

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

移除了 NotFoundError​

在 Prisma v6 中，我们移除了 NotFoundError，转而使用带有错误代码 P2025 的 PrismaClientKnownRequestError，用于 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"]
}
打开方式
复制为 Markdown
在 Claude 中打开
在 ChatGPT 中打开
在 T3.chat 中打开
在 GitHub 中编辑
© . This site is unofficial and not affiliated with Prisma Data, Inc.