Reactive SQL clients

Reactive SQL クライアントは、スケーラビリティと低オーバーヘッドに焦点を当てたシンプルな API を持っています。現在、以下のデータベースサーバーがサポートされています。

  • IBM Db2

  • PostgreSQL

  • MariaDB/MySQL

  • Microsoft SQL Server

  • Oracle

このガイドでは、PostgreSQL に格納されたデータをRESTful APIで公開するシンプルなCRUDアプリケーションの実装方法を学びます。

Extension and connection pool class names for each client can be found at the bottom of this document.
If you are not familiar with the Quarkus Vert.x extension, consider reading the Using Eclipse Vert.x guide first.

アプリケーションは、フルーツのエンティティを管理するものとします。

src/main/java/org/acme/reactive/crud/Fruit.java
package org.acme.reactive.crud;

import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.Uni;
import io.vertx.mutiny.sqlclient.Pool;
import io.vertx.mutiny.sqlclient.Row;
import io.vertx.mutiny.sqlclient.RowSet;
import io.vertx.mutiny.sqlclient.Tuple;

public class Fruit {

    public Long id;

    public String name;

    public Fruit() {
        // default constructor.
    }

    public Fruit(String name) {
        this.name = name;
    }

    public Fruit(Long id, String name) {
        this.id = id;
        this.name = name;
    }
}

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.9.16

  • 動作するコンテナランタイム(Docker, Podman)

  • 使用したい場合は、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

アプリケーションを開発モードで起動すると、Quarkus はすぐに使用できる zero-config database を提供します。

事前にデータベースを起動することもできます。

docker run -it --rm=true --name quarkus_test -e POSTGRES_USER=quarkus_test -e POSTGRES_PASSWORD=quarkus_test -e POSTGRES_DB=quarkus_test -p 5432:5432 docker.io/library/postgres:18

ソリューション

次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

git clone -b development https://github.com/quarkusio/quarkus-quickstarts.git で Git リポジトリーをクローンします。または、https://github.com/quarkusio/quarkus-quickstarts/archive/development.zip[アーカイブ] をダウンロードします。

解決策は、 getting-started-reactive-crud ディレクトリー を参照してください。

インストール

リアクティブな PostgreSQL クライアントエクステンション

まず、プロジェクトで quarkus-reactive-pg-client のエクステンションが有効になっていることを確認します。新しいプロジェクトを作成する場合は、次のコマンドを使用します。

コマンドラインインタフェース
quarkus create app org.acme:reactive-pg-client-quickstart \
    --extension='rest,reactive-pg-client' \
    --no-code
cd reactive-pg-client-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven
mvn io.quarkus:quarkus-maven-plugin:999-SNAPSHOT:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=reactive-pg-client-quickstart \
    -Dextensions='rest,reactive-pg-client' \
    -DnoCode
cd reactive-pg-client-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=reactive-pg-client-quickstart"

すでに作成済みのプロジェクトがある場合は、 add-extension コマンドで既存のQuarkusプロジェクトに reactive-pg-client エクステンションを追加することが出来ます。

CLI
quarkus extension add reactive-pg-client
Maven
./mvnw quarkus:add-extension -Dextensions='reactive-pg-client'
Gradle
./gradlew addExtension --extensions='reactive-pg-client'

それ以外の場合は、ビルドファイルに依存関係を手動で追加できます。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-reactive-pg-client</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-reactive-pg-client")

Mutiny

Quarkus REST (旧称 RESTEasy Reactive) には、Mutiny タイプ (例: Uni および Multi) のサポートが標準で含まれています。

このガイドでは、Reactive PostgreSQL Client の Mutiny API を使用します。Mutiny についてよく知らない方は、Mutiny - an intuitive reactive programming library を参照してください。

JSON バインディング

Fruit インスタンスを HTTP 経由で JSON 形式で公開します。 したがって、 quarkus-rest-jackson エクステンションも追加する必要があります。

CLI
quarkus extension add rest-jackson
Maven
./mvnw quarkus:add-extension -Dextensions='rest-jackson'
Gradle
./gradlew addExtension --extensions='rest-jackson'

コマンドラインを使用したくない場合は、ビルドファイルに依存関係を手動で追加します。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-rest-jackson")

もちろん、これはこのガイドの要件に過ぎず、Reactive PostgreSQLクライアントを使用したアプリケーションではありません。

設定

Reactive PostgreSQLクライアントは、Quarkusの標準的なデータソースプロパティーとReactive URLを使用して設定することができます。

src/main/resources/application.properties
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=quarkus_test
quarkus.datasource.password=quarkus_test
quarkus.datasource.reactive.url=postgresql://localhost:5432/quarkus_test

これで、 FruitResource スケルトンを作成し、 io.vertx.mutiny.sqlclient.Pool インスタンスを注入することができます:

