The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

Quarkusでデータソースを設定

統一された設定モデルを使用して、Java Database Connectivity (JDBC) および Reactive ドライバのデータソースを定義します。

アプリケーションは、データソースを使用してリレーショナルデータベースにアクセスします。 Quarkusは、Java Database Connectivity（JDBC）およびReactiveデータベースドライバー用のデータソースを定義するための統一された設定モデルを提供します。

Quarkus uses Agroal and Vert.x to provide high-performance, scalable datasource connection pooling for JDBC and reactive drivers. The quarkus-jdbc-* and quarkus-reactive-*-client extensions provide build time optimizations and integrate configured datasources with Quarkus features like security, health checks, and metrics.

リアクティブデータソースの消費と使用に関する詳細は、Quarkus Reactive SQLクライアントガイド を参照してください。

さらに、JDBCデータソースの消費と使用については、Quarkus Hibernate ORM ガイドを参照してください。

Quarkusでの datasources の設定入門

For users familiar with the fundamentals, this section provides an overview and code samples to set up datasources quickly.

より高度な設定とその例については、 参照 を参照してください。

開発モードでのゼロコンフィグセットアップ

Quarkusでは、Dev Services機能によってデータベース設定が簡素化され、テストや開発（dev）モードでの実行のためのデータベース設定をゼロコンフィギュレーションで行うことができます。 開発モードでは、DevServicesを使用してQuarkusにデータベースを処理させる方法が推奨されます。一方、本番モードでは、Quarkusの外部で管理されるデータベースを指す明示的なデータベース設定の詳細を記述してください。

Dev Servicesを使用するには、 pom.xml ファイルに、希望するデータベースタイプに適したドライバエクステンション（ jdbc-postgresql など）を追加します。 開発モードでは、明示的なデータベース接続の詳細を記述しない場合、Quarkusが自動的にデータベースのセットアップを行い、アプリケーションとデータベース間の接続を行います。

ユーザークレデンシャルを指定すると、基礎となるデータベースはそのクレデンシャルを使用するように設定されます。 これは、外部ツールでデータベースに接続したい場合に便利です。

この機能を使用するには、データベースの種類に応じて、DockerまたはPodmanコンテナランタイムがインストールされているようにして下さい。H2などの一部のデータベースはインメモリモードで動作するため、コンテナランタイムは必要ありません。

prodモードの実際の接続詳細の前に %prod. を付けて、それらがdev モードで適用されないようにします。 詳細については、"設定リファレンス" ガイドの Profiles セクションを参照してください。

Dev Services の詳細については、 Dev Services の概要 を参照してください。

詳細およびオプション設定については、 Dev Services for databases を参照してください。

JDBC データソースの設定

  1. 選択したデータベースの正しい JDBC エクステンションを追加します。

    • quarkus-jdbc-db2

    • quarkus-jdbc-derby

    • quarkus-jdbc-h2

    • quarkus-jdbc-mariadb

    • quarkus-jdbc-mssql

    • quarkus-jdbc-mysql

    • quarkus-jdbc-oracle

    • quarkus-jdbc-postgresql

  2. JDBC データソースを設定します：

    quarkus.datasource.db-kind=postgresql (1)
quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>

quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
quarkus.datasource.jdbc.max-size=16
    1 この設定値は、クラスパスに複数のデータベース・エクステンションがある場合にのみ必要です。

使用可能なエクステンションが1つしかない場合、Quarkusはこれを正しいエクステンションとみなします。テストスコープにドライバーを追加すると、Quarkusは自動的に指定したドライバーをテストに含めます。

JDBC接続プールのサイズ調整

負荷のピーク時の過負荷からデータベースを保護するには、データベースの負荷を軽減するためにプールのサイズを適切に設定します。 最適なプールのサイズは、並列アプ リ ケーシ ョ ンのユーザー数や作業負荷の性質な ど、 さ ま ざ ま な要因に よ っ て異な り ます。

プールサイズを小さく設定しすぎると、接続待ちの間にタイムアウトする リクエストが出てくるかもしれないことに注意してください。

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

Reactiveデータソースの設定

  1. 選択したデータベースの正しいリアクティブエクステンションを追加します。

    • quarkus-reactive-db2-client

    • quarkus-reactive-mssql-client

    • quarkus-reactive-mysql-client

    • quarkus-reactive-oracle-client

    • quarkus-reactive-pg-client

  2. リアクティブデータソースを設定します：

    quarkus.datasource.db-kind=postgresql (1)
quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>

quarkus.datasource.reactive.url=postgresql:///your_database
quarkus.datasource.reactive.max-size=20
    1 この設定値は、クラスパスに複数の Reactive ドライバー・エクステンションがある場合にのみ必要です。

データソースの設定

以下のセクションでは、単一または複数のデータソースの設定について説明します。 ここでは簡単のため、単一のデータソースをデフォルトの (無名の) データソースとして参照します。

単一のデータソースの設定

データソースには、JDBC データソース、リアクティブ、またはその両方を指定できます。 これは、設定とプロジェクトエクステンションの選択に依存します。

  1. 以下の設定プロパティでデータソースを定義します。 db-kind は、どのデータベースプラットフォームに接続するかを定義します。例えば、 h2 の場合:

    quarkus.datasource.db-kind=h2

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

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

    Quarkusには現在、以下のデータベースのdb-kindが組み込まれています：

    • DB2: db2

    • Derby: derby

    • H2: h2

    • MariaDB: mariadb

    • Microsoft SQL Server: mssql

    • MySQL: mysql

    • Oracle: oracle

    • PostgreSQL: postgresql、pgsql、または pg

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

      You can use any JDBC driver in a Quarkus app in JVM mode as described in Custom databases and drivers. However, using a non-built-in database kind is unlikely to work when compiling your application to a native executable.

      ネイティブ実行可能ファイルをビルドする場合は、利用可能なJDBC Quarkusエクステンションを使用するか、特定のドライバ用にカスタムエクステンションを作成することをお勧めします。

  2. 以下のプロパティを設定し、クレデンシャルを定義します：

    quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>

    また、データソースに クレデンシャルプロバイダを使用することで、Vault からパスワードを取得することもできます。

これまでは、JDBC ドライバとReactiveドライバのどちらを使用していても、設定は同じでした。データベースの種類とクレデンシャルを定義したら、あとは使用するドライバの種類に依存します。JDBC とReactive・ドライバを同時に使用することは可能です。

JDBC データソース

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

  1. JDBC データソースを使用するには、必要な依存関係を追加することから始めます：

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

      • Derby - quarkus-jdbc-derby

      • H2 - quarkus-jdbc-h2

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

        結合テストに関する提案については、 インメモリデータベースを使ったテスト をお読みください。

      • 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

      • Other JDBC extensions, such as SQLite and its documentation, can be found in the Quarkiverse.

        例えば、PostgreSQLドライバー依存関係を追加します：

        ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"

        組込JDBC ドライバのエクステンションを使用すると、カスタムと組込JDBC ドライバーに適用可能な JDBC 接続プールの実装である Agroal エクステンションが自動的に含まれます。 しかし、カスタムドライバーの場合、Agroal を明示的に追加する必要があります。

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

      ./mvnw quarkus:add-extension -Dextensions="agroal"

      別のデータベース用の JDBC ドライバーを使用するには、 組込エクステンションのないデータベースか、別のドライバー を使用してください。

  2. JDBC URL プロパティを定義して、JDBC 接続を構成します:

    quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test

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

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

