エンジン

技術的な観点から見ると、Prismaクライアントは3つの主要コンポーネントで構成されています

JavaScriptクライアントライブラリ
TypeScript型定義
クエリエンジン

これらのコンポーネントはすべて、prisma generateを実行した後、生成された.prisma/clientフォルダーに配置されます。

このページでは、クエリエンジンに関する関連技術詳細を説明します。

注

v6.7.0以降、Prisma ORMにはqueryCompilerプレビュー機能が搭載されています。

有効にすると、PrismaクライアントはRustベースのクエリエンジンバイナリなしで生成されます。:

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

queryCompilerと合わせてドライバーアダプタープレビュー機能も必要であることに注意してください。

この変更については、当社のブログで詳しく知ることができます。

Prismaエンジン

各モジュールの核には、通常、中核となる機能セットを実装するPrismaエンジンがあります。エンジンはRustで実装されており、上位レベルのインターフェースが使用する低レベルAPIを公開しています。

Prismaエンジンはデータベースへの直接的なインターフェースであり、上位レベルのインターフェースは常にエンジン層を介してデータベースと通信します。

例として、Prismaクライアントはデータベースのデータの読み書きのためにクエリエンジンに接続します。

Prisma engine

カスタムエンジンライブラリまたはバイナリの使用

デフォルトでは、prisma（Prisma CLIパッケージ）をインストールまたは更新すると、すべてのエンジンファイルが自動的にnode_modules/@prisma/enginesフォルダーにダウンロードされます。また、prisma generateを呼び出すと、クエリエンジンも生成されたPrismaクライアントにコピーされます。次の場合に、カスタムライブラリまたはバイナリファイルを使用することができます。

エンジンファイルの自動ダウンロードが不可能な場合。
テスト目的で、または公式にサポートされていないOSのために、独自のエンジンライブラリまたはバイナリを作成した場合。

以下の環境変数を使用して、バイナリのカスタム場所を指定します。

PRISMA_QUERY_ENGINE_LIBRARY (クエリエンジン、ライブラリ)
PRISMA_QUERY_ENGINE_BINARY (クエリエンジン、バイナリ)
PRISMA_SCHEMA_ENGINE_BINARY (スキーマエンジン)
PRISMA_MIGRATION_ENGINE_BINARY (マイグレーションエンジン)
PRISMA_INTROSPECTION_ENGINE_BINARY (イントロスペクションエンジン)

警告

PRISMA_MIGRATION_ENGINE_BINARY変数は5.0.0で非推奨になりました。
イントロスペクションエンジンは4.9.0からマイグレーションエンジンによって提供されます。そのため、PRISMA_INTROSPECTION_ENGINE環境変数は使用されません。
PRISMA_FMT_BINARY変数は4.2.0以前のバージョンで使用されます。

環境変数の設定

環境変数は、マシン全体または.envファイル内で定義できます。

a) `.env`ファイル

.envファイルに環境変数を追加します。

Linux、Unix、macOS
Windows

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

PRISMA_QUERY_ENGINE_BINARY=c:\custom\path\my-query-engine-binary.exe

注: .envファイルをprismaフォルダーの外部の場所で使用することも可能です。

b) グローバル環境変数

環境変数をグローバルに設定するには、以下のコマンドを実行します（この例ではPRISMA_QUERY_ENGINE_BINARY）。

Linux、Unix、macOS
Windows

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

set PRISMA_QUERY_ENGINE_BINARY=c:\custom\my-query-engine-windows.exe

環境変数のテスト

すべてのバイナリへのパスを出力するには、以下のコマンドを実行します。

npx prisma -v

出力は、クエリエンジンのパスがPRISMA_QUERY_ENGINE_BINARY環境変数から来ていることを示しています。

Linux、Unix、macOS
Windows

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)

Current platform     : windows
Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\custom\my-query-engine-windows.exe)
Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\engines\migration-engine-windows.exe)
Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\engines\introspection-engine-windows.exe)

エンジンのホスティング

PRISMA_ENGINES_MIRROR環境変数を使用すると、プライベートサーバー、AWSバケット、またはその他のクラウドストレージを介してエンジンファイルをホストできます。これは、カスタムビルドのエンジンを必要とするカスタムOSを使用している場合に役立ちます。

PRISMA_ENGINES_MIRROR=https://my-aws-bucket

クエリエンジンファイル