src/main/java/org/acme/vertx/FruitResource.java
package org.acme.reactive.crud;

import java.net.URI;

import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.Response.ResponseBuilder;
import jakarta.ws.rs.core.Response.Status;

import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.Uni;
import io.vertx.mutiny.sqlclient.Pool;

@Path("fruits")
public class FruitResource {

    private final Pool client;

    public FruitResource(Pool client) {
        this.client = client;
    }
}

データベーススキーマとシードデータ

REST エンドポイントとデータ管理コードを実装する前に、データベーススキーマを設定する必要があります。 事前に何らかのデータを挿入しておくと便利です。

本番環境では Flyway データベースマイグレーションツール のようなものを使用することをお勧めします。しかし、開発時には単純に起動時にテーブルをドロップして作成し、いくつかの fruits を挿入することができます。

/src/main/java/org/acme/reactive/crud/DBInit.java
package org.acme.reactive.crud;

import io.quarkus.runtime.StartupEvent;
import io.vertx.mutiny.sqlclient.Pool;
import org.eclipse.microprofile.config.inject.ConfigProperty;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;

@ApplicationScoped
public class DBInit {

    private final Pool client;
    private final boolean schemaCreate;

    public DBInit(Pool client, @ConfigProperty(name = "myapp.schema.create", defaultValue = "true") boolean schemaCreate) {
        this.client = client;
        this.schemaCreate = schemaCreate;
    }

    void onStart(@Observes StartupEvent ev) {
        if (schemaCreate) {
            initdb();
        }
    }

    private void initdb() {
        // TODO
    }
}
You might override the default value of the myapp.schema.create property in the application.properties file.

ほとんど準備ができています! 開発モードで DB を初期化するには、クライアントの単純な query メソッドを使用します。 Uni を返すため、クエリーを順番に実行するように設定できます。

client.query("DROP TABLE IF EXISTS fruits").execute()
    .flatMap(r -> client.query("CREATE TABLE fruits (id SERIAL PRIMARY KEY, name TEXT NOT NULL)").execute())
    .flatMap(r -> client.query("INSERT INTO fruits (name) VALUES ('Kiwi')").execute())
    .flatMap(r -> client.query("INSERT INTO fruits (name) VALUES ('Durian')").execute())
    .flatMap(r -> client.query("INSERT INTO fruits (name) VALUES ('Pomelo')").execute())
    .flatMap(r -> client.query("INSERT INTO fruits (name) VALUES ('Lychee')").execute())
    .await().indefinitely();

最新のクエリーが完了するまでブロックする必要があるのはなぜでしょうか? このコードは、 StartupEvent を @Observes し、Quarkus がそれを同期的に呼び出すメソッドの一部です。 その結果、時期尚早に戻ると、データベースがまだ準備できていない状態でリクエストが処理される可能性があります。

以上です。これまで、プールされたクライアントを設定し、単純なクエリーを実行する方法を見てきました。これで、データ管理コードを開発し、RESTful エンドポイントを実装する準備が整いました。

使用

クエリー結果のトラバーサル

開発モードでは、データベースは fruits テーブルのいくつかの行で設定されます。すべてのデータを取得するには、 query メソッドを再度使用します。

/src/main/java/org/acme/reactive/crud/Fruit.java
    public static Multi<Fruit> findAll(Pool client) {
        return client.query("SELECT id, name FROM fruits ORDER BY name ASC").execute()
                .onItem().transformToMulti(set -> Multi.createFrom().iterable(set)) (1)
                .onItem().transform(Fruit::from); (2)
    }

    private static Fruit from(Row row) {
        return new Fruit(row.getLong("id"), row.getString("name"));
    }
1 io.vertx.mutiny.sqlclient.RowSet を Multi<Row> に変換します。。
2 各 io.vertx.mutiny.sqlclient.Row を Fruit に変換します。

Fruit#from メソッドは Row インスタンスを Fruit インスタンスに変換します。これは、他のデータ管理方法の実装の便宜上、展開されています。

次に、バックエンドからすべての fruits を取得するためのエンドポイントを追加します。

src/main/java/org/acme/vertx/FruitResource.java
@GET
public Multi<Fruit> get() {
    return Fruit.findAll(client);
}

ここで、開発モードで Quarkus を起動します。

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

最後に、ブラウザーを開いて http://localhost:8080/fruits に移動します。次のように表示されます。

[{"id":2,"name":"Durian"},{"id":1,"name":"Kiwi"},{"id":4,"name":"Lychee"},{"id":3,"name":"Pomelo"}]

プリペアドクエリー

Reactive PostgreSQL Client は、クエリーを準備し、実行時に SQL ステートメントにおいて置き換えられるパラメーターを持つこともできます。