カスタムデータベースとドライバー

If Quarkus does not provide a JDBC extension for your database, or you need to use a different JDBC driver, such as one for OpenTelemetry, you can configure the JDBC driver explicitly.

Without an extension, JDBC drivers are expected to work correctly in JVM mode. However, they are unlikely to function when compiling your application into a native executable. To build a native executable, use an existing Quarkus JDBC extension or contribute a new extension for your driver.

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

JDBC設定オプションや、接続プール・サイズなどの他の側面の設定に関するすべての詳細については、 JDBC構成リファレンス セクションを参照してください。

データソースの消費

Hibernate ORMを使用する場合、Hibernateレイヤーは自動的にデータソースを選択し、それを使用します。

データソースへのコード内アクセスは、他のBeanと同様に以下のように取得します：

@Inject
AgroalDataSource defaultDataSource;

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

Oracle considerations

As documented in issue #36265, Oracle has a very weird behavior of committing the uncommitted transactions on connection closing.

Which means that when stopping Quarkus for instance, in progress transactions might be committed even if incomplete.

Given that is not the expected behavior and that it could lead to data loss, we added an interceptor that rolls back any unfinished transactions at connection close, provided you are not using XA (in which case the transaction manager handles things for you).

If this behavior introduced in 3.18 causes issues for your specific workload, you can disable it by setting the -Dquarkus-oracle-no-automatic-rollback-on-connection-close system property to true. Please take the time to report your use case in our issue tracker so that we can adjust this behavior if needed.

リアクティブデータソース

Quarkusには、リアクティブデータソースで使用できるリアクティブクライアントがいくつかあります。

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

    • DB2: quarkus-reactive-db2-client

    • 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
リアクティブ接続プールのサイズ調整

負荷のピーク時の過負荷からデータベースを保護するには、データベースの負荷を軽減するためにプールのサイズを適切に設定します。 適切なサ イ ズは常に、 並列アプ リ ケーシ ョ ンのユーザー数や作業負荷の性質な ど、 さ ま ざ ま な要因に よ っ て異な り ます。

プールサイズを小さく設定しすぎると、接続待ちの間にタイムアウトする リクエストが出てくるかもしれないことに注意してください。

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

JDBC とリアクティブデータソースの同時利用

When both a JDBC extension and a reactive datasource extension for the same database kind are included, both JDBC and reactive datasources will be created by default.

  • To use the JDBC and reactive datasources simultaneously:

    %prod.quarkus.datasource.reactive.url=postgresql:///your_database
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test

If you do not want to have both a JDBC datasource and a reactive datasource created, use the following configuration.

  • JDBC データソースを明示的に無効にするには、次のようにします:

    quarkus.datasource.jdbc=false

  • リアクティブデータソースを明示的に無効にするには、次のようにします:

    quarkus.datasource.reactive=false

    ほとんどの場合、JDBC ドライバまたはリアクティブ・データソース・エクステンションのどちらかが存在し、両方は存在しないため、上記の構成はオプションになります。

複数のデータソースの設定

Hibernate ORM エクステンションは、設定プロパティを使用した 永続化ユニット の定義をサポートしています。 各固有化ユニットに対して、任意のデータソースを指定します。

複数のデータソースの定義は、単一のデータソースを定義するのと同じように機能しますが、重要な変更点が 1 つあります。それは、各データソースの名前 (設定プロパティ) を指定する必要があることです。

以下の例では、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

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

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

名前付きデータソース注入

複数のデータソースを使用する場合は、各 DataSource にデータソース名を値として指定した io.quarkus.agroal.DataSource 修飾子を付与してください。

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

@Inject
AgroalDataSource defaultDataSource;

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

@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;

Activate or deactivate datasources

When a datasource is configured at build time and its URL is set at runtime, it is active by default. This means that Quarkus will start the corresponding JDBC connection pool or reactive client when the application starts.

To deactivate a datasource at runtime, either:

  • Do not set quarkus.datasource[.optional name].jdbc.url/quarkus.datasource[.optional name].reactive.url.

  • Or set quarkus.datasource[.optional name].active to false.

If a datasource is not active:

  • The datasource will not attempt to connect to the database during application startup.

  • The datasource will not contribute a health check.

  • Static CDI injection points involving the datasource (@Inject DataSource ds or @Inject Pool pool) will cause application startup to fail.

  • Dynamic retrieval of the datasource (e.g. through CDI.getBeanContainer()/Arc.instance(), or by injecting an Instance<DataSource>) will cause an exception to be thrown.

  • Other Quarkus extensions consuming the datasource may cause application startup to fail.

    In such a case, you will also need to deactivate those other extensions. For an example of this scenario, see this section of the Hibernate ORM guide.

This feature is especially useful when you need the application to select one datasource from a predefined set at runtime.

例えば、次のような設定です:

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:///your_database

Setting quarkus.datasource."pg".active=true at runtime will make only the PostgreSQL datasource available, and setting quarkus.datasource."oracle".active=true at runtime will make only the Oracle datasource available.

カスタム設定プロファイル を使用すると、このような設定を簡素化できます。 以下のプロファイル固有の設定を上記の設定に追加することで、 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 pg-related runtime configuration here, prefixed with "%pg."

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

With such a setup, you will need to take care to only ever access the active datasource. To do so, you can inject an InjectableInstance<DataSource> or InjectableInstance<Pool> with an @Any qualifier, and call getActive():

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

    public void doSomething() {
        DataSource activeDataSource = dataSource.getActive();
        // ...
    }
}

Alternatively, you may define a CDI bean producer for the default datasource redirecting to the currently active named datasource, so that it can be injected directly, like this:

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()) { (3)
            return oracleDataSourceBean.get();
        } else {
            throw new RuntimeException("No active datasource!");
        }
    }
}

@ApplicationScoped
public class MyConsumer {
    @Inject
    DataSource dataSource; (4)

    public void doSomething() {
        // .. just use the injected datasource ...
    }
}
1 Don’t inject a DataSource or AgroalDatasource directly, because that would lead to a failure on startup (can’t inject inactive beans). Instead, inject InjectableInstance<DataSource> or InjectableInstance<AgroalDataSource>.
2 Declare a CDI producer method that will define the default datasource as either PostgreSQL or Oracle, depending on what is active.
3 Check whether beans are active before retrieving them.
4 This will get injected with the (only) active datasource.

Use multiple datasources in a single transaction

By default, XA support on datasources is disabled. Therefore, a transaction may include no more than one datasource. Attempting to access multiple non-XA datasources in the same transaction results in an exception similar to the following:

...
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)
        ...

