The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides

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 を起動しようとすると失敗し、使用中の正確なイメージ名が表示されますので、それをファイルに追加してください。

ファイルの例を以下に示します。

src/main/resources/container-license-acceptance.txt
ibmcom/db2:11.5.0.0a
mcr.microsoft.com/mssql/server:2017-CU12

データベースベンダー固有の設定

コンテナーに基づくすべてのサービスは Testcontainers を使用して実行されますが、Quarkus は Testcontainers JDBC ドライバーを使用しません。そのため、追加の JDBC URL プロパティーを application.properties ファイルで設定できますが、TC_INITSCRIPTTC_INITFUNCTIONTC_DAEMONTC_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

デフォルトのデータソースは quarkus、もしくはデータソースの名前

quarkus

quarkus

Microsoft SQL Server

SA

Quarkus123

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 指定されたデータソースの固定ポート。

docker ps allows for more advanced retrieval of container information using the --format argument. For example, to get the running container ID, the image, the labels and the ports, the following command can be used:

docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Labels}}\t{{.Ports}}

An example output using Dev Services for PostgreSQL is the following:

CONTAINER ID   IMAGE          LABELS                                                                        PORTS
a7034c91a392   postgres:14    org.testcontainers.sessionId=xyz,datasource=default,org.testcontainers=true   0.0.0.0:49154->5432/tcp, :::49154->5432/tcp

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 は、以下の設定オプションをサポートしています:

ビルド時に固定される設定プロパティ - その他の設定プロパティはランタイムでオーバーライド可能です。

Configuration property

デフォルト

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: QUARKUS_DATASOURCE_DEVSERVICES_ENABLED

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: QUARKUS_DATASOURCE_DEVSERVICES_IMAGE_NAME

string

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PORT

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: QUARKUS_DATASOURCE_DEVSERVICES_COMMAND

string

The name of the database to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_DB_NAME

string

The username to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_USERNAME

string

The password to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PASSWORD

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: QUARKUS_DATASOURCE_DEVSERVICES_INIT_SCRIPT_PATH

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: QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_PROPERTIES

Map<String,String>

Generic properties that are added to the database connection URL.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PROPERTIES

Map<String,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: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_ENABLED

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: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_IMAGE_NAME

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: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_CONTAINER_PROPERTIES

Map<String,String>

Generic properties that are added to the database connection URL.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PROPERTIES

Map<String,String>

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PORT

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: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_COMMAND

string

The name of the database to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_DB_NAME

string

The username to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_USERNAME

string

The password to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PASSWORD

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: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_INIT_SCRIPT_PATH

string