client.preparedQuery("SELECT id, name FROM fruits WHERE id = $1").execute(Tuple.of(id))
For PostgreSQL, the SQL string can refer to parameters by position, using $1, $2, …​etc. Please refer to the データベースクライアントの詳細 section for other databases.

単純な query メソッドと同様に、 preparedQuery は PreparedQuery<RowSet<Row>> のインスタンスを返します。このツールを装備すると、ユーザーから提供された id を安全に使用して、特定の fruit の詳細を取得できます。

src/main/java/org/acme/vertx/Fruit.java
public static Uni<Fruit> findById(Pool client, Long id) {
    return client.preparedQuery("SELECT id, name FROM fruits WHERE id = $1").execute(Tuple.of(id)) (1)
            .onItem().transform(RowSet::iterator) (2)
            .onItem().transform(iterator -> iterator.hasNext() ? from(iterator.next()) : null); (3)
}
1 プリペアドクエリーパラメーターを保持するための Tuple を作成します。
2 RowSet の結果に対して Iterator を取得します。
3 エンティティーが見つかった場合は、 Row から Fruit インスタンスを作成します。

そして、Jakarta RESTのリソースは以下のようにします:

src/main/java/org/acme/vertx/FruitResource.java
@GET
@Path("{id}")
public Uni<Response> getSingle(Long id) {
    return Fruit.findById(client, id)
            .onItem().transform(fruit -> fruit != null ? Response.ok(fruit) : Response.status(Status.NOT_FOUND)) (1)
            .onItem().transform(ResponseBuilder::build); (2)
}
1 見つかった場合、 Fruit インスタンス、あるいは 404 ステータスコードでJakarta REST 応答を準備します。
2 レスポンスを構築して送信します。

Fruit を保存するときに同じロジックが適用されます。

src/main/java/org/acme/vertx/Fruit.java
public Uni<Long> save(Pool client) {
    return client.preparedQuery("INSERT INTO fruits (name) VALUES ($1) RETURNING id").execute(Tuple.of(name))
            .onItem().transform(pgRowSet -> pgRowSet.iterator().next().getLong("id"));
}

また、Web リソースでは、 POST リクエストを処理します。

src/main/java/org/acme/vertx/FruitResource.java
@POST
public Uni<Response> create(Fruit fruit) {
    return fruit.save(client)
            .onItem().transform(id -> URI.create("/fruits/" + id))
            .onItem().transform(uri -> Response.created(uri).build());
}

結果のメタデータ

RowSet はデータをメモリーに保持するだけでなく、次のようなデータ自体に関する情報も提供します。

  • クエリーの影響を受ける行数 (クエリータイプに応じて挿入/削除/更新/取得)、

  • 列名。

これを使用して、データベース内の fruits の削除をサポートしましょう。

src/main/java/org/acme/vertx/Fruit.java
public static Uni<Boolean> delete(Pool client, Long id) {
    return client.preparedQuery("DELETE FROM fruits WHERE id = $1").execute(Tuple.of(id))
            .onItem().transform(pgRowSet -> pgRowSet.rowCount() == 1); (1)
}
1 メタデータを調べて、fruit が実際に削除されたかどうかを判断します。

また、Web リソースで HTTP の DELETE メソッドを処理するには:

src/main/java/org/acme/vertx/FruitResource.java
@DELETE
@Path("{id}")
public Uni<Response> delete(Long id) {
    return Fruit.delete(client, id)
            .onItem().transform(deleted -> deleted ? Status.NO_CONTENT : Status.NOT_FOUND)
            .onItem().transform(status -> Response.status(status).build());
}

GET、 POST、および DELETE メソッドが実装されたので、RESTful アプリケーションを試すための最小限の Web ページを作成できます。 jQuery を使用して、バックエンドとのやり取りを簡素化します。

/src/main/resources/META-INF/resources/fruits.html
<!doctype html>
<html>
<head>
    <meta charset="utf-8"/>
    <title>Reactive REST - Quarkus</title>
    <script src="https://code.jquery.com/jquery-3.3.1.min.js"
            integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=" crossorigin="anonymous"></script>
    <script type="application/javascript" src="fruits.js"></script>
</head>
<body>

<h1>Fruits API Testing</h1>

<h2>All fruits</h2>
<div id="all-fruits"></div>

<h2>Create Fruit</h2>
<input id="fruit-name" type="text">
<button id="create-fruit-button" type="button">Create</button>
<div id="create-fruit"></div>

</body>
</html>
Quarkus automatically serves static resources located under the META-INF/resources directory.

JavaScript コードでは、次の場合に fruits のリストを更新する関数が必要です。

  • ページが読み込まれる、または

  • fruit が追加される、または

  • fruit は削除される。

