Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

1.2. データソースを設定する

次のセクションでは、単一または複数データソースの設定を説明します。説明をシンプルにするために、単一データソースをデフォルトデータソース (名前なし) とします。

1.2.1. 単一データソースを設定する
リンクのコピー

データソースは、JDBC データソース、リアクティブ、またはその両方になります。これは、プロジェクトエクステンションの設定と選択に応じて決定されます。

  1. 次の設定プロパティーを使用してデータソースを定義します。この場合の db-kind は、接続先のデータベースプラットフォーム (例: h2) を定義します。 

    quarkus.datasource.db-kind=h2
    Copy to Clipboard Toggle word wrap

    Quarkus は、db-kind データベースプラットフォーム属性に指定された値から、使用するべき JDBC ドライバークラスを推定します。

    注記

    この手順は、アプリケーションが複数のデータベースドライバーに依存する場合にのみ必要です。アプリケーションが単一のドライバーで動作する場合、ドライバーは自動的に検出されます。

    Quarkus には現在、次の種類のビルトインデータベースがあります。

    • DB2: db2

    • Derby: derby

      注記

      以前のリリースで非推奨となった Apache Derby データベースのサポートは、Red Hat ビルドの Quarkus 3.27 で削除されました。

    • H2: h2
    • MariaDB: mariadb
    • Microsoft SQL Server: mssql
    • MySQL: mysql
    • Oracle: oracle
    • PostgreSQL: postgresql、pgsql または pg

    • ビルトインではない種類のデータベースを使用する場合は other を使用し、JDBC ドライバーを明示的に定義します。

      注記

      カスタムデータベースとドライバー で説明されているように、JVM モードの Quarkus アプリケーションでは任意の JDBC ドライバーを使用できます。ただし、ビルトイン以外の種類のデータベースを使用すると、アプリケーションをネイティブ実行可能ファイルにコンパイルする際に機能しない可能性が高くなります。

      ネイティブ実行可能ファイルのビルドの場合、利用可能な JDBC Quarkus エクステンションを使用するか、使用する特定のドライバー用のカスタムエクステンションを提供することが推奨されます。

  2. 次のプロパティーを設定して認証情報を定義します。 

    quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>
    Copy to Clipboard Toggle word wrap

    データソースの 認証情報プロバイダーを使用 して、Vault からパスワードを取得することもできます。

これまでは、JDBC とリアクティブドライバーのどちらを使用しているかにかかわらず、設定は同じでした。データベースの種類と認証情報の定義以外は、使用しているドライバーの種類により異なります。JDBC とリアクティブドライバーは、同時に使用できます。

1.2.1.1. JDBC データソース
リンクのコピー

JDBC は最も一般的なデータベース接続パターンであり、通常は非リアクティブな Hibernate ORM と組み合わせて使用する場合に必要です。

  1. JDBC データソースを使用する場合は、まず必要な依存関係を追加します。

    1. ビルトイン JDBC ドライバーで使用する場合は、以下のリストからリレーショナルデータベースドライバーの Quarkus エクステンションを選択して追加します。

      • Derby - quarkus-jdbc-derby

        注記

        以前のリリースで非推奨となった Apache Derby データベースのサポートは、Red Hat ビルドの Quarkus 3.27 で削除されました。

      • H2 - quarkus-jdbc-h2

        注記

        H2 データベースと Derby データベースは、"組み込みモード" で実行するように設定できます。ただし、Derby エクステンションでは、組み込みデータベースエンジンのネイティブ実行可能ファイルへのコンパイルはサポートされていません。

        結合テストに関する提案事項については、in-memory データベースを使用してテストする を参照してください。

      • DB2 - quarkus-jdbc-db2
      • MariaDB - quarkus-jdbc-mariadb
      • Microsoft SQL Server - quarkus-jdbc-mssql
      • MySQL - quarkus-jdbc-mysql
      • Oracle - quarkus-jdbc-oracle

      • PostgreSQL - quarkus-jdbc-postgresql

        たとえば、PostgreSQL ドライバーの依存関係を追加するには、以下を実行します。 

        ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
        Copy to Clipboard Toggle word wrap
        注記

        ビルトイン JDBC ドライバーエクステンションを使用すると、Agroal エクステンションが自動的に組み込まれます。これは、カスタムおよびビルトインの JDBC ドライバーに適用できる JDBC 接続プール実装です。ただし、カスタムドライバーの場合は、Agroal を明示的に追加する必要があります。

    2. カスタム JDBC ドライバーで使用するには、リレーショナルデータベースドライバーのエクステンションとともに quarkus-agroal 依存関係をプロジェクトに追加します。 

      ./mvnw quarkus:add-extension -Dextensions="agroal"
      Copy to Clipboard Toggle word wrap

      別のデータベースの JDBC ドライバーを使用するには、ビルトインエクステンションがない、または別のドライバーがあるデータベースを使用 します。

  2. JDBC URL プロパティーを定義して JDBC 接続を設定します。 

    quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
    Copy to Clipboard Toggle word wrap
    注記

    プロパティー名の接頭辞 jdbc に注意してください。JDBC 固有のすべての設定プロパティーには、接頭辞として jdbc が付いています。リアクティブデータソースの場合、接頭辞は reactive です。

