跳到主要內容

如何升級

概述​

本頁將幫助您就是否以及如何從 Prisma 1 升級到 Prisma ORM 2.x 及更高版本做出明智的決定。

升級文件​

升級文件包含多個頁面，以下是使用它們的方法概述

  • 如何升級 (您當前在此頁面)：瞭解通用升級過程的起點。
  • Schema 不相容性：關於 Prisma 1 與 Prisma ORM 2.x（及更高版本）之間 schema 不相容性的參考頁面。閱讀此頁面是可選的，但它將讓您更好地理解升級過程中的某些步驟。

除了這兩個頁面之外，還有各種實用指南，它們將引導您完成升級過程中的示例場景

  • 升級 Prisma 層：無論您的 Prisma 1 設定如何，您都應始終從遵循本指南開始升級過程。

完成該指南後，您可以選擇以下四個指南之一來升級您的應用層

Prisma 1 與 Prisma ORM 2.x 及更高版本之間的主要區別​

從高層次來看，Prisma 1 與 Prisma ORM 2.x 及更高版本之間的最大區別總結如下。

Prisma ORM 2.x 及更高版本

  • 不需要託管資料庫代理伺服器（即 Prisma 伺服器）。
  • 使 Prisma 1 的功能更加模組化，並將其拆分為專用工具
    • Prisma Client：Prisma Client 1.0 的改進版本
    • Prisma Migrate：資料建模和遷移（以前是 prisma deploy）。
  • 使用 Prisma schema，它是 Prisma 1 資料模型和 prisma.yml 的合併。
  • 使用自己的建模語言，而不是基於 GraphQL SDL。
  • 不再暴露“為您的資料庫提供 GraphQL API”，而僅透過 Prisma Client API 允許程式設計訪問。
    • 不再支援 Prisma ORM 繫結。
  • 透過更強大的內省功能，允許將 Prisma ORM 2.x 及更高版本連線到任何現有資料庫

功能一致性​

Prisma ORM 2.x 及更高版本尚未與 Prisma 1 完全功能一致。Prisma ORM 2.x 及更高版本仍缺失的最大功能是即時訂閱。

  • 即時 API（訂閱）：Prisma ORM 2.x 及更高版本目前沒有訂閱資料庫中發生事件並即時獲得通知的方法。目前尚不清楚即時 API 是否、何時以及以何種形式會新增到 Prisma ORM 2.x 及更高版本中。目前，您可以使用原生資料庫觸發器實現即時功能，或者如果您正在使用 GraphQL 訂閱，可以考慮在您的變更解析器中手動觸發訂閱。

Schema 不相容性​

在 Prisma 1 中執行 prisma deploy 時建立的資料庫 schema 僅與 Prisma ORM 2.x 及更高版本建立的 schema 部分相容。本節快速概述了常見的不相容性及可能的解決方案。-

注意：有關問題和相應解決方案的詳細說明，請參閱Schema 不相容性頁面。

以下是不同列的概述

  • 問題：從 Prisma 1 升級到 Prisma ORM 2.x 及更高版本時問題的簡短描述
  • SQL：這可以透過對 SQL schema 進行非破壞性更改來解決嗎？
  • Prisma schema：這可以透過對 Prisma ORM 2.x 及更高版本中的 schema 進行非破壞性更改來解決嗎？
  • 破壞 Prisma 1：SQL 語句會破壞 Prisma 1 的設定嗎？這僅在您選擇逐步並行升級策略時相關。
問題SQLPrisma schema破壞 Prisma 1
預設值未在資料庫中體現是是否
生成的 CUID 作為 ID 值未在資料庫中體現否是否
@createdAt 未在資料庫中體現是是否
@updatedAt 未在資料庫中體現否是否
內聯 1-1 關係被識別為 1-n（缺少 UNIQUE 約束）是否否
所有非內聯關係都被識別為 m-n是否是
Json 型別在資料庫中表示為 TEXT是否否 (MySQL)
是 (PostgreSQL)
列舉在資料庫中表示為 TEXT是否否 (MySQL)
是 (PostgreSQL)
必需的 1-1 關係未在資料庫中體現否是否
Prisma 1 中的 @db 屬性未傳輸到 Prisma schema否是否
CUID 長度不匹配是否否
標量列表（陣列）透過額外表維護取決於具體情況否取決於具體情況

