升級到 Prisma ORM 3

如果你從早期版本（任何 2.x 版本）升級，Prisma ORM 3 引入了許多重大更改，因此，瞭解此次升級可能如何影響你的應用程式並進行任何必要的調整以確保平穩過渡非常重要。

以下是重大更改列表以及如何處理它們。

重大更改

引用操作

3.x 版本中引入的引用操作移除了 Prisma Client 中之前在執行時阻止級聯刪除的安全網。

因此，根據你用於應用程式的工作流程，你可能會受到影響。我們建議你檢查你的 schema 並決定是否需要明確定義引用操作。

命名約束

我們更改了 Prisma ORM 命名約束和索引所遵循的約定。我們還在 PSL 中引入了 map 屬性（資料庫級名稱）和 name 屬性（Prisma Client API 名稱）之間的明確區分，以顯式控制 Prisma schema 中約束的定義方式。

這意味著你在執行 Prisma migrate 或 db pull 時會注意到影響，它們將遵循此新約定。我們建議你調整你的 schema 以適當地反映你的約束和索引的名稱。

你可以檢視命名約束升級路徑以獲取更多資訊，瞭解如何操作。

$queryRaw

從 3.x 版本開始，$queryRaw 方法現在只支援模板字面量。

這意味著如果你的應用程式依賴於使用字串的 $queryRaw 呼叫，這些呼叫將不再起作用。我們建議你儘可能使用模板字面量以確保安全，否則在仔細轉義查詢以防止 SQL 注入後，求助於 $queryRawUnsafe。

你可以在文件的原始資料庫訪問部分了解更多關於新的 $queryRaw 和 $queryRawUnsafe 方法。

Json 空值相等性

你不能透過空值過濾 Json 欄位。參閱此 GitHub issue。這是因為 { equals: null } 檢查資料庫中的列值是否為 NULL，而不是列內的 JSON 值是否等於 null。

為了解決此問題，我們決定將 Json 欄位上的 null 分為 JsonNull、DbNull 和 AnyNull。

JsonNull：選擇 JSON 中的空值。
DbNull：選擇資料庫中的 NULL 值。
AnyNull：選擇 JSON 空值和資料庫 NULL 值。

鑑於你的 Prisma Schema 中有以下模型

model Log {
  id Int @id
  meta Json
}

從 3.0.1 版本開始，如果你嘗試透過空值過濾 Json 欄位，你將看到 TypeError

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: null
                ^ TypeError: Type 'null' is not assignable to type
        }
    },
  },
});

要解決此問題，你需要匯入並使用其中一種新的 null 型別

import { Prisma } from '@prisma/client'

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: Prisma.AnyNull,
      },
    },
  },
})

這也適用於 create、update 和 upsert。要在 Json 欄位中插入 null 值，你可以這樣寫

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.JsonNull,
  },
})

要將資料庫 NULL 插入到 Json 欄位中，你可以這樣寫

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.DbNull,
  },
})

警告

此 API 更改不適用於 MongoDB 聯結器，因為在 MongoDB 中 JSON null 和資料庫 NULL 之間沒有區別。

它們也不適用於 array_contains 運算子，因為 JSON 陣列中只能有 JSON null。由於 JSON 陣列中不能有資料庫 NULL，所以 { array_contains: null } 不會產生歧義。

特定升級路徑

命名約束升級路徑

升級到 Prisma ORM 3 後，約束和索引名稱的預設命名約定將發生變化，並且你的主鍵和外部索引鍵名稱現在將成為支援它們的資料庫模式的一部分。因此，你現有 Prisma schema 的含義將發生變化。

引用操作升級路徑

Prisma ORM 2.x 版本會阻止在某些 Prisma Client 函式中刪除相關聯的記錄，並且不允許你在 Prisma Schema 中配置引用操作來更改此行為。

將 `prisma` 和 `@prisma/client` 包升級到 Prisma ORM 3

要從 2.x 版本升級到 3.x 版本，你需要更新 prisma 和 @prisma/client 包。prisma 和 @prisma/client 包在版本號中都帶有插入符號 ^，以防止重大更改。

要忽略插入符號 ^ 並跨主要版本升級，你可以在使用 npm 或 yarn 升級時使用 @3 標籤。

危險

在升級之前，檢查每項重大更改，檢視升級可能如何影響你的應用程式。

npm
yarn

npm install prisma@3 @prisma/client@3

yarn up prisma@3 @prisma/client@3

重大更改​

引用操作​

命名約束​

$queryRaw​

Json 空值相等性​

特定升級路徑​