/src/main/resources/META-INF/resources/fruits.js
function refresh() {
    $.get('/fruits', function (fruits) {
        var list = '';
        (fruits || []).forEach(function (fruit) { (1)
            list = list
                + '<tr>'
                + '<td>' + fruit.id + '</td>'
                + '<td>' + fruit.name + '</td>'
                + '<td><a href="#" onclick="deleteFruit(' + fruit.id + ')">Delete</a></td>'
                + '</tr>'
        });
        if (list.length > 0) {
            list = ''
                + '<table><thead><th>Id</th><th>Name</th><th></th></thead>'
                + list
                + '</table>';
        } else {
            list = "No fruits in database"
        }
        $('#all-fruits').html(list);
    });
}

function deleteFruit(id) {
    $.ajax('/fruits/' + id, {method: 'DELETE'}).then(refresh);
}

$(document).ready(function () {

    $('#create-fruit-button').click(function () {
        var fruitName = $('#fruit-name').val();
        $.post({
            url: '/fruits',
            contentType: 'application/json',
            data: JSON.stringify({name: fruitName})
        }).then(refresh);
    });

    refresh();
});
1 データベースが空の場合、 fruits パラメーターは定義されません。

すべて完了! http://localhost:8080/fruits.html に移動し、いくつかの fruits を読み取り/作成/削除します。

データベースクライアントの詳細

Database 拡張子名 プレースホルダー

IBM Db2

quarkus-reactive-db2-client

?

MariaDB/MySQL

quarkus-reactive-mysql-client

?

Microsoft SQL Server

quarkus-reactive-mssql-client

@p1, @p2, etc.

Oracle

quarkus-reactive-oracle-client

?

PostgreSQL

quarkus-reactive-pg-client

$1, $2 など

トランザクション

リアクティブ SQL クライアントはトランザクションをサポートします。トランザクションは io.vertx.mutiny.sqlclient.SqlConnection#begin で開始され、 io.vertx.mutiny.sqlclient.Transaction#commit または io.vertx.mutiny.sqlclient.Transaction#rollback で終了します。これらの操作はすべて非同期です。

  • connection.begin()`は `Uni<Transaction> を返します。

  • transaction.commit() および transaction.rollback() は Uni<Void> を返します。

リアクティブプログラミングの世界でトランザクションを管理するのは面倒な場合があります。反復的で複雑な (したがってエラーが発生しやすい) コードを記述する代わりに、 io.vertx.mutiny.sqlclient.Pool#withTransaction ヘルパーメソッドを使用できます。

次のスニペットは、同じトランザクションで 2 つの挿入を実行する方法を示しています。

public static Uni<Void> insertTwoFruits(Pool client, Fruit fruit1, Fruit fruit2) {
    return client.withTransaction(conn -> {
        Uni<RowSet<Row>> insertOne = conn.preparedQuery("INSERT INTO fruits (name) VALUES ($1) RETURNING id")
                .execute(Tuple.of(fruit1.name));
        Uni<RowSet<Row>> insertTwo = conn.preparedQuery("INSERT INTO fruits (name) VALUES ($1) RETURNING id")
                .execute(Tuple.of(fruit2.name));

        return Uni.combine().all().unis(insertOne, insertTwo)
                // Ignore the results (the two ids)
                .discardItems();
    });
}

この例では、トランザクションは成功時に自動的にコミットされるか、失敗時にロールバックされます。

次のように依存アクションを作成することもできます。

return client.withTransaction(conn -> conn

        .preparedQuery("INSERT INTO person (firstname,lastname) VALUES ($1,$2) RETURNING id")
        .execute(Tuple.of(person.getFirstName(), person.getLastName()))

        .onItem().transformToUni(id -> conn.preparedQuery("INSERT INTO addr (person_id,addrline1) VALUES ($1,$2)")
                .execute(Tuple.of(id.iterator().next().getLong("id"), person.getLastName())))

        .onItem().ignore().andContinueWithNull());

バッチクエリー結果の操作

バッチクエリーを実行すると、リアクティブ SQL クライアントはバッチの最初の要素の結果に対応する RowSet を返します。次のバッチ要素の結果を取得するには、 null が返されるまで RowSet#next メソッドを呼び出す必要があります。

いくつかの行を更新し、影響を受ける行の総数を計算するとします。各 RowSet を検査する必要があります。

PreparedQuery<RowSet<Row>> preparedQuery = client.preparedQuery("UPDATE fruits SET name = $1 WHERE id = $2");

Uni<RowSet<Row>> rowSet = preparedQuery.executeBatch(Arrays.asList(
        Tuple.of("Orange", 1),
        Tuple.of("Pear", 2),
        Tuple.of("Apple", 3)));

Uni<Integer> totalAffected = rowSet.onItem().transform(res -> {
    int total = 0;
    do {
        total += res.rowCount(); (1)
    } while ((res = res.next()) != null); (2)
    return total;
});
1 RowSet#rowCount の合計を計算します。
2 null を返すまで RowSet#next を呼び出します。