注意：Prisma schema 中這些變通方法的一個普遍缺點是，重新內省資料庫後，對 Prisma schema 的更改會丟失，並且每次內省執行後都需要手動重新新增。

Prisma 1 升級 CLI​

Prisma 1 升級 CLI 幫助您應用 Schema 不相容性 頁面上解釋的變通方法。它生成 SQL 語句以修復資料庫 schema 並使其與 Prisma ORM 2.x 及更高版本相容。請注意，您可以完全控制對資料庫執行的操作，升級 CLI 僅為您生成和列印語句。升級 CLI 還負責 Prisma schema 中的變通方法。

從高層次來看，使用升級 CLI 的升級工作流程如下所示。

對於初始設定

  1. 您透過安裝 Prisma ORM 2.x 及更高版本的 CLI 並執行 npx prisma init 來設定 Prisma ORM。
  2. 您連線到資料庫並使用 npx prisma db pull 進行內省。

Prisma CLI introspection flow

對於修復 schema 不相容性

  1. 您使用 npx prisma-upgrade 呼叫升級 CLI。
  2. 升級 CLI 會生成 SQL 命令供您在資料庫上執行。
  3. 您在資料庫上執行這些 SQL 命令。
  4. 您再次執行 prisma db pull 命令。
  5. 您再次執行 npx prisma-upgrade 命令。
  6. 升級 CLI 透過新增缺失的屬性來調整 Prisma schema (2.x 及更高版本)。

Fixing the schema incompatibilities

請注意，升級 CLI 的設計方式是您可以隨時停止和重新啟動該過程。一旦您在資料庫上運行了升級 CLI 生成的 SQL 命令，下次呼叫升級 CLI 時該 SQL 命令將不會再顯示。這樣，您就可以在方便的時候逐步解決所有 schema 不相容性。

升級策略​

主要有兩種升級策略

  • 一次性升級：從專案中完全移除 Prisma 1，並一次性將所有內容遷移到 Prisma ORM 2.x 或更高版本。
  • 逐步並行升級：將 Prisma ORM 2.x 及更高版本新增到現有的 Prisma 1 專案中，並逐步用新的 Prisma 功能替換現有的 Prisma 1 功能，同時讓它們並行執行。

請注意，如果您計劃並行執行 Prisma 1 和 Prisma ORM 2.x 或更高版本，則不得解決那些會破壞 Prisma 1 設定的schema 不相容性。

何時選擇哪種策略​

如果您的專案尚未在生產環境中執行，或者流量和使用者資料較少，則建議採用一次性升級策略。

如果您的專案已經有大量流量，並且資料庫中儲存了大量使用者資料，您可能需要考慮逐步升級策略，即讓 Prisma 1 和 Prisma ORM 2 或更高版本並行執行一段時間，直到您將所有舊的 Prisma 1 功能替換為 Prisma ORM 2 或更高版本的功能。

請注意，如果您選擇逐步升級策略並打算並行執行 Prisma 1 和 Prisma ORM 2.x 或更高版本，則無法修復需要“破壞 Prisma 1”更改的schema 不相容性。這是因為這些資料遷移會破壞 Prisma 1 預期的 schema。這意味著您的 Prisma Client API 可能不會像原來那樣地道，但您仍然可以獲得 Prisma Client 的完整功能集。

升級路徑​

無論您選擇哪種策略，從高層次來看，設想的升級路徑如下所示

  1. 將新的 Prisma ORM 2.x 或更高版本的 CLI 作為開發依賴項安裝
  2. 建立您的 Prisma schema 並配置資料庫連線 URL
  3. 使用 Prisma ORM 2.x 或更高版本的 CLI 內省您的 Prisma 1 資料庫並生成您的 Prisma schema
  4. 執行 Prisma 1 升級 CLI 以“修復”Prisma schema
  5. 安裝並生成 Prisma Client 2.x 或更高版本
  6. 調整您的應用程式程式碼，特別是將 Prisma Client 1.0 的 API 呼叫替換為 Prisma Client 2.x 或更高版本的 API 呼叫

後續步驟​

一旦您決定升級，請繼續閱讀升級 Prisma ORM 層指南。

© . This site is unofficial and not affiliated with Prisma Data, Inc.