エンジン
技術的な観点から見ると、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
(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
(イントロスペクションエンジン)
環境変数の設定
環境変数は、マシン全体または.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クライアントとクエリエンジンの間の通信オーバーヘッドを削減するため推奨されます。
クエリエンジンは、最初のPrismaクライアントクエリが呼び出されたとき、またはPrismaClient
インスタンスで$connect()
メソッドが呼び出されたときに開始されます。クエリエンジンが開始されると、コネクションプールを作成し、データベースへの物理接続を管理します。それ以降、Prismaクライアントはデータベースにクエリ(例: findUnique()
、findMany
、create
など)を送信する準備ができます。
$disconnect()
が呼び出されると、クエリエンジンは停止し、データベース接続は閉じられます。
以下の図は「典型的な流れ」を示しています
- Prismaクライアントで
$connect()
が呼び出される - クエリエンジンが起動する
- クエリエンジンがデータベースへの接続を確立し、コネクションプールを作成する
- Prismaクライアントはデータベースにクエリを送信する準備ができた
- Prismaクライアントが
findMany()
クエリをクエリエンジンに送信する - クエリエンジンがクエリをSQLに変換し、データベースに送信する
- クエリエンジンがデータベースからSQL応答を受信する
- クエリエンジンが結果をプレーンなJavaScriptオブジェクトとしてPrismaクライアントに返す
- Prismaクライアントで
$disconnect()
が呼び出される - クエリエンジンがデータベース接続を閉じる
- クエリエンジンが停止する
クエリエンジンの責任
クエリエンジンは、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
を定義することで、クエリエンジンのバイナリバージョンを使用するように構成できます。