Dev Services for Databases
Quarkusでは、テストや開発モードで実行する際に、ゼロコンフィグでデータベースをすぐに提供することができます。これは、私たちがDevServicesと呼ぶ機能です。データベースの種類によっては、この機能を使用するためにDockerをインストールする必要があります。DevServicesは以下のデータベースでサポートされています。
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 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 は、以下の設定オプションをサポートしています:
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
|---|---|---|
If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default unless an existing configuration is present. When DevServices is enabled, Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. Environment variable: Show more |
boolean |
|
The container image name for container-based DevServices 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 DevServices 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 |
|