To allow using multiple JDBC datasources in the same transaction:

  1. Make sure your JDBC driver supports XA. All supported JDBC drivers do, but other JDBC drivers might not.

  2. Make sure your database server is configured to enable XA.

  3. Enable XA support explicitly for each relevant datasource by setting quarkus.datasource[.optional name].jdbc.transactions to xa.

Using XA, a rollback in one datasource will trigger a rollback in every other datasource enrolled in the transaction.

XA transactions on reactive datasources are not supported at the moment.

If your transaction involves non-datasource resources, be aware that they might not support XA transactions or might require additional configuration.

If XA cannot be enabled for one of your datasources:

If no other solution works, and to maintain compatibility with Quarkus 3.8 and earlier, set quarkus.transaction-manager.unsafe-multiple-last-resources to allow to enable unsafe transaction handling across multiple non-XA datasources.

With this property set to allow, it might happen that a transaction rollback will only be applied to the last non-XA datasource, while other non-XA datasources have already committed their changes, potentially leaving your overall system in an inconsistent state.

Alternatively, you can allow the same unsafe behavior, but with warnings when it takes effect:

  • Setting the property to warn-each results in logging a warning on each offending transaction.

  • Setting the property to warn-first results in logging a warning on the first offending transaction.

We do not recommend using this configuration property, and we plan to remove it in the future, so you should fix your application accordingly. If you think your use case of this feature is valid and this option should be kept around, open an issue in the Quarkus tracker explaining why.

データソースの統合

データソースのヘルスチェック

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

アプリケーションのヘルスチェックエンドポイント /q/health/ready (デフォルト) にアクセスすると、データソースの検証状況に関する情報を受け取ります。 複数のデータソースがある場合は、すべてのデータソースがチェックされ、データソースの検証に失敗した場合は、ステータスが DOWN に変わります。

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

To exclude only a particular datasource from the health check:

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

データソースのメトリクス

quarkus-micrometer または quarkus-smallrye-metrics エクステンションを使用している場合、 quarkus-agroal は、データソース関連のメトリックをメトリック・レジストリに貢献することができます。これは、 quarkus.datasource.metrics.enabled プロパティを true に設定することで有効になります。

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

To disable metrics for a particular datasource, set quarkus.datasource.jdbc.enable-metrics to false, or apply quarkus.datasource.<datasource name>.jdbc.enable-metrics for a named datasource. This disables collecting the metrics and exposing them in the /q/metrics endpoint if the mechanism to collect them is disabled.

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

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

データソースのトレース

To use tracing with a datasource, you need to add the quarkus-opentelemetry extension to your project.

You do not need to declare a different driver to enable tracing. If you use a JDBC driver, you need to follow the instructions in the OpenTelemetry extension.

Even with all the tracing infrastructure in place, the datasource tracing is not enabled by default, and you need to enable it by setting this property:

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

Narayanaトランザクションマネージャの統合

Narayana JTAエクステンションも利用可能であれば、統合は自動的に行われます。

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

  • quarkus.datasource.jdbc.transactions デフォルトの無名データソースの場合

  • quarkus.datasource. <datasource-name> .jdbc.transactions 名前付きデータソースの場合

詳細については、以下の 設定リファレンス のセクションを参照してください。

jdbcを使用してトランザクションログをデータベースに保存しやすくするには、 Quarkusのトランザクションの使用 ガイドの トランザクションログをデータソースに保存するように設定する セクションを参照してください。

名前付きデータソース

Dev Servicesを使用すると、デフォルトのデータソースが常に作成されますが、名前付きデータソースを指定するには、Quarkusがデータソースの作成方法を検出できるように、少なくとも1つのビルド時プロパティが必要です。

通常、 db-kind プロパティを指定するか、 quarkus.datasource."name".devservices.enabled=true を設定して明示的に Dev Services を有効にします。

インメモリーデータベースを使用したテスト

H2やDerbyのようないくつかのデータベースは、結合テストを迅速に実行するための機能として、 組み込み モードで一般的に使用されています。

特に、 dev Services がテスト用のゼロコンフィグデータベースを提供して おり、コンテナに対してテストを実行すると比較的短時間で実際の環境で期待通りの結果が得られる場合は、本番環境で使用する予定の実際のデータベースを使用することをお勧めします。しかし、単純な統合テストを実行する機能が必要なシナリオでは、JVM で動作するデータベースを使用することも可能です。

サポートと制限

組み込みデータベース(H2およびDerby)はJVMモードで動作します。 ネイティブモードでは、以下の制限が適用されます：

  • Derbyをネイティブモードでアプリケーションに組み込むことはできません。 しかし、Quarkus Derbyエクステンションを使用すると、Derby JDBC クライアント をネイティブにコンパイルして、 リモート 接続をサポートできます。

  • ネイティブイメージにH2を埋め込むことは推奨されません。 例えば、別のデータベースへのリモート接続を使用するなど、別の方法を検討してください。

統合テストの実行

  1. 次の Maven 座標の下にある追加ツールを提供する成果物に依存関係を追加します：

    • io.quarkus:quarkus-test-h2 H2の場合

    • io.quarkus:quarkus-test-derby ダービーの場合

      これにより、アプリケーションをネイティブの実行可能ファイルにコンパイルしても、データベースはJVMプロセスとして実行されます。

  2. JVM とネイティブの実行可能ファイルの両方で統合テストを実行するために、結合テストの任意のクラスに以下の特定のアノテーションを追加します：

    • @QuarkusTestResource(H2DatabaseTestResource.class)

    • @QuarkusTestResource(DerbyDatabaseTestResource.class)

      これにより、テストスイートは、テスト実行に必要な別プロセスで管理データベースを起動し、終了します。

      H2の例
      package my.app.integrationtests.db;

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.h2.H2DatabaseTestResource;

@QuarkusTestResource(H2DatabaseTestResource.class)
public class TestResources {
}

  3. マネージドデータベースへの接続を設定します:

    quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:test

参照

共通データソース設定リファレンス

ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能

Configuration property

型

デフォルト

quarkus.datasource.health.enabled

Whether or not a health check is published in case the smallrye-health extension is present.

This is a global setting and is not specific to a datasource.

Environment variable: QUARKUS_DATASOURCE_HEALTH_ENABLED

Show more

boolean

true

quarkus.datasource.metrics.enabled

Whether or not datasource metrics are published in case a metrics extension is present.

This is a global setting and is not specific to a datasource.

This is different from the "jdbc.enable-metrics" property that needs to be set on the JDBC datasource level to enable collection of metrics for that datasource.

Environment variable: QUARKUS_DATASOURCE_METRICS_ENABLED

Show more

boolean

false

quarkus.datasource.db-kind

quarkus.datasource."datasource-name".db-kind

The kind of database we will connect to (e.g. h2, postgresql…​).

Environment variable: QUARKUS_DATASOURCE_DB_KIND

Show more

string

quarkus.datasource.db-version

quarkus.datasource."datasource-name".db-version

The version of the database we will connect to (e.g. '10.0').

The version number set here should follow the same numbering scheme as the string returned by java.sql.DatabaseMetaData#getDatabaseProductVersion() for your database’s JDBC driver. This numbering scheme may be different from the most popular one for your database; for example Microsoft SQL Server 2016 would be version 13.

