如何升級

總覽

本頁面協助您針對何時以及如何從 Prisma 1 升級到 Prisma ORM 2.x 及更高版本做出明智的決定。

升級文件

升級文件包含數個頁面，以下是如何使用它們的總覽

• 如何升級 (您在這裡)：了解一般升級流程的起點。
• Schema 不相容性：關於 Prisma 1 和 Prisma ORM 2.x (及更高版本) 之間 Schema 不相容性的參考頁面。閱讀此頁面是可選的，但它將讓您更了解升級流程中的某些步驟。

除了這兩個頁面之外，還有各種實用指南，引導您完成升級流程的範例情境

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

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

• 舊版 Nexus 到新版 Nexus：如果您目前正在使用 GraphQL Nexus 執行 Prisma 1，請選擇本指南。
• prisma-binding 到 Nexus：如果您目前正在使用 prisma-binding 執行 Prisma 1，並想要升級到 Nexus，請選擇本指南。
• prisma-binding 到 SDL-first：如果您目前正在使用 prisma-binding 執行 Prisma 1，並想要升級到 SDL-first GraphQL 伺服器，請選擇本指南。
• REST API：如果您目前正在使用 Prisma Client 1 執行 Prisma 1，並正在建構 REST API，請選擇本指南。

Prisma 1 和 Prisma ORM 2.x 及更高版本之間的主要差異

在高層次上，以下概述了 Prisma 1 和 Prisma ORM 2.x 及更高版本之間的最大差異。

Prisma ORM 2.x 及更高版本

• 不需要託管資料庫代理伺服器 (即 Prisma server)。
• 使 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 binding。
• 允許透過更強大的內省將 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 訂閱，您可以考慮在mutation resolvers 內部手動觸發訂閱。

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 設定？這僅在您選擇逐步並行升級策略時相關。

問題	SQL	Prisma schema	破壞 Prisma 1
預設值未在資料庫中表示	是	是	否
產生的 CUID 作為 ID 值未在資料庫中表示	否	是	否
@createdAt 未在資料庫中表示	是	是	否
@updatedAt 未在資料庫中表示	否	是	否
內聯 1-1 關係被識別為 1-n (缺少 UNIQUE 約束)	是	否	否
所有非內聯關係都被識別為 m-n	是	否	是
Json 類型在資料庫中表示為 TEXT	是	否	否 (MySQL) 是 (PostgreSQL)
Enums 在資料庫中表示為 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 進行內省。

對於修復 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 及更高版本)。

請注意，升級 CLI 的設計方式是您可以隨時停止並重新開始該流程。一旦您針對資料庫執行了由升級 CLI 產生的 SQL 命令，SQL 命令將不會在您下次叫用升級 CLI 時顯示。這樣一來，您可以在方便時逐步解決所有 Schema 不相容性。

升級策略

有兩種主要的升級策略

• 一次全部升級：完全從您的專案中移除 Prisma 1，並一次將所有內容移轉到 Prisma ORM 2.x 或更高版本。
• 逐步並行升級：將 Prisma ORM 2.x 及更高版本新增到現有的 Prisma 1 專案，並在並行運行的同時逐步將現有的 Prisma 1 功能替換為較新的 Prisma 功能。

請注意，如果您計劃並行運行 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 層指南。