別の例として、挿入したばかりのすべての行をロードする場合は、各 RowSet の内容を連結する必要があります。

PreparedQuery<RowSet<Row>> preparedQuery = client.preparedQuery("INSERT INTO fruits (name) VALUES ($1) RETURNING *");

Uni<RowSet<Row>> rowSet = preparedQuery.executeBatch(Arrays.asList(
        Tuple.of("Orange"),
        Tuple.of("Pear"),
        Tuple.of("Apple")));

// Generate a Multi of RowSet items
Multi<RowSet<Row>> rowSets = rowSet.onItem().transformToMulti(res -> {
    return Multi.createFrom().generator(() -> res, (rs, emitter) -> {
        RowSet<Row> next = null;
        if (rs != null) {
            emitter.emit(rs);
            next = rs.next();
        }
        if (next == null) {
            emitter.complete();
        }
        return next;
    });
});

// Transform each RowSet into Multi of Row items and Concatenate
Multi<Row> rows = rowSets.onItem().transformToMultiAndConcatenate(Multi.createFrom()::iterable);

複数のデータソース

Reactive SQL クライアントは、複数のデータソースの定義をサポートしています。

複数のデータソースを使用した典型的な構成は以下のようになります。

quarkus.datasource.db-kind=postgresql (1)
quarkus.datasource.username=user-default
quarkus.datasource.password=password-default
quarkus.datasource.reactive.url=postgresql://localhost:5432/default

quarkus.datasource."additional1".db-kind=postgresql (2)
quarkus.datasource."additional1".username=user-additional1
quarkus.datasource."additional1".password=password-additional1
quarkus.datasource."additional1".reactive.url=postgresql://localhost:5432/additional1

quarkus.datasource."additional2".db-kind=mysql (3)
quarkus.datasource."additional2".username=user-additional2
quarkus.datasource."additional2".password=password-additional2
quarkus.datasource."additional2".reactive.url=mysql://localhost:3306/additional2
1 デフォルトのデータソース - PostgreSQL を使用。
2 additional1 と呼ばれる名前付きデータソース - PostgreSQL を使用。
3 additional2 と呼ばれる名前付きデータソース - MySQL を使用。

次に、次のようにクライアントを挿入できます。

@Inject (1)
Pool defaultClient;

@Inject
@ReactiveDataSource("additional1") (2)
Pool additional1Client;

@Inject
@ReactiveDataSource("additional2")
Pool additional2Client;
1 デフォルトのデータソースにクライアントを挿入するために特別なことは何も必要ありません。
2 名前付きデータソースの場合、値としてデータソース名を指定して @ReactiveDataSource CDI 修飾子を使用します。

Unix Domain Socket connections

The PostgreSQL and MariaDB/MySQL clients can be configured to connect to the server through a Unix Domain Socket.

Unix Domain Sockets are supported in both JVM and native modes.

Configure the database connection url as described below. This step depends on the database type.

PostgreSQL

PostgreSQL ドメインソケットパスの形式は、 <directory>/.s.PGSQL.<port> のようになります。

データベース接続の URL は、次のように設定する必要があります。

  • host はソケットパスの directory です

  • port はソケットパスの port です

次のソケットパスを検討してください: /var/run/postgresql/.s.PGSQL.5432。

application.properties で以下を追加します。

quarkus.datasource.reactive.url=postgresql://:5432/quarkus_test?host=/var/run/postgresql

MariaDB/MySQL

データベース接続 URL は、 host がソケットパスになるように設定する必要があります。

次のソケットパスを検討してください: /var/run/mysqld/mysqld.sock。

application.properties で以下を追加します。

quarkus.datasource.reactive.url=mysql:///quarkus_test?host=/var/run/mysqld/mysqld.sock

ロードバランシングコネクション

リアクティブPostgreSQLおよびMariaDB/MySQLクライアントは、複数の接続を定義することをサポートしています。

複数の接続がある典型的な構成は、次のようになります:

quarkus.datasource.reactive.url=postgresql://host1:5432/default,postgresql://host2:5432/default,postgresql://host3:5432/default

これは、インデックス付プロパティ構文で書くこともできます:

quarkus.datasource.reactive.url[0]=postgresql://host1:5432/default
quarkus.datasource.reactive.url[1]=postgresql://host2:5432/default
quarkus.datasource.reactive.url[2]=postgresql://host3:5432/default

Pooled connection idle-timeout

リアクティブデータソースは、 idle-timeout で設定できます。これは、接続が閉じられる前に、接続がプール内で未使用のままである最大時間です。

The idle-timeout is disabled by default.

たとえば、アイドル状態の接続を 60 分後に期限切れにすることができます。

quarkus.datasource.reactive.idle-timeout=PT60M

Pooled Connection max-lifetime