JDBC の設定の詳細は、JDBC URL フォーマットのリファレンス および Quarkus エクステンションとデータベースドライバーのリファレンス を参照してください。

1.2.1.1.1. カスタムデータベースとドライバー
リンクのコピー

お使いのデータベース用の JDBC エクステンションが Quarkus にない場合、または OpenTelemetry 用などの別の JDBC ドライバーを使用する必要がある場合は、JDBC ドライバーを明示的に設定できます。

エクステンションがない場合も、JDBC ドライバーは JVM モードで正しく動作すると予想されます。しかし、アプリケーションをネイティブ実行可能ファイルにコンパイルする際に、ドライバーが機能しない可能性があります。ネイティブ実行可能ファイルをビルドするには、既存の Quarkus JDBC エクステンションを使用するか、ドライバー用の新しいエクステンションを提供してください。

JVM モードでビルトインサポートがないデータベースへのアクセスを定義した例:

quarkus.datasource.db-kind=other
quarkus.datasource.jdbc.driver=oracle.jdbc.driver.OracleDriver
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@192.168.1.12:1521/ORCL_SVC
quarkus.datasource.username=scott
quarkus.datasource.password=tiger
Copy to Clipboard Toggle word wrap

JDBC 設定オプションや、接続プールサイズをはじめとする他の設定に関する詳細は、JDBC 設定リファレンス セクションを参照してください。

1.2.1.1.2. データソースを消費する
リンクのコピー

Hibernate ORM を使用すると、Hibernate レイヤーが自動的にデータソースを取得して使用します。

データソースへの in-code アクセスでは、次のように他の Bean としてデータソースを取得する必要があります。 

@Inject
AgroalDataSource defaultDataSource;
Copy to Clipboard Toggle word wrap

上記の例のタイプは AgroalDataSource、つまり javax.sql.DataSource サブタイプです。そのため、注入されたタイプとして javax.sql.DataSource も使用できます。

1.2.1.1.3. Oracle に関する考慮事項
リンクのコピー

issue #36265 に記載されているように、Oracle は接続を閉じるときに、コミットされていないトランザクションを予期しない形でコミットします。そのため、Quarkus を停止すると、進行中のトランザクションが未完了の状態でコミットされる可能性があります。

この動作は想定外のものであり、データの損失につながる可能性があります。そのため、接続を閉じるときに、インターセプターが未完了のトランザクションをロールバックします。ただし、XA トランザクションを使用する場合は、トランザクションマネージャーがロールバックを処理します。

3.18 で導入された動作によってワークロードに問題が発生する場合は、-Dquarkus-oracle-no-automatic-rollback-on-connection-close システムプロパティーを true に設定して、この動作を無効にしてください。より永続的な設定などにより、必要に応じてこの動作を調整できるように、Issue トラッカー でユースケースの報告をお願いします。

1.2.1.2. リアクティブデータソース
リンクのコピー

Quarkus では、リアクティブデータソースで使用できるリアクティブクライアントがいくつか提供されています。

  1. 対応するエクステンションをアプリケーションに追加します。

    • MariaDB/MySQL: quarkus-reactive-mysql-client
    • Microsoft SQL Server: quarkus-reactive-mssql-client
    • Oracle: quarkus-reactive-oracle-client

    • PostgreSQL: quarkus-reactive-pg-client

      インストールされたエクステンションは、データソース設定で定義した quarkus.datasource.db-kind と一致する必要があります。

  2. ドライバーを追加した後、接続 URL を設定し、接続プールの適切なサイズを定義します。 

    quarkus.datasource.reactive.url=postgresql:///your_database
