跳到主要內容

引擎

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

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

執行 prisma generate 後，所有這些元件都位於生成的 .prisma/client 資料夾中。

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

注意

自v6.7.0起，Prisma ORM 擁有 queryCompiler 預覽功能。

啟用後，你的 Prisma Client 將在沒有基於 Rust 的查詢引擎二進位制檔案的情況下生成。:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["queryCompiler", "driverAdapters"]
}

請注意，queryCompiler 旁邊還需要驅動介面卡預覽功能。

你可以在我們的部落格上瞭解更多關於此更改的資訊。

Prisma 引擎​

在每個模組的核心，通常都有一個Prisma 引擎，它實現了核心功能集。引擎用Rust實現，並暴露了一個低階 API，供高階介面使用。

Prisma 引擎是直接與資料庫互動的介面，任何高階介面總是透過引擎層與資料庫通訊。

例如，Prisma Client 連線到查詢引擎，以便在資料庫中讀寫資料。

Prisma engine

使用自定義引擎庫或二進位制檔案​

預設情況下，當你安裝或更新 prisma（Prisma CLI 包）時，所有引擎檔案都會自動下載到 node_modules/@prisma/engines 資料夾中。當你呼叫 prisma generate 時，查詢引擎也會被複制到生成的 Prisma Client 中。如果你希望使用自定義庫或二進位制檔案，可能出現以下情況：

  • 無法自動下載引擎檔案。
  • 你已經建立了自己的引擎庫或二進位制檔案用於測試目的，或者用於一個官方不支援的作業系統。

使用以下環境變數來指定二進位制檔案的自定義位置

警告
  • PRISMA_MIGRATION_ENGINE_BINARY 變數在5.0.0中已棄用。
  • 從4.9.0起，內省引擎由遷移引擎提供。因此，PRISMA_INTROSPECTION_ENGINE 環境變數將不再使用。
  • PRISMA_FMT_BINARY 變數在4.2.0或更低版本中使用。

設定環境變數​

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

a) .env 檔案​

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

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

注意：可以將.env 檔案放置在 prisma 資料夾之外的位置。

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 bucket 或其他雲端儲存託管引擎檔案。這在你擁有需要自定義構建引擎的自定義作業系統時會很有用。

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 以使用編譯為可執行二進位制檔案的查詢引擎，該二進位制檔案作為應用程式的伴隨程序執行。推薦使用 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 庫，但也有一個作為可執行二進位制檔案的替代實現，它在自己的程序中執行。你可以透過向 Prisma Client generator 提供 engineType 屬性來配置查詢引擎型別。

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 將其配置為使用查詢引擎的二進位制版本。

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