As a rule, the version set here should be as high as possible, but must be lower than or equal to the version of any database your application will connect to.

A high version will allow better performance and using more features (e.g. Hibernate ORM may generate more efficient SQL, avoid workarounds and take advantage of more database features), but if it is higher than the version of the database you want to connect to, it may lead to runtime exceptions (e.g. Hibernate ORM may generate invalid SQL that your database will reject).

Some extensions (like the Hibernate ORM extension) will try to check this version against the actual database version on startup, leading to a startup failure when the actual version is lower or simply a warning in case the database cannot be reached.

The default for this property is specific to each extension; the Hibernate ORM extension will default to the oldest version it supports.

Environment variable: QUARKUS_DATASOURCE_DB_VERSION

Show more

string

quarkus.datasource.health-exclude

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

Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled.

By default, the health check includes all configured data sources (if it is enabled).

Environment variable: QUARKUS_DATASOURCE_HEALTH_EXCLUDE

Show more

boolean

false

quarkus.datasource.active

quarkus.datasource."datasource-name".active

Whether this datasource should be active at runtime.

See this section of the documentation.

Environment variable: QUARKUS_DATASOURCE_ACTIVE

Show more

boolean

`true if the URL is set, false otherwise`

quarkus.datasource.username

quarkus.datasource."datasource-name".username

The datasource username

Environment variable: QUARKUS_DATASOURCE_USERNAME

Show more

string

quarkus.datasource.password

quarkus.datasource."datasource-name".password

The datasource password

Environment variable: QUARKUS_DATASOURCE_PASSWORD

Show more

string

quarkus.datasource.credentials-provider

quarkus.datasource."datasource-name".credentials-provider

The credentials provider name

Environment variable: QUARKUS_DATASOURCE_CREDENTIALS_PROVIDER

Show more

string

quarkus.datasource.credentials-provider-name

quarkus.datasource."datasource-name".credentials-provider-name

The credentials provider bean name.

This is a bean name (as in @Named) of a bean that implements CredentialsProvider. It is used to select the credentials provider bean when multiple exist. This is unnecessary when there is only one credentials provider available.

For Vault, the credentials provider bean name is vault-credentials-provider.

Environment variable: QUARKUS_DATASOURCE_CREDENTIALS_PROVIDER_NAME

Show more

string

Dev Services

型

デフォルト

quarkus.datasource.devservices.enabled

quarkus.datasource."datasource-name".devservices.enabled

Whether this Dev Service should start with the application in dev mode or tests.

Dev Services are enabled by default unless connection configuration (e.g. the JDBC URL or reactive client URL) is set explicitly.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_ENABLED

Show more

boolean

quarkus.datasource.devservices.image-name

quarkus.datasource."datasource-name".devservices.image-name

The container image name for container-based Dev Service providers.

This has no effect if the provider is not a container-based database, such as H2 or Derby.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_IMAGE_NAME

Show more

string

quarkus.datasource.devservices.container-env."environment-variable-name"

quarkus.datasource."datasource-name".devservices.container-env."environment-variable-name"

Environment variables that are passed to the container.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_

Show more

Map<String,String>

quarkus.datasource.devservices.container-properties."property-key"

quarkus.datasource."datasource-name".devservices.container-properties."property-key"

Generic properties that are passed for additional container configuration.

Properties defined here are database-specific and are interpreted specifically in each database dev service implementation.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>

quarkus.datasource.devservices.properties."property-key"

quarkus.datasource."datasource-name".devservices.properties."property-key"

Generic properties that are added to the database connection URL.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>

quarkus.datasource.devservices.port

quarkus.datasource."datasource-name".devservices.port

Optional fixed port the dev service will listen to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PORT

Show more

int

quarkus.datasource.devservices.command

quarkus.datasource."datasource-name".devservices.command

The container start command to use for container-based Dev Service providers.

This has no effect if the provider is not a container-based database, such as H2 or Derby.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_COMMAND

Show more

string

quarkus.datasource.devservices.db-name

quarkus.datasource."datasource-name".devservices.db-name

The database name to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_DB_NAME

Show more

string

quarkus.datasource.devservices.username

quarkus.datasource."datasource-name".devservices.username

The username to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_USERNAME

Show more

string

quarkus.datasource.devservices.password

quarkus.datasource."datasource-name".devservices.password

The password to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PASSWORD

Show more

string

quarkus.datasource.devservices.init-script-path

quarkus.datasource."datasource-name".devservices.init-script-path

The paths to SQL scripts to be loaded from the classpath and applied to the Dev Service database.

This has no effect if the provider is not a container-based database, such as H2 or Derby.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_INIT_SCRIPT_PATH

Show more

list of string

quarkus.datasource.devservices.volumes."host-path"

quarkus.datasource."datasource-name".devservices.volumes."host-path"

The volumes to be mapped to the container.

The map key corresponds to the host location; the map value is the container location. If the host location starts with "classpath:", the mapping loads the resource from the classpath with read-only permission.

When using a file system location, the volume will be generated with read-write permission, potentially leading to data loss or modification in your file system.

This has no effect if the provider is not a container-based database, such as H2 or Derby.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_VOLUMES__HOST_PATH_

Show more

Map<String,String>

quarkus.datasource.devservices.reuse

quarkus.datasource."datasource-name".devservices.reuse

Whether to keep Dev Service containers running after a dev mode session or test suite execution to reuse them in the next dev mode session or test suite execution.

Within a dev mode session or test suite execution, Quarkus will always reuse Dev Services as long as their configuration (username, password, environment, port bindings, …​) did not change. This feature is specifically about keeping containers running when Quarkus is not running to reuse them across runs.

This feature needs to be enabled explicitly in testcontainers.properties, may require changes to how you configure data initialization in dev mode and tests, and may leave containers running indefinitely, forcing you to stop and remove them manually. See this section of the documentation for more information.

This configuration property is set to true by default, so it is mostly useful to disable reuse, if you enabled it in testcontainers.properties but only want to use it for some of your Quarkus applications or datasources.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_REUSE

Show more

boolean

true

quarkus.datasource.devservices.show-logs

quarkus.datasource."datasource-name".devservices.show-logs

Whether the logs should be consumed by the JBoss logger.

This has no effect if the provider is not a container-based database, such as H2 or Derby.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_SHOW_LOGS

Show more

boolean

false

JDBC 設定リファレンス

ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

quarkus.datasource.dev-ui.enabled

Activate or disable the dev ui page.

Environment variable: QUARKUS_DATASOURCE_DEV_UI_ENABLED

Show more

boolean

true

quarkus.datasource.dev-ui.allow-sql

Allow sql queries in the Dev UI page

Environment variable: QUARKUS_DATASOURCE_DEV_UI_ALLOW_SQL

Show more

boolean

false

quarkus.datasource.dev-ui.append-to-default-select

Append this to the select done to fetch the table values. eg: LIMIT 100 or TOP 100

Environment variable: QUARKUS_DATASOURCE_DEV_UI_APPEND_TO_DEFAULT_SELECT

