1.3. データソースのインテグレーション

quarkus-smallrye-health エクステンションを使用する場合は、quarkus-agroal エクステンションおよびリアクティブクライアントエクステンションが自動的にレディネスヘルスチェックを追加してデータソースを検証します。

アプリケーションのヘルスレディネスエンドポイント (デフォルトは /q/health/ready) にアクセスすると、データソースの検証ステータスに関する情報を受け取ります。複数のデータソースがある場合はすべてのデータソースがチェックされ、そのうちの 1 つでもデータソース検証に失敗すると、ステータスが DOWN に遷移します。

この動作は、quarkus.datasource.health.enabled プロパティーを使用して無効にできます。

特定のデータソースのみをヘルスチェックから除外するには、以下を使用します。

quarkus.datasource."datasource-name".health-exclude=true

quarkus.datasource."datasource-name".health-exclude=true

quarkus-micrometer または quarkus-smallrye-metrics エクステンションを使用している場合、quarkus-agroal はいくつかのデータソース関連のメトリクスをメトリクスレジストリーに提供できます。これは、quarkus.datasource.metrics.enabled プロパティーを true に設定することでアクティブ化できます。

メトリクスに実際の値を含むメトリクスを公開するには、Agroal メカニズムを使用して内部でメトリクスを有効にする必要があります。メトリクスエクステンションが存在し、Agroal エクステンションのメトリクスが有効になっている場合、このメトリクス収集メカニズムはデフォルトですべてのデータソースに対して有効になります。

特定のデータソースのメトリクスを無効にするには、quarkus.datasource.jdbc.enable-metrics を false に設定するか、名前付きデータソースに quarkus.datasource.<datasource name>.jdbc.enable-metrics を適用します。これにより、収集メカニズムが無効の場合は、メトリクスの収集と /q/metrics エンドポイントへの公開が無効になります。

逆に、quarkus.datasource.jdbc.enable-metrics を true に設定するか、名前付きデータソースに quarkus.datasource.<datasource name>.jdbc.enable-metrics を設定すると、メトリクスエクステンションが使用されていない場合でもメトリクス収集が明示的に有効になります。これは、収集されたメトリクスにプログラムを使用してアクセスする必要がある場合に役立ちます。これらは、注入された AgroalDataSource インスタンスで dataSource.getMetrics() を呼び出すと使用可能になります。

このデータソースのメトリクス収集が無効になっている場合、すべての値はゼロになります。

データソースでトレースを使用するには、quarkus-opentelemetry エクステンションをプロジェクトに追加する必要があります。

トレースを有効にするために別のドライバーを宣言する必要はありません。JDBC ドライバーを使用する場合は、OpenTelemetry エクステンションの手順 に従う必要があります。

すべてのトレースインフラストラクチャーが整っていても、データソーストレースはデフォルトでは有効になっていません。そのため、次のプロパティーを設定して有効にする必要があります。

enable tracing

# enable tracing
quarkus.datasource.jdbc.telemetry=true

Narayana JTA エクステンションも使用できる場合、インテグレーションは自動的に行われます。

これは、transactions 設定プロパティーを設定することでオーバーライドできます。

quarkus.datasource[.optional name].jdbc.transactions=xa を設定してデータソースを XA トランザクション用に設定し、quarkus.transaction-manager.enable-recovery=true を使用してトランザクションリカバリーシステムを有効にすると、データソースは自動的にリカバリー用に登録されます。これは推奨される安全なデフォルトです。quarkus.datasource.jdbc.enable-recovery=false または quarkus.datasource."datasource-name".jdbc.enable-recovery=false 設定することで、個々のデータソースに対してこの動作をオーバーライドできます。

詳細は、後述の 設定リファレンス セクションを参照してください。データベースへのトランザクションログの保存を JDBC を使用して容易にするには、Using transactions in Quarkus ガイドの Configuring transaction logs to be stored in a datasource セクションを参照してください。

H2 や Derby などの一部のデータベースは、結合テストを迅速に実行するファシリティーとして頻繁に 組み込みモード で使用されます。

推奨されるアプローチは、実稼働環境に可能な限り近い結果を得るために、実稼働環境向けのデータベースを使用することです。これは Dev Services を使用すると容易になります。設定が不要で、起動が比較的高速なためです。ただし、単純な結合テストを実行する機能が必要なシナリオでは、JVM 対応データベースを使用することもできます。