quarkus.datasource.reactive.max-size=20
    Copy to Clipboard Toggle word wrap
1.2.1.2.1. リアクティブ接続プールのサイズ調整
リンクのコピー

負荷のピーク時の過負荷からデータベースを保護するには、データベースの負荷にスロットリングを適用できるようプールサイズを適切に設定します。適切なサイズは、並列アプリケーションユーザーの数やワークロードの性質など、多くの要因により異なります。

プールサイズの設定が小さすぎると、接続の待機中に一部のリクエストがタイムアウトになる可能性があることに注意してください。

プールサイズ調整プロパティーの詳細は、リアクティブデータソース設定リファレンス セクションを参照してください。

1.2.1.3. JDBC データソースとリアクティブデータソースの同時使用
リンクのコピー

同じデータベースの種類用の JDBC エクステンションとリアクティブデータソースエクステンションが両方とも含まれている場合、デフォルトで JDBC データソースとリアクティブデータソースの両方が作成されます。

  • JDBC データソースと リアクティブ データソースを同時に使用するには、次の設定を使用します。 

    %prod.quarkus.datasource.reactive.url=postgresql:///your_database
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
    Copy to Clipboard Toggle word wrap

JDBC データソースとリアクティブデータソースの両方を作成しない場合は、次の設定を使用します。

  • JDBC データソースを明示的に無効にするには、以下を実行します。 

    quarkus.datasource.jdbc=false
    Copy to Clipboard Toggle word wrap

  • リアクティブデータソースを明示的に無効にするには、以下を実行します。 

    quarkus.datasource.reactive=false
    Copy to Clipboard Toggle word wrap
    ヒント

    ほとんどの場合、JDBC ドライバーとリアクティブデータソースエクステンションは、両方ではなくいずれか一方のみ存在するため、上記の設定はオプションです。

1.2.2. 複数のデータソースを設定する
リンクのコピー

注記

Hibernate ORM エクステンションは、設定プロパティーを使用した 永続ユニット の定義をサポートしています。永続ユニットごとに、選択したデータソースを参照できます。

複数のデータソースを定義することは、単一のデータソースを定義するのと同じように機能しますが、重要な相違点として名前 (設定プロパティー) を定義する必要があります。

次の例では、3 つの異なるデータソースを示しています。

  • デフォルトのデータソース
  • users という名前のデータソース
  • inventory という名前のデータソース

それぞれの設定は次のとおりです。 

quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:mem:default
quarkus.datasource.jdbc.max-size=13

quarkus.datasource.users.db-kind=h2
quarkus.datasource.users.username=username1
quarkus.datasource.users.jdbc.url=jdbc:h2:mem:users
quarkus.datasource.users.jdbc.max-size=11

quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:mem:inventory
quarkus.datasource.inventory.jdbc.max-size=12
Copy to Clipboard Toggle word wrap

設定プロパティーに追加のセクションがあることに注意してください。構文は quarkus.datasource.[optional name.][datasource property] です。

注記

データベースエクステンションが 1 つだけインストールされている場合でも、Quarkus がそれを検出できるように、名前付きデータベースは少なくとも 1 つのビルドタイムプロパティーを指定する必要があります。通常、これは db-kind プロパティーですが、Dev Services for Databases ガイドに従って、名前付きデータソースを作成するために Dev Services プロパティーを指定することもできます。

1.2.2.1. 名前付きデータソースの注入
リンクのコピー

複数のデータソースを使用する場合、各 DataSource には、データソースの名前を値として持つ io.quarkus.agroal.DataSource 修飾子もあります。

前のセクションで説明したプロパティーを使用して 3 つの異なるデータソースを設定し、それぞれを次のように注入します。 

@Inject
AgroalDataSource defaultDataSource;

@Inject
@DataSource("users")
AgroalDataSource usersDataSource;

@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;
Copy to Clipboard Toggle word wrap

1.2.3. データソースをアクティブ化または非アクティブ化する
リンクのコピー

