升級至 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。

資訊

此 schema 變更僅適用於 PostgreSQL。
如果您使用 CockroachDB，則無需採取任何行動—隱含多對多關係的 schema 保持不變。

PostgreSQL 上隱含多對多關係的 Schema 變更

如果您使用 PostgreSQL 並在您的 Prisma schema 中定義隱含多對多關係，Prisma ORM 會在底層維護關係表。此關係表具有 A 和 B 欄位，以表示屬於此關係的模型的表格。

先前版本的 Prisma ORM 曾經在這兩個欄位上建立唯一索引。在 Prisma v6 中，此唯一索引正在變更為主鍵，以便簡化預設副本身分行為。

展開以查看範例

舉例來說，考慮以下 Prisma schema，其中 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 schema 中定義隱含多對多關係，您將建立的下一個 migration 將包含適用於屬於這些關係的所有關係表的 ALTER TABLE 陳述式。這些將看起來類似於這樣

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

-- DropIndex
DROP INDEX "_PostToTag_AB_unique";

為了隔離這些 schema 變更（並且不將它們與您的下一個 migration 捆綁在一起），我們建議您在升級到 Prisma v6 之後立即建立新的 migration

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

這樣，您就有一個單獨的、專用的 migration 來處理此 schema 變更，並保持您的 migration 歷史記錄的整潔。

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

之後

程式碼
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`

在 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 schema 中的 previewFeatures 移除 fullTextIndex

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

`fullTextSearch`

如果您在應用程式中將全文檢索功能與 MySQL 結合使用，您現在可以從 Prisma schema 中的 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 上隱含多對多關係的 Schema 變更​

PostgreSQL 上的全文檢索​

之前​

之後​

Buffer 的使用​

從 Buffer 轉換為 Uint8Array​

從 Uint8Array 轉換為 Buffer​

之前​

之後​

已移除 NotFoundError​

之前​

之後​

不能再用作模型名稱的新關鍵字：async、await、using​

預覽功能提升為正式發行版​

fullTextIndex​

fullTextSearch​