升級至 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 呼叫，則這些呼叫將不再有效。我們建議您在任何可能的情況下都使用模板字串以確保安全，否則請改用 $queryRawUnsafe，但在仔細逸出查詢以防止 SQL 注入後再使用。

您可以在文件中的原始資料庫存取章節中，了解有關新的 $queryRaw 和 $queryRawUnsafe 方法的更多資訊。

Json Null 相等性

您無法透過 null 值篩選 Json 欄位。請參閱此 GitHub issue。這是因為 { equals: null } 檢查資料庫中的欄位值是否為 NULL，而不是檢查欄位內的 JSON 值是否等於 null。

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

JsonNull：選取 JSON 中的 null 值。
DbNull：選取資料庫中的 NULL 值。
AnyNull： 選取 null JSON 值和 NULL 資料庫值。

假設您的 Prisma Schema 中有以下模型

model Log {
  id Int @id
  meta Json
}

從 3.0.1 開始，如果您嘗試在 Json 欄位上依 null 篩選，您會看到 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。若要將 null 值插入 Json 欄位，您會寫入

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 連接器，因為 JSON null 和資料庫 NULL 之間沒有區別。

它們也不適用於 array_contains 運算子，因為 JSON 陣列中只能存在 JSON null。由於 JSON 陣列中不能存在資料庫 NULL，因此 { array_contains: null } 並不含糊。

特定升級路徑

具名約束升級路徑

升級到 Prisma ORM 3 後，約束和索引名稱的預設命名慣例將會變更，且您的主鍵和外鍵名稱現在將成為支援它們的資料庫的 schema 的一部分。因此，您現有 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 Null 相等性​

特定升級路徑​