Show more

string

quarkus.datasource.dev-ui.allowed-db-host

Allowed database host. By default only localhost is allowed. Any provided host here will also be allowed

Environment variable: QUARKUS_DATASOURCE_DEV_UI_ALLOWED_DB_HOST

Show more

string

quarkus.datasource.jdbc

quarkus.datasource."datasource-name".jdbc

If we create a JDBC datasource for this datasource.

Environment variable: QUARKUS_DATASOURCE_JDBC

Show more

boolean

true

quarkus.datasource.jdbc.driver

quarkus.datasource."datasource-name".jdbc.driver

The datasource driver class name

Environment variable: QUARKUS_DATASOURCE_JDBC_DRIVER

Show more

string

quarkus.datasource.jdbc.transactions

quarkus.datasource."datasource-name".jdbc.transactions

Whether we want to use regular JDBC transactions, XA, or disable all transactional capabilities.

When enabling XA you will need a driver implementing javax.sql.XADataSource.

Environment variable: QUARKUS_DATASOURCE_JDBC_TRANSACTIONS

Show more

enabledIntegrate the JDBC Datasource with the JTA TransactionManager of Quarkus. This is the default., xaSimilarly to enabled, also enables integration with the JTA TransactionManager of Quarkus, but enabling XA transactions as well. Requires a JDBC driver implementing javax.sql.XADataSource, disabledDisables the Agroal integration with the Narayana TransactionManager. This is typically a bad idea, and is only useful in special cases\: make sure to not use this without having a deep understanding of the implications.

enabledIntegrate the JDBC Datasource with the JTA TransactionManager of Quarkus. This is the default.

quarkus.datasource.jdbc.enable-metrics

quarkus.datasource."datasource-name".jdbc.enable-metrics

Enable datasource metrics collection. If unspecified, collecting metrics will be enabled by default if a metrics extension is active.

Environment variable: QUARKUS_DATASOURCE_JDBC_ENABLE_METRICS

Show more

boolean

quarkus.datasource.jdbc.telemetry

quarkus.datasource."datasource-name".jdbc.telemetry

Enable OpenTelemetry JDBC instrumentation.

Environment variable: QUARKUS_DATASOURCE_JDBC_TELEMETRY

Show more

boolean

false

quarkus.datasource.jdbc.url

quarkus.datasource."datasource-name".jdbc.url

The datasource URL

Environment variable: QUARKUS_DATASOURCE_JDBC_URL

Show more

string

quarkus.datasource.jdbc.initial-size

quarkus.datasource."datasource-name".jdbc.initial-size

The initial size of the pool. Usually you will want to set the initial size to match at least the minimal size, but this is not enforced so to allow for architectures which prefer a lazy initialization of the connections on boot, while being able to sustain a minimal pool size after boot.

Environment variable: QUARKUS_DATASOURCE_JDBC_INITIAL_SIZE

Show more

int

quarkus.datasource.jdbc.min-size

quarkus.datasource."datasource-name".jdbc.min-size

The datasource pool minimum size

Environment variable: QUARKUS_DATASOURCE_JDBC_MIN_SIZE

Show more

int

0

quarkus.datasource.jdbc.max-size

quarkus.datasource."datasource-name".jdbc.max-size

The datasource pool maximum size

Environment variable: QUARKUS_DATASOURCE_JDBC_MAX_SIZE

Show more

int

20

quarkus.datasource.jdbc.background-validation-interval

quarkus.datasource."datasource-name".jdbc.background-validation-interval

The interval at which we validate idle connections in the background.

Set to 0 to disable background validation.

Environment variable: QUARKUS_DATASOURCE_JDBC_BACKGROUND_VALIDATION_INTERVAL

Show more

Duration 

2M

quarkus.datasource.jdbc.foreground-validation-interval

quarkus.datasource."datasource-name".jdbc.foreground-validation-interval

Perform foreground validation on connections that have been idle for longer than the specified interval.

Environment variable: QUARKUS_DATASOURCE_JDBC_FOREGROUND_VALIDATION_INTERVAL

Show more

Duration 

quarkus.datasource.jdbc.acquisition-timeout

quarkus.datasource."datasource-name".jdbc.acquisition-timeout

The timeout before cancelling the acquisition of a new connection

Environment variable: QUARKUS_DATASOURCE_JDBC_ACQUISITION_TIMEOUT

Show more

Duration 

5S

quarkus.datasource.jdbc.leak-detection-interval

quarkus.datasource."datasource-name".jdbc.leak-detection-interval

The interval at which we check for connection leaks.

Environment variable: QUARKUS_DATASOURCE_JDBC_LEAK_DETECTION_INTERVAL

Show more

Duration 

This feature is disabled by default.

quarkus.datasource.jdbc.idle-removal-interval

quarkus.datasource."datasource-name".jdbc.idle-removal-interval

The interval at which we try to remove idle connections.

Environment variable: QUARKUS_DATASOURCE_JDBC_IDLE_REMOVAL_INTERVAL

Show more

Duration 

5M

quarkus.datasource.jdbc.max-lifetime

quarkus.datasource."datasource-name".jdbc.max-lifetime

The max lifetime of a connection.

Environment variable: QUARKUS_DATASOURCE_JDBC_MAX_LIFETIME

Show more

Duration 

By default, there is no restriction on the lifespan of a connection.

quarkus.datasource.jdbc.transaction-isolation-level

quarkus.datasource."datasource-name".jdbc.transaction-isolation-level

The transaction isolation level.

Environment variable: QUARKUS_DATASOURCE_JDBC_TRANSACTION_ISOLATION_LEVEL

Show more

undefined, none, read-uncommitted, read-committed, repeatable-read, serializable

quarkus.datasource.jdbc.extended-leak-report

quarkus.datasource."datasource-name".jdbc.extended-leak-report

Collect and display extra troubleshooting info on leaked connections.

Environment variable: QUARKUS_DATASOURCE_JDBC_EXTENDED_LEAK_REPORT

Show more

boolean

false

quarkus.datasource.jdbc.flush-on-close

quarkus.datasource."datasource-name".jdbc.flush-on-close

Allows connections to be flushed upon return to the pool. It’s not enabled by default.

Environment variable: QUARKUS_DATASOURCE_JDBC_FLUSH_ON_CLOSE

Show more

boolean

false

quarkus.datasource.jdbc.detect-statement-leaks

quarkus.datasource."datasource-name".jdbc.detect-statement-leaks

When enabled, Agroal will be able to produce a warning when a connection is returned to the pool without the application having closed all open statements. This is unrelated with tracking of open connections. Disable for peak performance, but only when there’s high confidence that no leaks are happening.

Environment variable: QUARKUS_DATASOURCE_JDBC_DETECT_STATEMENT_LEAKS

Show more

boolean

true

quarkus.datasource.jdbc.new-connection-sql

quarkus.datasource."datasource-name".jdbc.new-connection-sql

Query executed when first using a connection.

Environment variable: QUARKUS_DATASOURCE_JDBC_NEW_CONNECTION_SQL

Show more

string

quarkus.datasource.jdbc.validation-query-sql

