跳到主要內容

引擎

從技術角度來看，Prisma Client 由三個主要組件構成

  • JavaScript 客戶端函式庫
  • TypeScript 類型定義
  • 一個查詢引擎

所有這些組件在您執行 prisma generate 後都位於產生的 .prisma/client 資料夾中。

本頁面涵蓋關於查詢引擎的相關技術細節。

Prisma 引擎​

在每個模組的核心，通常都有一個 Prisma 引擎 實作核心功能集。引擎以 Rust 實作，並公開高階介面使用的低階 API。

Prisma 引擎是直接連接資料庫的介面，任何更高層級的介面都總是透過引擎層與資料庫通訊。

舉例來說，Prisma Client 連接到 查詢引擎，以便在資料庫中讀取和寫入資料

Prisma engine

使用自訂引擎函式庫或二進制檔案​

預設情況下，當您安裝或更新 Prisma CLI 套件 prisma 時，所有引擎檔案都會自動下載到 node_modules/@prisma/engines 資料夾中。當您呼叫 prisma generate 時，查詢引擎 也會複製到產生的 Prisma Client。如果您有以下情況，您可能想要使用 自訂函式庫或二進制檔案 檔案：

  • 無法自動下載引擎檔案。
  • 您已建立自己的引擎函式庫或二進制檔案，用於測試目的，或用於未正式支援的作業系統。

使用下列環境變數來指定您的二進制檔案的自訂位置

警告
  • PRISMA_MIGRATION_ENGINE_BINARY 變數在 5.0.0 版本中已被棄用。
  • 內省引擎由 4.9.0 版本起的 Migration 引擎提供服務。因此，PRISMA_INTROSPECTION_ENGINE 環境變數將不會被使用。
  • PRISMA_FMT_BINARY 變數用於 4.2.0 或更低版本。

設定環境變數​

您可以在您的機器上全域定義環境變數，或在 .env 檔案中定義。

a) .env 檔案​

將環境變數新增至 .env 檔案。

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

注意：可以在 prisma 資料夾外部的位置使用 .env 檔案。

b) 全域環境變數​

執行以下命令以全域設定環境變數 (在此範例中為 PRISMA_QUERY_ENGINE_BINARY)

export PRISMA_QUERY_ENGINE_BINARY=/custom/my-query-engine-unix

測試您的環境變數​

執行以下命令以輸出所有二進制檔案的路徑

npx prisma -v

輸出顯示查詢引擎路徑來自 PRISMA_QUERY_ENGINE_BINARY 環境變數

Current platform     : darwin
Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-unix)
Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/migration-engine-unix)
Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/introspection-engine-unix)

託管引擎​

PRISMA_ENGINES_MIRROR 環境變數允許您透過私有伺服器、AWS 儲存桶或其他雲端儲存託管引擎檔案。如果您有需要自訂建置引擎的自訂作業系統，這會很有用。

PRISMA_ENGINES_MIRROR=https://my-aws-bucket

查詢引擎檔案​

**查詢引擎檔案**對於每個作業系統都不同。它被命名為 query-engine-PLATFORM 或 libquery_engine-PLATFORM，其中 PLATFORM 對應於編譯目標的名稱。查詢引擎檔案擴展名也取決於平台。例如，如果查詢引擎必須在 Darwin 作業系統（例如 macOS Intel）上執行，則它被稱為 libquery_engine-darwin.dylib.node 或 query-engine-darwin。您可以在這裡找到所有支援平台的概觀。

當呼叫 prisma generate 時，查詢引擎檔案會下載到產生的 Prisma Client 的 runtime 目錄中。

請注意，查詢引擎是以 Rust 實作的。原始碼位於 prisma-engines 儲存庫中。

運行時的查詢引擎​

預設情況下，Prisma Client 將查詢引擎作為 Node-API 函式庫 載入。您也可以選擇 將 Prisma 配置為使用編譯為可執行二進制檔案的查詢引擎，它將作為 sidecar 程序與您的應用程式一起運行。建議使用 Node-API 函式庫方法，因為它可以減少 Prisma Client 和查詢引擎之間的通訊開銷。

Diagram showing the query engine and Node.js at runtime

當第一個 Prisma Client 查詢被調用時，或當在您的 PrismaClient 實例上呼叫 $connect() 方法時，查詢引擎會啟動。一旦查詢引擎啟動，它會建立一個 連線池 並管理到資料庫的實體連線。從那時起，Prisma Client 就可以將 查詢 (例如 findUnique()、findMany、create 等) 發送到資料庫。

當調用 $disconnect() 時，查詢引擎會停止，並且資料庫連線會關閉。

下圖描述了「典型流程」

  1. 在 Prisma Client 上調用 $connect()
  2. 查詢引擎已啟動
  3. 查詢引擎建立到資料庫的連線並建立連線池
  4. Prisma Client 現在已準備好將查詢發送到資料庫
  5. Prisma Client 將 findMany() 查詢發送到查詢引擎
  6. 查詢引擎將查詢翻譯成 SQL 並發送到資料庫
  7. 查詢引擎從資料庫接收 SQL 回應
  8. 查詢引擎將結果以純 JavaScript 物件的形式返回給 Prisma Client
  9. 在 Prisma Client 上調用 $disconnect()
  10. 查詢引擎關閉資料庫連線
  11. 查詢引擎已停止

Typical flow of the query engine at run time

查詢引擎的職責​

在使用 Prisma Client 的應用程式中，查詢引擎具有以下職責

  • 在連線池中管理實體資料庫連線
  • 從 Prisma Client Node.js 程序接收傳入的查詢
  • 產生 SQL 查詢
  • 將 SQL 查詢發送到資料庫
  • 處理來自資料庫的回應並將其發送回 Prisma Client

偵錯查詢引擎​

您可以透過將 DEBUG 環境變數設定為 engine 來存取查詢引擎的日誌

export DEBUG="engine"

您還可以透過在 Prisma Client 中設定 query 日誌等級，更清楚地了解查詢引擎產生的 SQL 查詢

const prisma = new PrismaClient({
  log: ['query'],
})

了解更多關於偵錯和記錄的資訊。

配置查詢引擎​

為 Prisma Client 定義查詢引擎類型​

如上所述，預設查詢引擎是載入到 Prisma Client 中的 Node-API 函式庫，但也有另一種實作方式是作為在自己的程序中運行的可執行二進制檔案。您可以透過將 engineType 屬性提供給 Prisma Client generator 來配置查詢引擎類型

generator client {
  provider   = "prisma-client-js"
  engineType = "binary"
}

engineType 的有效值為 binary 和 library。您也可以改為使用環境變數 PRISMA_CLIENT_ENGINE_TYPE。

資訊
  • 在 Prisma 3.x 之前，預設且唯一可用的引擎類型是 binary，因此無法配置 Prisma Client 和 Prisma CLI 要使用的引擎類型。
  • 從 2.20.0 到 3.x 版本，library 引擎類型可用，並且預設透過啟用預覽功能標誌「nApi」或使用 PRISMA_FORCE_NAPI=true 環境變數來使用。

為 Prisma CLI 定義查詢引擎類型​

Prisma CLI 也為其自身需求使用自己的查詢引擎。您可以透過定義環境變數 PRISMA_CLI_QUERY_ENGINE_TYPE=binary 將其配置為使用二進制版本的查詢引擎。