idle-timeout に加えて、リアクティブデータソースは max-lifetime を使用して設定することもできます。 これは、接続が切断され、必要に応じて置き換えられるまでに、接続がプール内に留まる最大時間です。 max-lifetime を使用すると、プールに最新の設定の新しい接続が確保されます。

The max-lifetime is disabled by default but is an important configuration when using a credentials provider that provides time limited credentials, like the Vault credentials provider.

たとえば、60 分後に接続が再利用されるように指定できます。

quarkus.datasource.reactive.max-lifetime=PT60M

Pool connection-timeout

The connection-timeout controls how long a request waits for a connection from the pool before failing.

The default connection timeout is 30 seconds (30S).

For example, you could set a 5-second timeout:

quarkus.datasource.reactive.connection-timeout=5S

Pool max-wait-queue-size

You can limit how many requests wait in the queue when all pool connections are in use. Further requests are rejected immediately when the queue is full.

By default, the wait queue is unbounded.
quarkus.datasource.reactive.max-wait-queue-size=100

Pool pool-cleaner-period

The pool-cleaner-period controls how often the pool checks for idle connections eligible for removal. This works in conjunction with idle-timeout.

The default pool cleaner period is 1 second.
quarkus.datasource.reactive.pool-cleaner-period=5S

TLSの設定

All reactive SQL clients support TLS configuration through the Quarkus TLS registry. You can reference a named TLS configuration using the tls-configuration-name property:

quarkus.tls.my-db-tls.trust-store.pem.certs=server.crt
quarkus.datasource.reactive.tls-configuration-name=my-db-tls

When a named TLS configuration is set, SSL is automatically enabled for the connection. For databases that support SSL modes (PostgreSQL and MariaDB/MySQL), the SSL mode is set to require/required. For IBM Db2 and Microsoft SQL Server, the ssl flag is set to true.

When a named TLS configuration is set, manual SSL properties (trust-certificate-, key-certificate-, trust-all, hostname-verification-algorithm) are ignored.

For more information about the TLS registry, see the TLS Registry Reference guide.

Direct SSL negotiation (PostgreSQL 17+)

PostgreSQL 17 introduced direct SSL: the TLS handshake starts immediately on connect, with no prior SSL request/response round-trip. This reduces connection latency and enables standard TLS proxies (nginx, haproxy) to terminate the connection.

Configure it with the ssl-negotiation property:

quarkus.datasource.reactive.postgresql.ssl-negotiation=direct
quarkus.datasource.reactive.postgresql.ssl-mode=require

The ssl-negotiation property accepts two values:

  • postgres (default) — traditional negotiation, compatible with all PostgreSQL versions.

  • direct — direct SSL, requires PostgreSQL 17 or later.

TDS 8.0 (Microsoft SQL Server 2022+)

Microsoft SQL Server 2022 and later support TDS 8.0, which performs the TLS handshake before any TDS protocol exchange. The reactive MSSQL client exposes this via the encryption-mode configuration property:

quarkus.datasource.reactive.mssql.encryption-mode=strict

strict enables TDS 8.0. The other values are on (optional encryption, equivalent to ssl=true) and off (no encryption, the default).

プール作成のカスタマイズ

データベース接続プールは、宣言だけでは設定できないことがあります。

たとえば、実稼働環境にのみ存在する特定のファイルを読み取ったり、独自の設定サーバーから設定データを取得したりする必要がある場合があります。

In this case, you can customize pool creation by creating a class implementing io.quarkus.reactive.datasource.PoolCreator:

import jakarta.inject.Singleton;

import io.quarkus.reactive.datasource.PoolCreator;
import io.vertx.sqlclient.Pool;
import io.vertx.sqlclient.PoolOptions;
import io.vertx.sqlclient.SqlConnectOptions;

@Singleton
public class CustomPoolCreator implements PoolCreator {

    @Override
    public Pool create(Input input) {
        SqlConnectOptions connectOptions = input.connectOptionsList().get(0);
        PoolOptions poolOptions = input.poolOptions();
        // Customize connectOptions, poolOptions or both, as required
        return Pool.pool(input.vertx(), connectOptions, poolOptions);
    }
}

For a named datasource, annotate the bean with @ReactiveDataSource("datasource-name").

PoolCreator is also the way to set Vert.x options that cannot be expressed as configuration properties, such as SqlConnectOptions.setPreparedStatementCacheSqlFilter(Predicate<String>).

パイプライン

PostgreSQL および MariaDB/MySQL クライアントは、接続レベルでのクエリーのパイプライン化をサポートしています。 この機能には、対応する応答を待たずに、同じデータベース接続で複数のクエリーを送信する機能などが含まれます。

ユースケースによっては、クエリーパイプラインによってデータベースアクセスのパフォーマンスが向上する場合があります。

ここでは、PostgreSQLの例を紹介します:

import jakarta.inject.Inject;

import io.smallrye.mutiny.Uni;
import io.vertx.mutiny.sqlclient.Pool;

