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=false
Dev 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:2017-CU12
データベースベンダー固有の設定
コンテナーに基づくすべてのサービスは 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 | 指定されたデータソースの固定ポート。 |
An example output using Dev Services for PostgreSQL is the following:
In the labels tab, we see that Quarkus added the datasource label, which can be very useful in differentiating containers when multiple Dev Services have been started. |
設定リファレンス
Dev Services for Databases は、以下の設定オプションをサポートしています:
ビルド時に固定される設定プロパティ - その他の設定プロパティはランタイムでオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
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 |
|
Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database If the provider is not container based (e.g. a H2 or Derby 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: |
|
|
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 |
|
Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database If the provider is not container based (e.g. a H2 or Derby Database) then this has no effect. Environment variable: |
string |