メインコンテンツにスキップ

エンジン

技術的な観点から、Prisma Clientは3つの主要なコンポーネントで構成されています

  • 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にもコピーされます。カスタムライブラリまたはバイナリファイルを使用したい場合があります。

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

バイナリのカスタムロケーションを指定するには、次の環境変数を使用します

警告
  • 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

注：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バケット、またはその他のクラウドストレージを介してエンジンファイルをホストできます。これは、カスタムビルドエンジンを必要とするカスタム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 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クエリが呼び出されたとき、または$connect()メソッドがPrismaClientインスタンスで呼び出されたときに起動されます。クエリエンジンが起動すると、接続プールを作成し、データベースへの物理接続を管理します。その時点から、Prisma Clientはクエリをデータベースに送信する準備ができています（例：findUnique()、findMany、createなど）。

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

次の図は、「典型的なフロー」を示しています

  1. $connect()がPrisma Clientで呼び出されます
  2. クエリエンジンが起動されます
  3. クエリエンジンはデータベースへの接続を確立し、接続プールを作成します
  4. Prisma Clientはデータベースにクエリを送信する準備ができました
  5. Prisma ClientはfindMany()クエリをクエリエンジンに送信します
  6. クエリエンジンはクエリをSQLに変換し、データベースに送信します
  7. クエリエンジンはデータベースからSQL応答を受信します
  8. クエリエンジンは結果をプレーンな古いJavaScriptオブジェクトとしてPrisma Clientに返します
  9. $disconnect()がPrisma Clientで呼び出されます
  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を定義することで、クエリエンジンのバイナリバージョンを使用するように構成できます。