データソース
データを使用する多くのプロジェクトでは、リレーショナルデータベースへの接続が必要になります。
データベースへの接続を取得する一般的な方法は、データソースを使用して JDBC ドライバーを設定することです。しかし、リアクティブな方法でデータベースに接続するために、リアクティブなドライバーを使用することが好まれる場合もあります。
Quarkus では、どちらにも対応できます。
どちらも統一された柔軟な構成で構成されています。
|
Agroal は、非常に高いパフォーマンスとスケーラビリティ－を実現するように設計されたモダンで軽量な接続プールの実装です。また、セキュリティー、トランザクション管理コンポーネント、ヘルス、メトリクスなど、Quarkus における他のコンポーネントとのファーストクラスの統合を特徴としています。 |
このガイドでは、以下の方法を説明します。
-
データソースまたは複数のデータソースの設定
-
コード内のデータソースへの参照を取得する方法
-
利用可能なプールチューニング構成プロパティー
このガイドでは、主にデータソースの設定について説明します。リアクティブデータソースの利用方法の詳細を知りたい場合は、 Reactive SQL clientsガイドを参照してください。
詳細な説明
これはデータソースの設定についての簡単な紹介です。すべての動作について理解を深める場合は、このガイドの後の段落でさらに多くの情報を得ることができます。
ゼロコンフィグセットアップ（DevServices）
Quarkusでは、テストや開発モードで実行する際に、ゼロコンフィグでデータベースをすぐに提供することができます。これは、私たちがDevServicesと呼ぶ機能です。データベースの種類によっては、この機能を使用するためにdockerをインストールする必要があります。DevServicesは以下のオープンソースデータベースでサポートされています。
DevServicesを使用する場合、必要なのは使用するデータベースの種類（リアクティブまたはJDBC、またはその両方）に応じた関連するエクステンションを含めることだけで、データベースのURLやユーザー名、パスワードを設定する必要はありません。Quarkusがデータベースを提供するので、ユーザーは設定に煩わされることなく、ただコーディングを開始することが出来ます。
詳細およびオプションの構成については、 Databases Dev Services を参照してください。
JDBCデータソース
agroal のエクステンションに加えて、jdbc-db2、jdbc-derby、jdbc-h2、jdbc-mariadb、jdbc-mssql、jdbc-mysql、jdbc-postgresql のいずれかを追加します。
次に、データソースを設定します。
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 | JDBCエクステンションが1つしかない場合や、テストを実行していてテストスコープ付きのJDBCエクステンションが1つしかインストールされていない場合は、このオプションは必須ではありません。利用可能なエクステンションが1つしかない場合は、それが正しいものであると判断します。また、テストスコープでドライバが追加されている場合は、テストでテストスコープでドライバ追加されたドライバを使用するものとします。 |
リアクティブデータソース
使用しているデータベースに適切なリアクティブエクステンションを追加します。reactive-pg-client , reactive-mysql-client、または reactive-db2-client です。
次に、リアクティブデータソースを構成します。
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 | 上述の通り、これはオプションです。 |
デフォルトのデータソース
データソースは、JDBC データソースまたはリアクティブデータソースのいずれか 1 つでも、その両方でも構いません。データソースの設定方法と、プロジェクトに追加したエクステンションによって異なります。
データソースを定義するには、まず以下のようにします（複数のデータベースタイプがインストールされている場合にのみ必要となりますのでご注意ください）。
quarkus.datasource.db-kind=h2データベースの種類は、接続するデータベースの種類を定義します。
現在のところ、これらの組込データベースの種類が含まれています。
-
DB2:
db2 -
Derby:
derby -
H2:
h2 -
MariaDB:
mariadb -
Microsoft SQL Server:
mssql -
MySQL:
mysql -
Oracle:
oracle -
PostgreSQL:
postgresql、pgsql、またはpg
対象とするデータベースの種類を Quarkus に指定することで、設定が容易になります。JDBC ドライバーのエクステンションを使用して、設定でタイプを指定することで、Quarkus は自動的に JDBC ドライバーを解決します。そのため、自分で設定する必要はありません。組み込みのものに含まれていないデータベースの種類を使用したい場合は、other を使用して、JDBCドライバーを明示的に定義してください。
|
JVM モードの Quarkus アプリでは、任意のJDBCドライバーを使用することができます (Using other databases を参照)。しかし、アプリケーションをネイティブ実行可能ファイルにコンパイルした場合には動作しない可能性があります。 ネイティブ実行可能ファイルを作成する場合は、既存の JDBC Quarkus エクステンションを使用するこが推奨されます (または、ドライバーに貢献することをお勧めします)。 |
データベースにアクセスするために、いくつかの認証情報を定義する必要がある可能性があります。
これは、以下のプロパティーを設定することで行います。
quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>また、データソースに クレデンシャルプロバイダを使用することで、Vaultからパスワードを取得することもできます。
データベースの種類と認証情報を定義したら、JDBC データソースまたはリアクティブデータソースのいずれか 1 つ、あるいはその両方を設定することができます。
JDBCデータソース
JDBC は最も一般的なデータベース接続パターンです。通常、Hibernate ORM を使用する場合は JDBC データソースが必要です。
Maven の依存関係をインストールします。
まず、quarkus-agroal 依存関係をプロジェクトに追加する必要があります。
シンプルな Maven コマンドを使って追加することができます。
./mvnw quarkus:add-extension -Dextensions="agroal"|
Agroal は Hibernate ORM エクステンションの遷移依存関係として提供されるので、Hibernate ORM を使用している場合は、Agroal エクステンションの依存関係を明示的に追加する必要はありません。 |
また、リレーショナルデータベースドライバー用の Quarkus エクステンションを選択して追加する必要があります。
Quarkus は、以下のためのドライバーエクステンションを提供しています。
-
DB2 -
jdbc-db2 -
Derby -
jdbc-derby -
H2 -
jdbc-h2 -
MariaDB -
jdbc-mariadb -
Microsoft SQL Server -
jdbc-mssql -
MySQL -
jdbc-mysql -
Oracle -
jdbc-oracle -
PostgreSQL -
jdbc-postgresql
その他のJDBCエクステンションは、Quarkiverseにいくつか掲載されています。
-
SQLite。 プロジェクトホームページ - ドキュメント
別のデータベースに JDBC ドライバーを使用する場合は、ビルトインエクステンションのないデータベースを使用するか、別のドライバーのあるデータベースを使用します。 を参照してください。
|
H2 データベースと Derby データベースは通常、「埋め込みモード」で実行するように設定することができます。また、このエクステンションは、組み込みデータベースエンジンのネイティブ実行可能ファイルへのコンパイルに対応していません。 統合テストに関する提案については、(後述の) インメモリデータベースでのテスト をお読みください。 |
通常通り、add-extension を使ってエクステンションをインストールします。
PostgreSQL ドライバーの依存関係をインスタンスにインストールするには、以下のコマンドを実行します。
./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"JDBC の接続設定
JDBC 接続の設定は簡単で、必須のプロパティーは JDBC URL のみです。
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test|
プロパティー名の接頭辞 |
|
JDBC URL 形式の詳細については、JDBC url reference section を参照してください。 |
ビルトインデータソースのいずれかの種類を使用している場合、JDBC ドライバーは以下の値に自動的に解決されます。
| データベースの種類 | JDBC ドライバー | XA ドライバー |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
前述したように、多くの場合、この自動解決が適切で、ドライバーを設定する必要はありません。 |
ビルトインエクステンションのないデータベースを使用するか、別のドライバーのあるデータベースを使用します。
必要に応じて (例えば OpenTracing ドライバーを使用する場合)、あるいはビルトイン JDBC ドライバーエクステンションのない Quarkus のデータベースを使用する必要がある場合は、特定のドライバーを使用できます。
エクステンションがない場合でも、JVM モードで実行されている Quarkus アプリであれば、ドライバーは問題なく動作します。しかし、アプリケーションをネイティブ実行可能ファイルにコンパイルした場合には動作しません。ネイティブ実行可能ファイルを作成する予定がある場合は、既存の JDBC Quarkus エクステンションを使用することをお勧めします (または、ドライバー用のエクステンションを提供することをお勧めします)。
ここでは、OpenTracing ドライバーをどのように使用するかを説明します。
quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriverここでは、組み込みサポートのないデータベースへのアクセスを定義する方法を説明します (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リアクティブデータソース
リアクティブデータソースを使用したい場合は、Quarkus では、DB2、MySQL/MariaDB、PostgreSQL リアクティブクライアントを利用できます。
Maven の依存関係をインストールします。
使用したいデータベースに応じて、対応するエクステンションを追加します。
-
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 と一致している必要があります。
JDBC とリアクティブデータソースの同時利用
デフォルトでは、JDBC エクステンション (+ Agroal) と、指定したデータベースの種類を扱うリアクティブデータソースエクステンションの両方を含めると、これらのファイル両方が作成されます。
JDBC データソースを明示的に無効にしたい場合は、以下を使用します。
quarkus.datasource.jdbc=falseリアクティブデータソースを明示的に無効にしたい場合は、以下のようにします。
quarkus.datasource.reactive=false|
多くの場合、存在するのはJDBC ドライバーまたはリアクティブデータソースエクステンションのどちらかで、両方存在するわけではありません。そのため、上記の設定は必要ありません。 |
複数のデータソース
複数のデータソースの構成
現在のところ、複数のデータソースは JDBC と Agroal エクステンションでのみサポートされています。そのため、現在、複数のリアクティブデータソースを作成することはできません。
|
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 プロパティになりますが、名前付きデータソースを作成するためにDevServicesプロパティを指定することもできます（このガイドで後述します）。
|
名前付きデータソースインジェクション
複数のデータソースを使用する場合、それぞれの DataSource にも、値としてデータソース名のある io.quarkus.agroal.DataSource の修飾子が付けられています。上記のプロパティーを使って 3 つの異なるデータソースを設定すると、以下のようにそれぞれのデータソースを注入することもできます。
@Inject
AgroalDataSource defaultDataSource;
@Inject
@DataSource("users")
AgroalDataSource usersDataSource;
@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;データソースヘルスチェック
quarkus-smallrye-health エクステンションを使用している場合、quarkus-agroal とリアクティブクライアントエクステンションは、データソースを検証するための準備の健全性チェックを自動的に追加します。
アプリケーションの /q/health/ready エンドポイントにアクセスすると、データソースの検証ステータスに関する情報が表示されます。複数のデータソースがある場合は、すべてのデータソースがチェックされ、1 つのデータソースの検証に失敗するとすぐにステータスが DOWN になります。
この動作は、プロパティー quarkus.datasource.health.enabled で無効にすることができます。
データソースメトリクス
quarkus-micrometer または quarkus-smallrye-metrics エクステンションを使用している場合、quarkus-agroal は /q/metrics エンドポイントでいくつかのデータソースメトリクスを公開できます。これは、プロパティー quarkus.datasource.metrics.enabled を true に設定することで有効にすることができます。
公開されたメトリクスに実際の値が含まれるようにするには、メトリクス収集が Agroal メカニズムによって内部的に有効化されている必要があります。デフォルトでは、メトリクスエクステンションが存在し、Agroal エクステンションのメトリクスが有効になっている場合に、このメトリック収集メカニズムはすべてのデータソースに対してオンになります。特定のデータソースのメトリクスを無効にしたい場合は、quarkus.datasource.jdbc.enable-metrics を false (名前付きデータソースの場合は quarkus.datasource.<datasource name>.jdbc.enable-metrics) に設定することで行うことができます。これは、メトリクスを収集するメカニズムが無効化されている場合は、メトリクスの公開は意味がありません。そのため、/q/metrics エンドポイントでの公開と同様に、メトリクスの収集を無効化します。
逆に、明示的に quarkus.datasource.jdbc.enable-metrics を true (名前付きデータソースの場合は quarkus.datasource.<datasource name>.jdbc.enable-metrics) に設定することで、メトリクスエクステンションが使用されていなくても、メトリクスの収集を有効にすることができます。これは、収集したメトリクスにプログラムでアクセスする必要がある場合に便利です。インジェクト下 AgroalDataSource インスタンスで dataSource.getMetrics() を呼び出した後に利用できます。このデータソースでメトリクスの収集が無効になっている場合、すべての値はゼロになります。
Narayana Transaction Manager 統合
Narayana JTA エクステンションも利用できる場合、統合は自動的に行われます。
これを上書きするには、transactions 構成プロパティーを設定します。以下の Configuration Reference を参照してください。
名前付きデータソース
When using Dev Services the default datasource will always be created, but to specify a named datasource you need to have at least one build time property so Quarkus knows to create the datasource. You will usually either specify the db-kind property, or explicitly enable Dev Services: quarkus.datasource."name".devservices.enabled=true.
インメモリーデータベースを使用したテスト
H2 や Derby のようなデータベースの中には、迅速な統合テストを実行するためのファシリティとして "embedded mode" で一般的に使用されているものもあります。
本番で使用する予定の実際のデータベースを使用することをお勧めします。コンテナーテクノロジーによりこれが容易になりました。ただ依然として、JVM を搭載したデータベースを使用して迅速な統合テストを実行する機能が必要な場合もあります。そのような場合でも、これが可能です。
埋め込みエンジンを使用するように H2 (または Derby) を設定する場合、JVM モードでは通常通り動作しますが、そのようなアプリケーションはネイティブ実行可能ファイルにはコンパイルされません。これは、Quarkus エクステンションが、JDBC クライアントコードをネイティブコンパイルステップに対応させることのみを対象としているためです。データベースエンジン全体のネイティブ実行可能ファイルへの組み込みは現在実装されていません。
このような統合テストを JVM で排他的に実行する予定であれば、もちろん通常通りに動作します。
このような統合テストを JVM やネイティブ実行可能ファイルの両方で実行できるようにしたい場合は、いくつかの便利なヘルパーを利用できます。統合テストの任意のクラスに @QuarkusTestResource(H2DatabaseTestResource.class) または @QuarkusTestResource(DerbyDatabaseTestResource.class) を追加するだけで、テストスイートがテストを実行するために必要なデータベースを別のプロセスに組み込んで起動 (および停止) するようになります。
これらの追加のヘルパーは、H2 と Derby 用にそれぞれ Maven 座標 io.quarkus:quarkus-test-h2 と io.quarkus:quarkus-test-derby を持アーティファクトによって提供されています。
以下は、H2 の例です。
package my.app.integrationtests.db;
import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.h2.H2DatabaseTestResource;
@QuarkusTestResource(H2DatabaseTestResource.class)
public class TestResources {
}これにより、ネイティブ実行可能ファイルにコンパイルされている場合でもアプリケーションをテストすることができ、データベースは通常通り JVM で実行されます。
以下を使用して接続します。
quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:test共通データソース構成リファレンス
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
The kind of database we will connect to (e.g. h2, postgresql…). Environment variable: |
string |
|
If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. Environment variable: |
boolean |
|
The container image name to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: |
string |
|
Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: |
int |
|
The container start command to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: |
string |
|
The name of the database to use if this Dev Service supports overriding it. Environment variable: |
string |
|
The username to use if this Dev Service supports overriding it. Environment variable: |
string |
|
The password to use if this Dev Service supports overriding it. Environment variable: |
string |
|
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: |
boolean |
|
Whether or not an 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: |
boolean |
|
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. NOTE: 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: |
boolean |
|
The datasource username Environment variable: |
string |
|
The datasource password Environment variable: |
string |
|
The credentials provider name Environment variable: |
string |
|
The credentials provider bean name.
It is the Environment variable: |
string |
|
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: |
|
|
Generic properties that are added to the database connection URL. Environment variable: |
|
|
タイプ |
デフォルト |
|
The kind of database we will connect to (e.g. h2, postgresql…). Environment variable: |
string |
|
If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. Environment variable: |
boolean |
|
The container image name to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: |
string |
|
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: |
|
|
Generic properties that are added to the database connection URL. Environment variable: |
|
|
Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: |
int |
|
The container start command to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: |
string |
|
The name of the database to use if this Dev Service supports overriding it. Environment variable: |
string |
|
The username to use if this Dev Service supports overriding it. Environment variable: |
string |
|
The password to use if this Dev Service supports overriding it. Environment variable: |
string |
|
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: |
boolean |
|
The datasource username Environment variable: |
string |
|
The datasource password Environment variable: |
string |
|
The credentials provider name Environment variable: |
string |
|
The credentials provider bean name.
It is the Environment variable: |
string |
JDBC 設定リファレンス
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
If we create a JDBC datasource for this datasource. Environment variable: |
boolean |
|
The datasource driver class name Environment variable: |
string |
|
Whether we want to use regular JDBC transactions, XA, or disable all transactional capabilities.
When enabling XA you will need a driver implementing Environment variable: |
|
|
Enable datasource metrics collection. If unspecified, collecting metrics will be enabled by default if a metrics extension is active. Environment variable: |
boolean |
|
Enable JDBC tracing. Disabled by default. Environment variable: |
boolean |
|
The datasource URL Environment variable: |
string |
|
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: |
int |
|
The datasource pool minimum size Environment variable: |
int |
|
The datasource pool maximum size Environment variable: |
int |
|
The interval at which we validate idle connections in the background.
Set to Environment variable: |
|
|
Perform foreground validation on connections that have been idle for longer than the specified interval. Environment variable: |
||
The timeout before cancelling the acquisition of a new connection Environment variable: |
|
|
The interval at which we check for connection leaks. Environment variable: |
||
The interval at which we try to remove idle connections. Environment variable: |
|
|
The max lifetime of a connection. Environment variable: |
||
The transaction isolation level. Environment variable: |
|
|
Collect and display extra troubleshooting info on leaked connections. Environment variable: |
boolean |
|
Allows connections to be flushed upon return to the pool. It’s not enabled by default. Environment variable: |
boolean |
|
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: |
boolean |
|
Query executed when first using a connection. Environment variable: |
string |
|
Query executed to validate a connection. Environment variable: |
string |
|
Disable pooling to prevent reuse of Connections. Use this with when an external pool manages the life-cycle of Connections. Environment variable: |
boolean |
|
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: |
|
|
Enable JDBC tracing. Environment variable: |
boolean |
|
Trace calls with active Spans only Environment variable: |
boolean |
|
Ignore specific queries from being traced Environment variable: |
string |
|
Other unspecified properties to be passed to the JDBC driver when creating new connections. Environment variable: |
|
|
タイプ |
デフォルト |
|
If we create a JDBC datasource for this datasource. Environment variable: |
boolean |
|
The datasource driver class name Environment variable: |
string |
|
Whether we want to use regular JDBC transactions, XA, or disable all transactional capabilities.
When enabling XA you will need a driver implementing Environment variable: |
|
|
Enable datasource metrics collection. If unspecified, collecting metrics will be enabled by default if a metrics extension is active. Environment variable: |
boolean |
|
Enable JDBC tracing. Disabled by default. Environment variable: |
boolean |
|
The datasource URL Environment variable: |
string |
|
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: |
int |
|
The datasource pool minimum size Environment variable: |
int |
|
The datasource pool maximum size Environment variable: |
int |
|
The interval at which we validate idle connections in the background.
Set to Environment variable: |
|
|
Perform foreground validation on connections that have been idle for longer than the specified interval. Environment variable: |
||
The timeout before cancelling the acquisition of a new connection Environment variable: |
|
|
The interval at which we check for connection leaks. Environment variable: |
||
The interval at which we try to remove idle connections. Environment variable: |
|
|
The max lifetime of a connection. Environment variable: |
||
The transaction isolation level. Environment variable: |
|
|
Collect and display extra troubleshooting info on leaked connections. Environment variable: |
boolean |
|
Allows connections to be flushed upon return to the pool. It’s not enabled by default. Environment variable: |
boolean |
|
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: |
boolean |
|
Query executed when first using a connection. Environment variable: |
string |
|
Query executed to validate a connection. Environment variable: |
string |
|
Disable pooling to prevent reuse of Connections. Use this with when an external pool manages the life-cycle of Connections. Environment variable: |
boolean |
|
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: |
|
|
Other unspecified properties to be passed to the JDBC driver when creating new connections. Environment variable: |
|
|
Enable JDBC tracing. Environment variable: |
boolean |
|
Trace calls with active Spans only Environment variable: |
boolean |
|
Ignore specific queries from being traced Environment variable: |
string |
|
|
期間フォーマットについて
期間のフォーマットは標準の 数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 |
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>] または 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>] または address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]
- 例
-
jdbc:mysql://localhost:3306/test
この機能は、公式ドキュメント に詳しい情報が掲載されています。
Oracle
jdbc:oracle:driver_type:@database_specifier
- 例
-
jdbc:oracle:thin:@localhost:1521/ORCL_SVC
詳しくは、 公式ドキュメントをご覧ください。
PostgreSQL
PostgreSQL は、以下の他のデータベースと同様に、サーバーとしてのみ動作します。そのため、接続の詳細を指定するか、デフォルトを使用する必要があります。
jdbc:postgresql:[//][host][:port][/database][?key=value…]
- 例
-
jdbc:postgresql://localhost/test
各部のデフォルトは以下の通りです。
host-
localhost
port-
5432
database-
ユーザー名と同じ名前
公式ドキュメント では、より詳細な情報を紹介しており、同様にオプションのパラメーターをリストアップしています。
リアクティブデータソース構成リファレンス
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
If we create a Reactive datasource for this datasource. Environment variable: |
boolean |
|
Whether prepared statements should be cached on the client side. Environment variable: |
boolean |
|
The datasource URL. Environment variable: |
string |
|
The datasource pool maximum size. Environment variable: |
int |
|
When a new connection object is created, the pool assigns it an event loop.
When Environment variable: |
int |
|
Whether all server certificates should be trusted. Environment variable: |
boolean |
|
PEM Trust config is disabled by default. Environment variable: |
boolean |
|
Comma-separated list of the trust certificate files (Pem format). Environment variable: |
list of string |
|
JKS config is disabled by default. Environment variable: |
boolean |
|
Path of the key file (JKS format). Environment variable: |
string |
|
Password of the key file. Environment variable: |
string |
|
PFX config is disabled by default. Environment variable: |
boolean |
|
Path to the key file (PFX format). Environment variable: |
string |
|
Password of the key. Environment variable: |
string |
|
PEM Key/cert config is disabled by default. Environment variable: |
boolean |
|
Comma-separated list of the path to the key files (Pem format). Environment variable: |
list of string |
|
Comma-separated list of the path to the certificate files (Pem format). Environment variable: |
list of string |
|
JKS config is disabled by default. Environment variable: |
boolean |
|
Path of the key file (JKS format). Environment variable: |
string |
|
Password of the key file. Environment variable: |
string |
|
PFX config is disabled by default. Environment variable: |
boolean |
|
Path to the key file (PFX format). Environment variable: |
string |
|
Password of the key. Environment variable: |
string |
|
The number of reconnection attempts when a pooled connection cannot be established on first try. Environment variable: |
int |
|
The interval between reconnection attempts when a pooled connection cannot be established on first try. Environment variable: |
|
|
The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS, LDAPS or an empty string. Environment variable: |
string |
|
The maximum time a connection remains unused in the pool before it is closed. Environment variable: |
|
|
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 Environment variable: |
boolean |
|
Set the pool name, used when the pool is shared among datasources, otherwise ignored. Environment variable: |
string |
|
Other unspecified properties to be passed through the Reactive SQL Client directly to the database when new connections are initiated. Environment variable: |
|
|
タイプ |
デフォルト |
|
If we create a Reactive datasource for this datasource. Environment variable: |
boolean |
|
Whether prepared statements should be cached on the client side. Environment variable: |
boolean |
|
The datasource URL. Environment variable: |
string |
|
The datasource pool maximum size. Environment variable: |
int |
|
When a new connection object is created, the pool assigns it an event loop.
When Environment variable: |
int |
|
Whether all server certificates should be trusted. Environment variable: |
boolean |
|
PEM Trust config is disabled by default. Environment variable: |
boolean |
|
Comma-separated list of the trust certificate files (Pem format). Environment variable: |
list of string |
|
JKS config is disabled by default. Environment variable: |
boolean |
|
Path of the key file (JKS format). Environment variable: |
string |
|
Password of the key file. Environment variable: |
string |
|
PFX config is disabled by default. Environment variable: |
boolean |
|
Path to the key file (PFX format). Environment variable: |
string |
|
Password of the key. Environment variable: |
string |
|
PEM Key/cert config is disabled by default. Environment variable: |
boolean |
|
Comma-separated list of the path to the key files (Pem format). Environment variable: |
list of string |
|
Comma-separated list of the path to the certificate files (Pem format). Environment variable: |
list of string |
|
JKS config is disabled by default. Environment variable: |
boolean |
|
Path of the key file (JKS format). Environment variable: |
string |
|
Password of the key file. Environment variable: |
string |
|
PFX config is disabled by default. Environment variable: |
boolean |
|
Path to the key file (PFX format). Environment variable: |
string |
|
Password of the key. Environment variable: |
string |
|
The number of reconnection attempts when a pooled connection cannot be established on first try. Environment variable: |
int |
|
The interval between reconnection attempts when a pooled connection cannot be established on first try. Environment variable: |
|
|
The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS, LDAPS or an empty string. Environment variable: |
string |
|
The maximum time a connection remains unused in the pool before it is closed. Environment variable: |
|
|
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 Environment variable: |
boolean |
|
Set the pool name, used when the pool is shared among datasources, otherwise ignored. Environment variable: |
string |
|
Other unspecified properties to be passed through the Reactive SQL Client directly to the database when new connections are initiated. Environment variable: |
|
|
期間フォーマットについて
期間のフォーマットは標準の 数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 |
リアクティブな DB2 の設定
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
Whether SSL/TLS is enabled. Environment variable: |
boolean |
|
タイプ |
デフォルト |
|
Whether SSL/TLS is enabled. Environment variable: |
boolean |
|
リアクティブな MariaDB/MySQL 固有の設定
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
Charset for connections. Environment variable: |
string |
|
Collation for connections. Environment variable: |
string |
|
Desired security state of the connection to the server. See MySQL Reference Manual. Environment variable: |
|
|
タイプ |
デフォルト |
|
Charset for connections. Environment variable: |
string |
|
Collation for connections. Environment variable: |
string |
|
Desired security state of the connection to the server. See MySQL Reference Manual. Environment variable: |
|
|
リアクティブなMicrosoft SQL Server 固有の設定
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
The desired size (in bytes) for TDS packets. Environment variable: |
int |
|
Whether SSL/TLS is enabled. Environment variable: |
boolean |
|
タイプ |
デフォルト |
|
The desired size (in bytes) for TDS packets. Environment variable: |
int |
|
Whether SSL/TLS is enabled. Environment variable: |
boolean |
|
リアクティブな PostgreSQL 固有の設定
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
The maximum number of inflight database commands that can be pipelined. Environment variable: |
int |
|
SSL operating mode of the client. See Protection Provided in Different Modes. Environment variable: |
|
|
タイプ |
デフォルト |
|
The maximum number of inflight database commands that can be pipelined. Environment variable: |
int |
|
SSL operating mode of the client. See Protection Provided in Different Modes. Environment variable: |
|
|
リアクティブデータソース構成リファレンス
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
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でパラメータを設定すると、デフォルトのプロパティがオーバーライドされます。 |