データソースがビルド時に設定され、その URL が実行時に設定されると、そのデータソースはデフォルトでアクティブになります。Quarkus は、アプリケーションの起動時に対応する JDBC 接続プールまたはリアクティブクライアントを起動します。

実行時にデータソースを非アクティブ化するには、次のいずれかを実行します。

  • quarkus.datasource[.optional name].jdbc.url または quarkus.datasource[.optional name].reactive.url を設定しない。
  • quarkus.datasource[.optional name].active を false に設定する。

データソースがアクティブでない場合:

  • データソースは、アプリケーションの起動中にデータベースへの接続を試行しません。
  • データソースは ヘルスチェック に影響しません。
  • データソースに関連する静的 CDI インジェクションポイント (@Inject DataSource ds や @Inject Pool pool など) により、アプリケーションの起動が失敗します。
  • CDI.getBeanContainer()、Arc.instance()、または Instance<DataSource> の注入などによるデータソースの動的な取得により、例外が出力されます。

  • データソースを使用するその他の Quarkus エクステンションにより、アプリケーションの起動が失敗する可能性があります。

    この場合、他のエクステンションも非アクティブ化する必要があります。このシナリオの例は、Hibernate ORM ガイドの こちらのセクション を参照してください。

この機能は、実行時にアプリケーションが定義済みのセットから 1 つのデータソースを選択する必要がある場合に特に便利です。

実行時に選択する複数のデータソースを設定する例:

quarkus.datasource."pg".db-kind=postgres
quarkus.datasource."pg".active=false
quarkus.datasource."pg".jdbc.url=jdbc:postgresql:///your_database

quarkus.datasource."oracle".db-kind=oracle
quarkus.datasource."oracle".active=false
quarkus.datasource."oracle".jdbc.url=jdbc:oracle:thin:@localhost:1521/your_database
Copy to Clipboard Toggle word wrap

実行時 に quarkus.datasource."pg".active=true を設定すると、PostgreSQL データソースのみが使用可能になります。実行時に quarkus.datasource."oracle".active=true を設定すると、Oracle データソースのみが使用可能になります。

ヒント

カスタム設定プロファイル を使用すると、このセットアップが簡素化されます。上記の設定に次のプロファイル固有の設定を追加することで、quarkus.profile を設定 して実行時に永続ユニットまたはデータソースを選択できます。たとえば、quarkus.profile=prod,pg または quarkus.profile=prod,oracle を使用します。 

%pg.quarkus.hibernate-orm."pg".active=true
%pg.quarkus.datasource."pg".active=true
# Add any PostgreSQL-related runtime configuration here, prefixed with "%pg."

%oracle.quarkus.hibernate-orm."oracle".active=true
%oracle.quarkus.datasource."oracle".active=true
# Add any Oracle-related runtime configuration here, prefixed with "%oracle."
Copy to Clipboard Toggle word wrap

この設定により、アクティブ なデータソースにのみアクセスできるようになります。これを実現するには、@Any 修飾子を持つ InjectableInstance<DataSource> または InjectableInstance<Pool> を注入し、getActive() を呼び出します。 

import io.quarkus.arc.InjectableInstance;
@ApplicationScoped
public class MyConsumer {
    @Inject
    @Any
    InjectableInstance<DataSource> dataSource;

    public void doSomething() {
        DataSource activeDataSource = dataSource.getActive();
        // ...
    }
}
Copy to Clipboard Toggle word wrap

または、デフォルトのデータソース用の CDI Bean プロデューサー を定義することもできます。この Bean プロデューサーは、現在アクティブな名前付きデータソースにリダイレクトします。これにより、以下に示すように、デフォルトのデータソースを直接注入できるようになります。 

public class MyProducer {
    @Inject
    @DataSource("pg")
    InjectableInstance<DataSource> pgDataSourceBean;
1 


    @Inject
    @DataSource("oracle")
    InjectableInstance<DataSource> oracleDataSourceBean;

    @Produces
2 

    @ApplicationScoped
    public DataSource dataSource() {
        if (pgDataSourceBean.getHandle().getBean().isActive()) {
3 

            return pgDataSourceBean.get();
        } else if (oracleDataSourceBean.getHandle().getBean().isActive()) {
4 

            return oracleDataSourceBean.get();
        } else {
            throw new RuntimeException("No active datasource!");
        }
    }
}