quarkus.datasource."datasource-name".jdbc.validation-query-sql

Query executed to validate a connection.

Environment variable: QUARKUS_DATASOURCE_JDBC_VALIDATION_QUERY_SQL

Show more

string

quarkus.datasource.jdbc.validate-on-borrow

quarkus.datasource."datasource-name".jdbc.validate-on-borrow

Forces connection validation prior to acquisition (foreground validation) regardless of the idle status.

Because of the overhead of performing validation on every call, it’s recommended to rely on default idle validation instead, and to leave this to false.

Environment variable: QUARKUS_DATASOURCE_JDBC_VALIDATE_ON_BORROW

Show more

boolean

false

quarkus.datasource.jdbc.pooling-enabled

quarkus.datasource."datasource-name".jdbc.pooling-enabled

Disable pooling to prevent reuse of Connections. Use this when an external pool manages the life-cycle of Connections.

Environment variable: QUARKUS_DATASOURCE_JDBC_POOLING_ENABLED

Show more

boolean

true

quarkus.datasource.jdbc.transaction-requirement

quarkus.datasource."datasource-name".jdbc.transaction-requirement

Require an active transaction when acquiring a connection. Recommended for production. WARNING: Some extensions acquire connections without holding a transaction for things like schema updates and schema validation. Setting this setting to STRICT may lead to failures in those cases.

Environment variable: QUARKUS_DATASOURCE_JDBC_TRANSACTION_REQUIREMENT

Show more

off, warn, strict

quarkus.datasource.jdbc.additional-jdbc-properties."property-key"

quarkus.datasource."datasource-name".jdbc.additional-jdbc-properties."property-key"

Other unspecified properties to be passed to the JDBC driver when creating new connections.

Environment variable: QUARKUS_DATASOURCE_JDBC_ADDITIONAL_JDBC_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>

quarkus.datasource.jdbc.telemetry.enabled

quarkus.datasource."datasource-name".jdbc.telemetry.enabled

Enable OpenTelemetry JDBC instrumentation.

Environment variable: QUARKUS_DATASOURCE_JDBC_TELEMETRY_ENABLED

Show more

boolean

false if quarkus.datasource.jdbc.telemetry=false and true if quarkus.datasource.jdbc.telemetry=true
期間フォーマットについて

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

  • 数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

JDBC URL リファレンス

サポートされているデータベースには、それぞれ異なる JDBC URL 設定オプションがあります。以下のセクションでは、各データベース URL の概要と公式ドキュメントへのリンクを示します。

DB2

jdbc:db2://<serverName>[:<portNumber>]/<databaseName>[:<key1>=<value>;[<key2>=<value2>;]]

例

jdbc:db2://localhost:50000/MYDB:user=dbadm;password=dbadm;

URL構文と追加のサポートされるオプションの詳細については、 公式ドキュメント を参照してください。

Derby

jdbc:derby:[//serverName[:portNumber]/][memory:]databaseName[;property=value[;property=value]]

例

jdbc:derby://localhost:1527/myDB, jdbc:derby:memory:myDB;create=true

Derbyは組み込みデータベースであり、サーバーとして実行することも、ファイルに基づいて実行することも、完全にメモリ内で実行することもできます。上記のオプションはすべて利用可能です。

詳しくは 公式ドキュメント をご覧ください。

H2

jdbc:h2:{ {.|mem:}[name] | [file:]fileName | {tcp|ssl}:[//]server[:port][,server2[:port]]/name }[;key=value…​]

例

jdbc:h2:tcp://localhost/~/test, jdbc:h2:mem:myDB

H2は、組み込みモードでもサーバーモードでも動作するデータベースです。 ファイルストレージを使用することも、完全にメモリ内で実行することもできます。 これらのオプションはすべて、上記のように利用可能です。

詳しくは 公式ドキュメント をご覧ください。

MariaDB

jdbc:mariadb:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…​]/[database][?<key1>=<value1>[&<key2>=<value2>]] hostDescription:: <host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]

例

jdbc:mariadb://localhost:3306/test

詳しくは 公式ドキュメント をご覧ください。

Microsoft SQL server

jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]

例

jdbc:sqlserver://localhost:1433;databaseName=AdventureWorks

Microsoft SQL Server JDBC ドライバーは、基本的に他のドライバーと同じように動作します。

詳しくは 公式ドキュメント をご覧ください。

MySQL

jdbc:mysql:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…​]/[database][?<key1>=<value1>[&<key2>=<value2>]] hostDescription:: <host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]

例

jdbc:mysql://localhost:3306/test

詳しくは 公式ドキュメント をご覧ください。

MySQL の制限

Quarkusアプリケーションをネイティブイメージにコンパイルする場合、MySQLのJMXサポートとOracle Cloud Infrastructure（OCI）統合は、GraalVMネイティブイメージと互換性がないため、無効になります。

  • JMXのサポートがないのは、ネイティブモードで実行することの当然の結果であり、解決される見込みはありません。

  • OCIとの統合はサポートされていません。

Oracle

jdbc:oracle:driver_type:@database_specifier

例

jdbc:oracle:thin:@localhost:1521/ORCL_SVC

詳しくは 公式ドキュメント をご覧ください。

PostgreSQL