public class PipeliningExample {

    @Inject
    Pool client;

    public Uni<String> favoriteFruitAndVegetable() {
        // Explicitly acquire a connection
        return client.withConnection(conn -> {
            Uni<String> favoriteFruit = conn.query("SELECT name FROM fruits WHERE preferred IS TRUE").execute()
                    .onItem().transform(rows -> rows.iterator().next().getString("name"));
            Uni<String> favoriteVegetable = conn.query("SELECT name FROM vegetables WHERE preferred IS TRUE").execute()
                    .onItem().transform(rows -> rows.iterator().next().getString("name"));
            // favoriteFruit and favoriteVegetable unis will be subscribed at the same time
            return Uni.combine().all().unis(favoriteFruit, favoriteVegetable)
                    .combinedWith(PipeliningExample::formatMessage);
        });
    }

    private static String formatMessage(String fruit, String vegetable) {
        return String.format("The favorite fruit is %s and the favorite vegetable is %s", fruit, vegetable);
    }
}

パイプラインクエリーの最大数は、 pipelining-limit プロパティーで設定されます。

# For PostgreSQL
quarkus.datasource.reactive.postgresql.pipelining-limit=256
# For MariaDB/MySQL
quarkus.datasource.reactive.mysql.pipelining-limit=256

デフォルトでは、 pipelining-limit は 256 に設定されています。

設定リファレンス

共通のデータソース

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

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

Whether 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 quarkus.datasource."datasource name".jdbc.metrics.enabled 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

Controls whether default database versions are applied when not explicitly configured.

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

When set to recent (the default), Quarkus will use recent stable versions as defaults for each database kind. This optimizes for performance and features but requires your database to be reasonably up-to-date.

When set to compatible, no default versions are applied. You must explicitly set quarkus.datasource.db-version (or quarkus.datasource."datasource-name".db-version) for each datasource.

Environment variable: QUARKUS_DATASOURCE_DB_VERSION_DEFAULTS

Show more

recent, compatible

recent

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."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, and Oracle Database 26ai would be version 23.26.

原則として、ここで設定するバージョンはできるだけ高くする必要がありますが、 アプリケーションが接続するデータベースのバージョン以下である必要があります。

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.

If not set, the default depends on the db-kind: * DB2: 12.1 * MariaDB: 11.4 * Microsoft SQL Server: 16 * MySQL: 8.4 * Oracle: 23 * PostgreSQL: 16

If you are connecting to an older database version, you must explicitly set this property to match your actual database version to avoid runtime errors.

Environment variable: QUARKUS_DATASOURCE_DB_VERSION

Show more

string

Depends on `db-kind`, see description.

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."datasource-name".active

Whether this datasource should be active at runtime.

Environment variable: QUARKUS_DATASOURCE_ACTIVE

Show more

boolean

`true` if the URL is set, `false` otherwise

quarkus.datasource."datasource-name".username

The datasource username

Environment variable: QUARKUS_DATASOURCE_USERNAME

Show more

string

quarkus.datasource."datasource-name".password

The datasource password

Environment variable: QUARKUS_DATASOURCE_PASSWORD

Show more

string

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

The credentials provider name

Environment variable: QUARKUS_DATASOURCE_CREDENTIALS_PROVIDER

Show more

string

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

Defaults depend on the configured datasource:

  • DB2: icr.io/db2_community/db2:12.1.5.0

  • MariaDB: docker.io/library/mariadb:12.3

  • Microsoft SQL Server: mcr.microsoft.com/mssql/server:2025-latest
    On ARM (aarch64),mcr.microsoft.com/azure-sql-edge:latest is used instead, because the standard MS SQL Server image does not run on ARM.

  • MySQL: docker.io/library/mysql:9.7

  • Oracle Express Edition: docker.io/gvenzl/oracle-free:23-slim-faststart

  • PostgreSQL: docker.io/library/postgres:18

For certain databases, the default image may be automatically adjusted based on required database features (e.g., spatial or vector support). Explicitly setting this property overrides the automatic image selection.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_IMAGE_NAME

Show more

string

Depends on `db-kind`, see description.

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

文字列のリスト

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

The paths to SQL scripts to be loaded from the classpath and applied to the Dev Service database using the SYS privileged user. Not all databases provide a privileged user. In these cases, the property is ignored. This has no effect if the provider is not a container-based database, such as H2 or Derby.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_INIT_PRIVILEGED_SCRIPT_PATH

Show more

文字列のリスト

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

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

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

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

true for PostgreSQL/MySQL/MariaDB/Db2, false otherwise

quarkus.datasource."datasource-name".reactive.prepared-statement-cache-max-size

The maximum number of prepared statements that the client will cache.

Only effective when cache-prepared-statements is enabled (PostgreSQL, MySQL/MariaDB, Db2).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_PREPARED_STATEMENT_CACHE_MAX_SIZE

