Dev Services for Databases
Quarkusでは、テストや開発モードで実行する際に、ゼロコンフィグでデータベースをすぐに提供することができます。これは、私たちがDevServicesと呼ぶ機能です。データベースの種類によっては、この機能を使用するためにDockerをインストールする必要があります。DevServicesは以下のデータベースでサポートされています。
-
DB2 (コンテナー) (license acceptance が必要)
-
Derby (インプロセス)
-
H2 (インプロセス)
-
MariaDB (コンテナー)
-
Microsoft SQL Server (コンテナー) (license acceptance が必要)
-
MySQL (コンテナー)
-
Oracle Express Edition (コンテナー)
-
PostgreSQL (コンテナー)
DevServicesを使用する場合、必要なのは使用するデータベースの種類（リアクティブまたはJDBC、またはその両方）に応じた関連するエクステンションを含めることだけで、データベースのURLやユーザー名、パスワードを設定する必要はありません。Quarkusがデータベースを提供するので、ユーザーは設定に煩わされることなく、ただコーディングを開始することが出来ます。
本番データベースは通常どおりに設定する必要があります。そのため、本番データベース設定を application.properties に含め、引き続き Dev Services を使用する場合は、%prod. プロファイルを使用してデータベース設定を定義することをお勧めします。
Dev Services for Database の有効化/無効化
Dev Services for Database は、開発モードやテストの実行時に自動的にデータベースサーバーを自動的も起動します。そのため、サーバーを手動で起動する必要はありません。アプリケーションは自動的に設定されます。
application.properties でデータベースの自動起動を無効にするには、以下を使用します。
quarkus.devservices.enabled=false
# OR
quarkus.datasource.devservices.enabled=falseDev Services for database は、Dockerに依存してサーバーを起動します (インプロセスで実行される H2 と Derby を除く)。お使いの環境がDockerをサポートしていない場合は、手動でサーバーを起動するか、すでに稼働しているサーバーに接続する必要があります。
独自のデータベース - ライセンスの受諾
DB2 や MSSQL のような独自データベースを使用している場合、ライセンス契約に同意する必要があります。これを行うには、プロジェクト内に src/main/resources/container-license-acceptance.txt ファイルを作成し、データベースのイメージ名とタグを記載した行を追加します。デフォルトでは、Quarkus は現在の Testcontainers バージョンのデフォルトイメージを使用します。Quarkus を起動しようとすると失敗し、使用中の正確なイメージ名が表示されますので、それをファイルに追加してください。
ファイルの例を以下に示します。
ibmcom/db2:11.5.0.0a mcr.microsoft.com/mssql/server:2022-latest
Dev Servicesの再利用
一般的なケース
開発モードセッションまたはテストスイートの実行において、 Quarkusは設定（ユーザー名、パスワード、環境、ポートバインディングなど）が変更されない限り、常にデータベースのDev Servicesを再利用します。
データベースDev Servicesの設定が変更されると、Quarkusは常にすべてのデータベースDev Servicesを再起動します。
開発モードのセッションまたはテストスイートの実行が終了すると、 Quarkusは（デフォルトで）すべてのデータベースDev Servicesを停止します。
実行を跨いだDev Servicesコンテナの再利用
(H2 や Derby とは異なり) コンテナをベースとした Dev Services を利用しているとして、
Dev Service コンテナを 開発モードセッションやテストスイート実行 後も実行したままにしておき、
次の開発モードセッションやテストスイート実行時に再利用したい場合、可能です。
TestContainers の再利用 を有効にするには、
TestContainers の設定ファイル ( ~/.testcontainers.properties あるいは C:/Users/myuser/.testcontainers.properties ) に次の行を記述します：
testcontainers.reuse.enable=true|
コンテナの再利用を有効にしても、コンテナは起動コマンドが次を変更しない場合のみ再利用されます: 同じ環境変数（特にユーザー名/パスワード）、同じポートバインディング、同じボリュームマウント、… |
|
コンテナの再利用は、データベーススキーマやテーブルの内容など、コンテナの内部状態の再利用を意味します。 テストがデータベースに書き込むのであれば、それはおそらく望んでいないことでしょう。 Hibernate ORM を適切に設定 するか、 Flyway や Liquibase を使うことを検討してください。 |
|
コンテナの再利用を有効にすると、新しいQuarkus開発モードセッションやテストスイートの実行を開始した後でも、古いコンテナ（特に実行可能ファイルが古い）が無期限に実行されたままになる可能性があります。 その場合、これらのコンテナを手動で停止して削除する必要があります。 |
すべてのQuarkusアプリケーションではなく一部のQuarkusアプリケーションでコンテナを再利用したい場合や、 すべてのQuarkusアプリケーションではなく一部のDev Serviceでコンテナを再利用したい場合は、 設定プロパティ quarkus.datasource.devservices.reuse/ quarkus.datasource."datasource-name".devservices.reuse を`false` に設定することで、特定のDev Serviceでこの機能を無効にすることができます。
Dev Services for Databaseにボリュームをマッピング
Dockerホストのファイルシステムからコンテナへのボリュームマッピングは、スクリプトや設定などのファイルを提供するのに便利ですが、データベースデータを保存してアプリケーション再起動後に再利用することもできます。
|
ボリュームのマッピングは、PostgreSQLのようなコンテナベースのデータベースを持つDev Servicesでのみ機能します。 |
Dev Servicesのボリュームは、ファイルシステムまたはクラスパスにマッピングすることができます:
# Using a filesystem volume:
quarkus.datasource.devservices.volumes."/path/from"=/container/to (1)
# Using a classpath volume:
quarkus.datasource.devservices.volumes."classpath:./file"=/container/to (2)| 1 | ローカルマシンのファイルやフォルダ "/path/from" は、コンテナの "/container/to" でアクセスできるようになります。 |
| 2 | クラスパス・ボリュームを使用する場合、場所は "classpath: "で始まる必要があります。プロジェクトのクラスパスにあるファイルやフォルダ "./file" は、コンテナ内の "/container/to" でアクセスできるようになります。 |
| クラスパス・ボリュームを使用する場合、コンテナには読み取り権限のみが付与されます。一方、ファイルシステムボリュームを使用する場合、コンテナには読み取りと書き込みの権限が付与されます。 |
データベースデータを永続化するためのマッピングボリュームの例
PostgreSQLを使い、データベースのデータを永続化するファイルシステムのボリュームをマッピングして使う例をみてみましょう:
quarkus.datasource.db-kind=postgresql
quarkus.datasource.devservices.volumes."/local/test/data"=/var/lib/postgresql/dataコンテナ内の適切な位置は、データベースベンダーによって異なります。PostgresSQLの場合は "/var/lib/postgresql/data" ですが、MySQLの場合は、代わりにこの設定が必要です:
quarkus.datasource.db-kind=mysql
quarkus.datasource.devservices.volumes."/local/test/data"=/var/lib/mysqldevサービスを起動すると（テストやDEVモードなど）、ファイルシステムに "/local/test/data" フォルダが作成され、その中にすべてのデータベースデータが格納されることがわかります。同じdevサービスを再度実行する場合、このデータには、事前に作成したすべてのデータが含まれます。
|
Hibernate ORMでDev Servicesを使用する場合、デフォルトではQuarkusはアプリケーション起動時にデータベースを消去し、Dockerホストのファイルシステム上のデータベースデータが消去されます。この動作を回避するには、 また、アプリケーションの起動時にFlywayを使用してスキーマを移行すると、Docker hostsのファイルシステム上のデータベースデータが変更されます。 |
データベースベンダー固有の設定
コンテナーに基づくすべてのサービスは Testcontainers を使用して実行されますが、Quarkus は Testcontainers JDBC ドライバーを使用しません。そのため、追加の JDBC URL プロパティーを application.properties ファイルで設定できますが、TC_INITSCRIPT、TC_INITFUNCTION、TC_DAEMON、TC_TMPFS などの Testcontainers JDBC ドライバーがサポートする特定のプロパティーはサポートされません。
ただし、Quarkus はコンテナー自体に送信される 特定の プロパティーをサポートできます。たとえば、MariaDB/MySQL 設定ファイルをオーバーライドできる TC_MY_CNF です。
MariaDB/MySQL の設定を上書きする場合は、以下を実行します。
quarkus.datasource.devservices.container-properties.TC_MY_CNF=testcontainers/mysql-confこのサポートはデータベース固有のものであり、各開発サービスで具体的に実装する必要があります。
Dev Service として実行されるデータベースへの接続
Docker コンテナー内で実行されているデータベースと同様に、Dev Service として実行されているデータベースに接続できます。
ログイン認証情報は、データベースの要件で許可されていない場合を除き、ほとんどのデータベースで同じです。
| Database | ユーザー名 | パスワード | データベース名 |
|---|---|---|---|
PostgreSQL、MariaDB、MySQL、IBM Db2、H2 |
デフォルトのデータソースは |
|
|
Microsoft SQL Server |
|
|
|
Microsoft SQL Server Testcontainer は、ユーザー名やデータベース名の定義に対応していません。また、強力なパスワードが必要です。 |
|
これをサポートするデータベース (つまり、パスワードの上書きのみが可能な Microsoft SQL Server を除くすべてのデータベース) では、Dev Service が使用するデータベース名、ユーザー名、パスワードを上書きできます。 詳しくは、 設定リファレンス を参照してください。 |
特に設定されている場合 (以下を参照) を除き、Dev Service はランダムなポートで実行されることに注意してください。たとえば、PostgreSQL を Dev Service として実行し、ホストに psql がインストールされている場合、次の方法で接続できます。
psql -h localhost -p <random port> -U quarkusランダムポートは docker ps で確認できます。
docker ps
# returns something like this:
CONTAINER ID IMAGE [..] PORTS [..]
b826e3a168c4 postgres:14.2 [..] 0.0.0.0:49174->5432/tcp, :::49174->5432/tcp [..] (1)| 1 | ランダムポートは 49174 です。 |
Dev Service が使用しているデータベースで固定ポートを要求するには、以下を実行します。
quarkus.datasource.devservices.port=<your fixed port> (1)
quarkus.datasource."datasource-name".devservices.port=<your fixed port> (2)| 1 | デフォルトデータソースの固定ポート。 |
| 2 | 指定されたデータソースの固定ポート。 |
|
Dev Services for PostgreSQLを使用した出力例は以下の通りです。 ラベルタブでは、Quarkusによってデータソースラベルが追加されていることがわかります。これは、複数のDev Servicesが起動されている時にコンテナを区別するのに非常に便利です。 |
設定リファレンス
Dev Services for Databases は、以下の設定オプションをサポートしています:
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|||
|---|---|---|---|---|
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: Show more |
boolean |
|||
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: Show more |
string |
|||
Environment variables that are passed to the container. Environment variable: Show more |
|
|||
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: Show more |
|
|||
Generic properties that are added to the database connection URL. Environment variable: Show more |
|
|||
Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: Show more |
int |
|||
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: Show more |
string |
|||
The database name to use if this Dev Service supports overriding it. Environment variable: Show more |
string |
|||
The username to use if this Dev Service supports overriding it. Environment variable: Show more |
string |
|||
The password to use if this Dev Service supports overriding it. Environment variable: Show more |
string |
|||
The path to a SQL script 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: Show more |
string |
|||
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: Show more |
|
|||
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 configuration property is set to Environment variable: Show more |
boolean |
|