jdbc:postgresql:[//][host][:port][/database][?key=value…​]

例

jdbc:postgresql://localhost/test

各パートのデフォルトは以下の通り：

host

localhost

port

5432

database

ユーザー名と同じ名前

追加パラメータの詳細については、 公式ドキュメント を参照してください。

Quarkusエクステンションとデータベースドライバーのリファレンス

以下の表は、組み込みの db-kind 値、対応する Quarkus エクステンション、およびそれらのエクステンションで使用される JDBC ドライバの一覧です。

組み込みのデータソースの種類のいずれかを使用する場合、JDBC および Reactive ドライバは、これらのテーブルの値と一致するように自動的に解決されます。

Table 1. データベースプラットフォームの種類と JDBC ドライバのマッピング
データベースの種類 Quarkusエクステンション Drivers

db2

quarkus-jdbc-db2

  • JDBC: com.ibm.db2.jcc.DB2Driver

  • XA: com.ibm.db2.jcc.DB2XADataSource

derby

quarkus-jdbc-derby

  • JDBC: org.apache.derby.jdbc.ClientDriver

  • XA: org.apache.derby.jdbc.ClientXADataSource

h2

quarkus-jdbc-h2

  • JDBC: org.h2.Driver

  • XA: org.h2.jdbcx.JdbcDataSource

mariadb

quarkus-jdbc-mariadb

  • JDBC: org.mariadb.jdbc.Driver

  • XA: org.mariadb.jdbc.MySQLDataSource

mssql

quarkus-jdbc-mssql

  • JDBC: com.microsoft.sqlserver.jdbc.SQLServerDriver

  • XA: com.microsoft.sqlserver.jdbc.SQLServerXADataSource

mysql

quarkus-jdbc-mysql

  • JDBC: com.mysql.cj.jdbc.Driver

  • XA: com.mysql.cj.jdbc.MysqlXADataSource

oracle

quarkus-jdbc-oracle

  • JDBC: oracle.jdbc.driver.OracleDriver

  • XA: oracle.jdbc.xa.client.OracleXADataSource

postgresql

quarkus-jdbc-postgresql

  • JDBC: org.postgresql.Driver

  • XA: org.postgresql.xa.PGXADataSource
Table 2. データベースの種類と Reactive ドライバーのマッピング
データベースの種類 Quarkusエクステンション ドライバー

oracle

reactive-oracle-client

io.vertx.oracleclient.spi.OracleDriver

mysql

reactive-mysql-client

io.vertx.mysqlclient.spi.MySQLDriver

mssql

reactive-mssql-client

io.vertx.mssqlclient.spi.MSSQLDriver

postgresql

reactive-pg-client

io.vertx.pgclient.spi.PgDriver

db2

reactive-db2-client

io.vertx.db2client.spi.DB2Driver

この自動解決はほとんどの場合に適用可能であり、ドライバーの設定は必要ありません。

Reactive データソース設定リファレンス

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

quarkus.datasource.reactive

quarkus.datasource."datasource-name".reactive

If we create a Reactive datasource for this datasource.

Environment variable: QUARKUS_DATASOURCE_REACTIVE

Show more

boolean

true

quarkus.datasource.reactive.cache-prepared-statements

quarkus.datasource."datasource-name".reactive.cache-prepared-statements

Whether prepared statements should be cached on the client side.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_CACHE_PREPARED_STATEMENTS

Show more

boolean

false

quarkus.datasource.reactive.url

quarkus.datasource."datasource-name".reactive.url

The datasource URLs.

If multiple values are set, this datasource will create a pool with a list of servers instead of a single server. The pool uses round-robin load balancing for server selection during connection establishment. Note that certain drivers might not accommodate multiple values in this context.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_URL

Show more

list of string

quarkus.datasource.reactive.max-size

quarkus.datasource."datasource-name".reactive.max-size

The datasource pool maximum size.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MAX_SIZE

Show more

int

20

quarkus.datasource.reactive.event-loop-size

quarkus.datasource."datasource-name".reactive.event-loop-size

When a new connection object is created, the pool assigns it an event loop.

When #event-loop-size is set to a strictly positive value, the pool assigns as many event loops as specified, in a round-robin fashion. By default, the number of event loops configured or calculated by Quarkus is used. If #event-loop-size is set to zero or a negative value, the pool assigns the current event loop to the new connection.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_EVENT_LOOP_SIZE

Show more

int

quarkus.datasource.reactive.trust-all

quarkus.datasource."datasource-name".reactive.trust-all

Whether all server certificates should be trusted.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_ALL

Show more

boolean

false

quarkus.datasource.reactive.trust-certificate-pem

quarkus.datasource."datasource-name".reactive.trust-certificate-pem

PEM Trust config is disabled by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PEM

Show more

boolean

false

quarkus.datasource.reactive.trust-certificate-pem.certs

quarkus.datasource."datasource-name".reactive.trust-certificate-pem.certs

Comma-separated list of the trust certificate files (Pem format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PEM_CERTS

Show more

list of string

quarkus.datasource.reactive.trust-certificate-jks

quarkus.datasource."datasource-name".reactive.trust-certificate-jks

JKS config is disabled by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_JKS

Show more

boolean

false

quarkus.datasource.reactive.trust-certificate-jks.path

quarkus.datasource."datasource-name".reactive.trust-certificate-jks.path

Path of the key file (JKS format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_JKS_PATH

Show more

string

quarkus.datasource.reactive.trust-certificate-jks.password

quarkus.datasource."datasource-name".reactive.trust-certificate-jks.password

Password of the key file.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_JKS_PASSWORD

Show more

string

quarkus.datasource.reactive.trust-certificate-pfx

quarkus.datasource."datasource-name".reactive.trust-certificate-pfx

PFX config is disabled by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PFX

Show more

boolean

false

quarkus.datasource.reactive.trust-certificate-pfx.path

quarkus.datasource."datasource-name".reactive.trust-certificate-pfx.path

Path to the key file (PFX format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PFX_PATH

Show more

string

quarkus.datasource.reactive.trust-certificate-pfx.password

quarkus.datasource."datasource-name".reactive.trust-certificate-pfx.password

Password of the key.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PFX_PASSWORD

Show more

string

quarkus.datasource.reactive.key-certificate-pem

quarkus.datasource."datasource-name".reactive.key-certificate-pem

PEM Key/cert config is disabled by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PEM

Show more

boolean

false

quarkus.datasource.reactive.key-certificate-pem.keys

quarkus.datasource."datasource-name".reactive.key-certificate-pem.keys

Comma-separated list of the path to the key files (Pem format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PEM_KEYS

Show more

list of string

quarkus.datasource.reactive.key-certificate-pem.certs

quarkus.datasource."datasource-name".reactive.key-certificate-pem.certs

Comma-separated list of the path to the certificate files (Pem format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PEM_CERTS

Show more

list of string

quarkus.datasource.reactive.key-certificate-jks

quarkus.datasource."datasource-name".reactive.key-certificate-jks

JKS config is disabled by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_JKS

Show more

boolean

false

quarkus.datasource.reactive.key-certificate-jks.path

quarkus.datasource."datasource-name".reactive.key-certificate-jks.path

Path of the key file (JKS format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_JKS_PATH

Show more

string

quarkus.datasource.reactive.key-certificate-jks.password

quarkus.datasource."datasource-name".reactive.key-certificate-jks.password

Password of the key file.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_JKS_PASSWORD

Show more

string

quarkus.datasource.reactive.key-certificate-pfx

quarkus.datasource."datasource-name".reactive.key-certificate-pfx

PFX config is disabled by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PFX

Show more

boolean

false

quarkus.datasource.reactive.key-certificate-pfx.path

quarkus.datasource."datasource-name".reactive.key-certificate-pfx.path

Path to the key file (PFX format).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PFX_PATH

Show more

string

quarkus.datasource.reactive.key-certificate-pfx.password

quarkus.datasource."datasource-name".reactive.key-certificate-pfx.password

Password of the key.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PFX_PASSWORD

Show more

string

quarkus.datasource.reactive.reconnect-attempts

quarkus.datasource."datasource-name".reactive.reconnect-attempts

The number of reconnection attempts when a pooled connection cannot be established on first try.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_RECONNECT_ATTEMPTS

Show more

int

0

quarkus.datasource.reactive.reconnect-interval

quarkus.datasource."datasource-name".reactive.reconnect-interval

The interval between reconnection attempts when a pooled connection cannot be established on first try.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_RECONNECT_INTERVAL

Show more

Duration 

PT1S

quarkus.datasource.reactive.hostname-verification-algorithm

quarkus.datasource."datasource-name".reactive.hostname-verification-algorithm

The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS, LDAPS or NONE. NONE is the default value and disables the verification.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_HOSTNAME_VERIFICATION_ALGORITHM

Show more

string

NONE

quarkus.datasource.reactive.idle-timeout

quarkus.datasource."datasource-name".reactive.idle-timeout

The maximum time a connection remains unused in the pool before it is closed.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_IDLE_TIMEOUT

Show more

Duration 

no timeout

quarkus.datasource.reactive.max-lifetime

quarkus.datasource."datasource-name".reactive.max-lifetime

The maximum time a connection remains in the pool, after which it will be closed upon return and replaced as necessary.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MAX_LIFETIME

Show more

Duration 

no timeout

quarkus.datasource.reactive.shared

quarkus.datasource."datasource-name".reactive.shared

Set to true to share the pool among datasources. There can be multiple shared pools distinguished by name, when no specific name is set, the __vertx.DEFAULT name is used.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_SHARED

Show more

boolean

false

quarkus.datasource.reactive.name

quarkus.datasource."datasource-name".reactive.name

Set the pool name, used when the pool is shared among datasources, otherwise ignored.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_NAME

Show more

string

quarkus.datasource.reactive.additional-properties."property-key"

quarkus.datasource."datasource-name".reactive.additional-properties."property-key"

Other unspecified properties to be passed through the Reactive SQL Client directly to the database when new connections are initiated.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_ADDITIONAL_PROPERTIES__PROPERTY_KEY_

Show more

Map<String,String>
期間フォーマットについて

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

  • 数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

Reactive DB2 設定

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

Datasources

型

デフォルト

quarkus.datasource.reactive.db2.ssl

quarkus.datasource."datasource-name".reactive.db2.ssl

Whether SSL/TLS is enabled.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_DB2_SSL

Show more

boolean

false

Reactive MariaDB/MySQL固有の設定

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

Additional named datasources

型

デフォルト

quarkus.datasource.reactive.mysql.charset

quarkus.datasource."datasource-name".reactive.mysql.charset

Charset for connections.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_CHARSET

Show more

string

quarkus.datasource.reactive.mysql.collation

quarkus.datasource."datasource-name".reactive.mysql.collation

Collation for connections.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_COLLATION

Show more

string

quarkus.datasource.reactive.mysql.ssl-mode

quarkus.datasource."datasource-name".reactive.mysql.ssl-mode

Desired security state of the connection to the server.

See MySQL Reference Manual.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_SSL_MODE

Show more

disabled, preferred, required, verify-ca, verify-identity

disabled

quarkus.datasource.reactive.mysql.connection-timeout

quarkus.datasource."datasource-name".reactive.mysql.connection-timeout

Connection timeout in seconds

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_CONNECTION_TIMEOUT

Show more

int

quarkus.datasource.reactive.mysql.authentication-plugin

quarkus.datasource."datasource-name".reactive.mysql.authentication-plugin

The authentication plugin the client should use. By default, it uses the plugin name specified by the server in the initial handshake packet.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_AUTHENTICATION_PLUGIN

Show more

default, mysql-clear-password, mysql-native-password, sha256-password, caching-sha2-password

default

quarkus.datasource.reactive.mysql.pipelining-limit

quarkus.datasource."datasource-name".reactive.mysql.pipelining-limit

The maximum number of inflight database commands that can be pipelined. By default, pipelining is disabled.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_PIPELINING_LIMIT

Show more

int

quarkus.datasource.reactive.mysql.use-affected-rows

quarkus.datasource."datasource-name".reactive.mysql.use-affected-rows

Whether to return the number of rows matched by the WHERE clause in UPDATE statements, instead of the number of rows actually changed.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_USE_AFFECTED_ROWS

Show more

ブーリアン

false

Reactive Microsoft SQLサーバー固有の設定

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

Datasources

型

デフォルト

quarkus.datasource.reactive.mssql.packet-size

quarkus.datasource."datasource-name".reactive.mssql.packet-size

The desired size (in bytes) for TDS packets.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MSSQL_PACKET_SIZE

Show more

int

quarkus.datasource.reactive.mssql.ssl

quarkus.datasource."datasource-name".reactive.mssql.ssl

Whether SSL/TLS is enabled.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MSSQL_SSL

Show more

boolean

false

Reactive Oracle固有の設定

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

No configuration properties found.

Reactive PostgreSQL固有の設定

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property

型

デフォルト

Datasources

型

デフォルト

quarkus.datasource.reactive.postgresql.pipelining-limit

quarkus.datasource."datasource-name".reactive.postgresql.pipelining-limit

The maximum number of inflight database commands that can be pipelined.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_PIPELINING_LIMIT

Show more

int

quarkus.datasource.reactive.postgresql.ssl-mode

quarkus.datasource."datasource-name".reactive.postgresql.ssl-mode

SSL operating mode of the client.

See Protection Provided in Different Modes.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_SSL_MODE

Show more

disable, allow, prefer, require, verify-ca, verify-full

disable

quarkus.datasource.reactive.postgresql.use-layer7-proxy

quarkus.datasource."datasource-name".reactive.postgresql.use-layer7-proxy

Level 7 proxies can load balance queries on several connections to the actual database. When it happens, the client can be confused by the lack of session affinity and unwanted errors can happen like ERROR: unnamed prepared statement does not exist (26000). See Using a level 7 proxy

Environment variable: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_USE_LAYER7_PROXY

Show more

boolean

false

Reactive データソースの URL 参照

DB2

db2://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

例

db2://dbuser:secretpassword@database.server.com:50000/mydb

現在、クライアントは以下のパラメータキーをサポートしています:

  • host

  • port

  • user

  • password

  • database

接続 URL でパラメータを設定すると、デフォルトのプロパティが上書きされます。

Microsoft SQL server

sqlserver://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

例

sqlserver://dbuser:secretpassword@database.server.com:1433/mydb

現在、クライアントは以下のパラメータキーをサポートしています:

  • host

  • port

  • user

  • password

  • database

接続 URL でパラメータを設定すると、デフォルトのプロパティが上書きされます。

MySQL / MariaDB

mysql://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

例

mysql://dbuser:secretpassword@database.server.com:3211/mydb

現在、クライアントは以下のパラメータキーをサポートしています（大文字と小文字を区別します）:

  • host

  • port

  • user

  • password

  • schema

  • socket

  • useAffectedRows

接続 URL でパラメータを設定すると、デフォルトのプロパティが上書きされます。

Oracle

EZConnect 形式

oracle:thin:@[[protocol:]//]host[:port][/service_name][:server_mode][/instance_name][?connection properties]

例

oracle:thin:@mydbhost1:5521/mydbservice?connect_timeout=10sec

TNSエイリアス形式

oracle:thin:@<alias_name>[?connection properties]

例

oracle:thin:@prod_db?TNS_ADMIN=/work/tns/

PostgreSQL

postgresql://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

例

postgresql://dbuser:secretpassword@database.server.com:5432/mydb

現在、クライアントは以下をサポートしています:

  • 以下のパラメータキー:

    • host

    • port

    • user

    • password

    • dbname

    • sslmode

  • 次のような追加のプロパティ:

    • application_name

    • fallback_application_name

    • search_path

    • options

接続 URL でパラメータを設定すると、デフォルトのプロパティが上書きされます。

関連コンテンツ

On the same extensions

On the same topics

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by