クエリエンジンファイルは、オペレーティングシステムごとに異なります。これはquery-engine-PLATFORMまたはlibquery_engine-PLATFORMと名付けられ、PLATFORMはコンパイルターゲットの名前に対応します。クエリエンジンファイルの拡張子もプラットフォームによって異なります。例えば、クエリエンジンがmacOS IntelなどのDarwinオペレーティングシステムで実行される場合、libquery_engine-darwin.dylib.nodeまたはquery-engine-darwinと呼ばれます。サポートされているすべてのプラットフォームの概要はこちらで確認できます。

クエリエンジンファイルは、prisma generateが呼び出されたときに、生成されたPrismaクライアントのruntimeディレクトリにダウンロードされます。

クエリエンジンはRustで実装されていることに注意してください。ソースコードはprisma-enginesリポジトリにあります。

実行時のクエリエンジン

デフォルトでは、PrismaクライアントはクエリエンジンをNode-APIライブラリとしてロードしますが、代わりに実行可能バイナリとしてコンパイルされたクエリエンジンを使用するようにPrismaを構成することもできます。このバイナリはアプリケーションのサイドカープロセスとして実行されます。Node-APIライブラリのアプローチは、Prismaクライアントとクエリエンジンの間の通信オーバーヘッドを削減するため推奨されます。

Diagram showing the query engine and Node.js at runtime

クエリエンジンは、最初のPrismaクライアントクエリが呼び出されたとき、またはPrismaClientインスタンスで$connect()メソッドが呼び出されたときに開始されます。クエリエンジンが開始されると、コネクションプールを作成し、データベースへの物理接続を管理します。それ以降、Prismaクライアントはデータベースにクエリ（例: findUnique()、findMany、createなど）を送信する準備ができます。

$disconnect()が呼び出されると、クエリエンジンは停止し、データベース接続は閉じられます。

以下の図は「典型的な流れ」を示しています

Prismaクライアントで$connect()が呼び出される
クエリエンジンが起動する
クエリエンジンがデータベースへの接続を確立し、コネクションプールを作成する
Prismaクライアントはデータベースにクエリを送信する準備ができた
PrismaクライアントがfindMany()クエリをクエリエンジンに送信する
クエリエンジンがクエリをSQLに変換し、データベースに送信する
クエリエンジンがデータベースからSQL応答を受信する
クエリエンジンが結果をプレーンなJavaScriptオブジェクトとしてPrismaクライアントに返す
Prismaクライアントで$disconnect()が呼び出される
クエリエンジンがデータベース接続を閉じる
クエリエンジンが停止する

Typical flow of the query engine at run time

クエリエンジンの責任

クエリエンジンは、Prismaクライアントを使用するアプリケーションにおいて以下の責任を負います。

コネクションプール内の物理データベース接続を管理する
PrismaクライアントNode.jsプロセスから受信クエリを受け取る
SQLクエリを生成する
SQLクエリをデータベースに送信する
データベースからの応答を処理し、Prismaクライアントに送り返す

クエリエンジンのデバッグ

クエリエンジンのログには、DEBUG環境変数をengineに設定することでアクセスできます。

export DEBUG="engine"

また、Prismaクライアントでqueryログレベルを設定することで、クエリエンジンによって生成されるSQLクエリをより詳細に可視化できます。

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

デバッグとロギングについて詳しくはこちら。

クエリエンジンの構成

Prismaクライアントのクエリエンジンタイプを定義する

上記で説明したように、デフォルトのクエリエンジンはPrismaクライアントにロードされる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クライアントとPrisma CLIで使用されるエンジンタイプを構成する方法はありませんでした。
バージョン2.20.0から3.xまでは、libraryエンジンタイプが利用可能で、プレビュー機能フラグ "nApi"を有効にするか、PRISMA_FORCE_NAPI=true環境変数を使用することでデフォルトで利用されていました。

Prisma CLIのクエリエンジンタイプを定義する

Prisma CLIも独自のニーズのために独自のクエリエンジンを使用します。環境変数PRISMA_CLI_QUERY_ENGINE_TYPE=binaryを定義することで、クエリエンジンのバイナリバージョンを使用するように構成できます。

Prismaエンジン​

カスタムエンジンライブラリまたはバイナリの使用​

環境変数の設定​

a) .envファイル​

b) グローバル環境変数​

環境変数のテスト​

エンジンのホスティング​

クエリエンジンファイル​

実行時のクエリエンジン​

クエリエンジンの責任​

クエリエンジンのデバッグ​

クエリエンジンの構成​

Prismaクライアントのクエリエンジンタイプを定義する​

Prisma CLIのクエリエンジンタイプを定義する​