Show more

int

256

quarkus.datasource."datasource-name".reactive.prepared-statement-cache-sql-limit

The maximum length of SQL text that the client will cache in a prepared statement. Queries exceeding this limit are not cached.

Only effective when cache-prepared-statements is enabled (PostgreSQL, MySQL/MariaDB, Db2).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_PREPARED_STATEMENT_CACHE_SQL_LIMIT

Show more

int

2048

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

文字列のリスト

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

文字列のリスト

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

文字列のリスト

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

文字列のリスト

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

1S

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."datasource-name".reactive.tls-configuration-name

The name of the TLS configuration to use.

If set, the TLS configuration with the given name is used for SSL/TLS. When set, manual trust/key certificate properties are ignored.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_TLS_CONFIGURATION_NAME

Show more

string

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

The maximum time to wait for a connection from the pool.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_CONNECTION_TIMEOUT

Show more

Duration 

30S

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

The maximum number of requests allowed in the wait queue of the pool. If the queue is full, further requests are rejected.

A value of -1 means there is no limit.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MAX_WAIT_QUEUE_SIZE

Show more

int

-1

quarkus.datasource."datasource-name".reactive.pool-cleaner-period

How often the pool is checked for idle connections eligible for removal.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_POOL_CLEANER_PERIOD

Show more

Duration 

1S

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

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。 詳細は Duration#parse() Java API documentation を参照してください。

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

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

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

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

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

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

IBM Db2

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

Datasources

タイプ

デフォルト

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

Whether SSL/TLS is enabled.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_DB2_SSL

Show more

boolean

false

MariaDB/MySQL

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

Additional named datasources

タイプ

デフォルト

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

Charset for connections.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_CHARSET

Show more

string

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

Collation for connections.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_COLLATION

Show more

string

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

Desired security state of the connection to the server.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_SSL_MODE

Show more

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

disabled

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

boolean

false

quarkus.datasource."datasource-name".reactive.mysql.character-encoding

Set the Java charset to use to encode query string and parameter values. The charset is UTF-8 by default.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_CHARACTER_ENCODING

Show more

string

UTF-8

quarkus.datasource."datasource-name".reactive.mysql.server-rsa-public-key-path

Path to the server RSA public key file.

Used to securely encrypt the password during login when using SHA-256 authentication plugins (e.g., caching_sha2_password) over unencrypted (non-TLS) connections. Specifying this locally prevents Man-in-the-Middle attacks by avoiding automatic public key retrieval from the server.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_SERVER_RSA_PUBLIC_KEY_PATH

Show more

string

quarkus.datasource."datasource-name".reactive.mysql.server-rsa-public-key-value

The server RSA public key content.

Used to securely encrypt the password during login when using SHA-256 authentication plugins (e.g., caching_sha2_password) over unencrypted (non-TLS) connections. Specifying this locally prevents Man-in-the-Middle attacks by avoiding automatic public key retrieval from the server.

If set, takes precedence over server-rsa-public-key-path.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MYSQL_SERVER_RSA_PUBLIC_KEY_VALUE

Show more

string

Microsoft SQL Server

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

Datasources

タイプ

デフォルト

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."datasource-name".reactive.mssql.ssl

Whether SSL/TLS is enabled.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MSSQL_SSL

Show more

boolean

false

quarkus.datasource."datasource-name".reactive.mssql.encryption-mode

The encryption mode for the connection.

Determines the TDS protocol version and whether TLS encryption is used:

  • EncryptionMode#OFF — no encryption, TDS 7.x.

  • EncryptionMode#ON — optional encryption, TDS 7.x. Equivalent to setting ssl=true.

  • EncryptionMode#STRICT — mandatory encryption, TDS 8.0.

When this option is set it takes precedence over ssl().

Environment variable: QUARKUS_DATASOURCE_REACTIVE_MSSQL_ENCRYPTION_MODE

Show more

off, on, strict

Oracle

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

Datasources

タイプ

デフォルト

PostgreSQL

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

Datasources

タイプ

デフォルト

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."datasource-name".reactive.postgresql.ssl-mode

SSL operating mode of the client.

Environment variable: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_SSL_MODE

Show more

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

disable

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

SSL negotiation mode.

Determines how SSL/TLS negotiation is performed with the PostgreSQL server:

  • SslNegotiation#POSTGRES — traditional negotiation; the client sends an SSL request message before the TLS handshake. Compatible with all PostgreSQL versions.

  • SslNegotiation#DIRECT — direct SSL; the TLS handshake starts immediately on connect, with no prior SSL request message. Requires PostgreSQL 17 or later.

When not set, the Vert.x client default applies (SslNegotiation#POSTGRES).

Environment variable: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_SSL_NEGOTIATION

Show more

postgres, direct

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