@ApplicationScoped
public class MyConsumer {
    @Inject
    DataSource dataSource;
5 


    public void doSomething() {
        // .. just use the injected datasource ...
    }
}
Copy to Clipboard Toggle word wrap
1
DataSource または AgroalDatasource を直接注入しないでください。非アクティブな Bean を注入すると、起動が失敗します。代わりに、InjectableInstance<DataSource> または InjectableInstance<AgroalDataSource> を注入してください。
2
CDI プロデューサーメソッドを宣言してデフォルトのデータソースを定義します。PostgreSQL または Oracle のうち、アクティブなものを選択します。
3 4
Bean を取得する前に、それがアクティブかどうかを確認します。
5
唯一のアクティブなデータソースを注入します。

1.2.4. 単一のトランザクションで複数のデータソースを使用する
リンクのコピー

デフォルトでは、データソースでの XA サポートが無効になっています。したがって、トランザクションに 1 つのデータソースしか含めることができません。同じトランザクションで複数の非 XA データソースにアクセスしようとすると、次のような例外が発生します。 

...
Caused by: java.sql.SQLException: Exception in association of connection to existing transaction
        at io.agroal.narayana.NarayanaTransactionIntegration.associate(NarayanaTransactionIntegration.java:130)
        ...
Caused by: java.sql.SQLException: Failed to enlist. Check if a connection from another datasource is already enlisted to the same transaction
        at io.agroal.narayana.NarayanaTransactionIntegration.associate(NarayanaTransactionIntegration.java:121)
        ...
Copy to Clipboard Toggle word wrap

同じトランザクションで複数の JDBC データソースを使用できるようにするには、次の手順を実行します。

  1. JDBC ドライバーが XA をサポートしていることを確認します。すべての サポート対象 JDBC ドライバーはサポートしています が、他の JDBC ドライバー はサポートしていない可能性があります。
  2. データベースサーバーが XA を有効化するように設定されていることを確認します。
  3. quarkus.datasource[.optional name].jdbc.transactions を xa に設定して、関連する各データソースに対して XA サポートを明示的に有効にします。

XA を使用すると、1 つのデータソースでのロールバックにより、トランザクションに登録されている他のすべてのデータソースでのロールバックがトリガーされます。

注記

現時点では、リアクティブデータソース上の XA トランザクションはサポートされていません。

注記

トランザクションにデータソース以外のリソースが含まれる場合は、そのリソースで XA トランザクションがサポートされていない可能性や、追加の設定が必要になる可能性があることに注意してください。

1 つのデータソースに対して XA を有効にできない場合:

  • その場合でも、Last Resource Commit Optimization (LRCO) を使用することで、1 つ (複数は不可) を除くすべてのデータソースに対して XA を有効にできます。
  • 1 つのデータソースのロールバックによって他のデータソースのロールバックをトリガーする必要がない場合は、コードを複数のトランザクションに分割することを検討してください。これを行うには、QuarkusTransaction.requiringNew()/@Transactional(REQUIRES_NEW) (推奨) または UserTransaction (より複雑なユースケースの場合) を使用します。
Important

他の解決策が機能せず、Quarkus 3.8 以前との互換性が必要な場合は、quarkus.transaction-manager.unsafe-multiple-last-resources を allow に設定して、複数の非 XA データソース間での安全でないトランザクション処理を有効にしてください。

このプロパティーを allow に設定すると、トランザクションのロールバックが、最後の非 XA データソースにのみ適用されます。他の非 XA データソースは、すでに変更をコミットしている可能性があります。これにより、システムが不整合な状態になる可能性があります。

または、そのような安全でない動作を許可し、その動作が発生した場合に警告を記録します。

  • プロパティーを warn-each に設定すると、問題のある それぞれ のトランザクションの警告が記録されます。
  • プロパティーを warn-first に設定すると、問題のある 最初 のトランザクションの警告が記録されます。

この設定プロパティーの使用は推奨されません。このプロパティーは今後、削除される予定です。アプリケーションを適宜更新してください。このプロパティーを維持することがユースケース上妥当であると思われる場合は、Quarkus トラッカー で Issue を作成し、その理由を説明してください。

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat