The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
このページを編集

Liquibaseの使用

Liquibase はデータベーススキーマ変更管理のためのオープンソースツールです。

Quarkusは、このガイドで説明するように、Liquibaseを使用するためのファーストクラスのサポートを提供しています。

ソリューション

次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.gitアーカイブ をダウンロードします。

ソリューションは liquibase-quickstart ディレクトリ にあります。

Liquibaseサポートの設定

Liquibase をプロジェクトで使い始めるためには、以下のことを行う必要があります。

  • Liquibase で通常行うように、変更ログを src/main/resources/db/changeLog.xml ファイルに追加してください。

  • migrate-at-start オプションを有効にしてスキーマを自動的に移行するか、 Liquibase オブジェクトをインジェクトして通常通りにマイグレーションを実行します。

pom.xml で、以下の依存関係を追加します:

  • Liquibaseエクステンション

  • お使いの JDBC ドライバーエクステンション ( quarkus-jdbc-postgresql , quarkus-jdbc-h2 , quarkus-jdbc-mariadb , …​)

pom.xml
build.gradle
<!-- Liquibase specific dependencies --> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-liquibase</artifactId> </dependency> <!-- JDBC driver dependencies --> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-jdbc-postgresql</artifactId> </dependency>
// Liquibase specific dependencies implementation("io.quarkus:quarkus-liquibase") // JDBC driver dependencies implementation("io.quarkus:quarkus-jdbc-postgresql")

Liquibaseのサポートは、Quarkusのデータソース設定に依存しています。この設定は、デフォルトのデータソースだけでなく、すべての 名前付きデータソース 用にカスタマイズすることができます。まず、Liquibaseがスキーマを管理できるようにするために、 application.properties ファイルにデータソース設定を追加する必要があります。

application.properties ファイルの例は以下の通りです。

# configure your datasource quarkus.datasource.db-kind=postgresql quarkus.datasource.username=sarah quarkus.datasource.password=connor quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mydatabase # Liquibase minimal config properties quarkus.liquibase.migrate-at-start=true # Liquibase optional config properties # quarkus.liquibase.change-log=db/changeLog.xml # quarkus.liquibase.validate-on-migrate=true # quarkus.liquibase.clean-at-start=false # quarkus.liquibase.database-change-log-lock-table-name=DATABASECHANGELOGLOCK # quarkus.liquibase.database-change-log-table-name=DATABASECHANGELOG # quarkus.liquibase.contexts=Context1,Context2 # quarkus.liquibase.labels=Label1,Label2 # quarkus.liquibase.default-catalog-name=DefaultCatalog # quarkus.liquibase.default-schema-name=DefaultSchema # quarkus.liquibase.liquibase-catalog-name=liquibaseCatalog # quarkus.liquibase.liquibase-schema-name=liquibaseSchema # quarkus.liquibase.liquibase-tablespace-name=liquibaseSpace

Liquibase の命名規則に従って、デフォルトのフォルダーに changeLog ファイルを追加します: src/main/resources/db/changeLog.xml yaml, json, xml, sql changeLog ファイル形式もサポートされています。

<?xml version="1.1" encoding="UTF-8" standalone="no"?> <databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd"> <changeSet author="quarkus" id="1"> <createTable tableName="quarkus"> <column name="ID" type="VARCHAR(255)"> <constraints nullable="false"/> </column> <column name="NAME" type="VARCHAR(255)"/> </createTable> </changeSet> </databaseChangeLog>

これでアプリケーションを起動することが出来るようになり、Quarkusはあなたの設定に従ってLiquibaseの更新メソッドを実行します:

import io.quarkus.liquibase.LiquibaseFactory; (1) @ApplicationScoped public class MigrationService { // You can Inject the object if you want to use it manually @Inject LiquibaseFactory liquibaseFactory; (2) public void checkMigration() { // Get the list of liquibase change set statuses try (Liquibase liquibase = liquibaseFactory.createLiquibase()) { List<ChangeSetStatus> status = liquibase.getChangeSetStatuses(liquibaseFactory.createContexts(), liquibaseFactory.createLabels()); } } }
1 Quarkusエクステンションは、Liquibaseインスタンスを初期化するためのファクトリーを提供します。
2 Liquibaseメソッドを直接使用したい場合は、QuarkusのLiquibaseファクトリーをインジェクトします。

複数のデータソース

Liquibase は複数のデータソースに対して設定することができます。Liquibase のプロパティーは、例えば、名前のついたデータソースと全く同じように接頭辞が付けられます。

quarkus.datasource.db-kind=h2 quarkus.datasource.username=username-default quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/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:tcp://localhost/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:tcp://localhost/mem:inventory quarkus.datasource.inventory.jdbc.max-size=12 # Liquibase configuration for the default datasource quarkus.liquibase.schemas=DEFAULT_TEST_SCHEMA quarkus.liquibase.change-log=db/changeLog.xml quarkus.liquibase.migrate-at-start=true # Liquibase configuration for the "users" datasource quarkus.liquibase.users.schemas=USERS_TEST_SCHEMA quarkus.liquibase.users.change-log=db/users.xml quarkus.liquibase.users.migrate-at-start=true # Liquibase configuration for the "inventory" datasource quarkus.liquibase.inventory.schemas=INVENTORY_TEST_SCHEMA quarkus.liquibase.inventory.change-log=db/inventory.xml quarkus.liquibase.inventory.migrate-at-start=true

キーに余分なビットがあることに注意してください。構文は以下の通りです。 quarkus.liquibase.[optional name.][datasource property] .

設定をしないと、Liquibaseはデフォルトの設定で各データソースに設定されます。

Liquibase オブジェクトの使用

Liquibase オブジェクトを直接使いたい場合は、以下のように注入します。

quarkus.liquibase.migrate-at-start プロパティーを有効にした場合、Liquibase インスタンスを使用する時点で、Quarkus はすでにマイグレーション操作を実行しています。
import io.quarkus.liquibase.LiquibaseFactory; @ApplicationScoped public class MigrationService { // You can Inject the object if you want to use it manually @Inject LiquibaseFactory liquibaseFactory; (1) @Inject @LiquibaseDataSource("inventory") (2) LiquibaseFactory liquibaseFactoryForInventory; @Inject @Named("liquibase_users") (3) LiquibaseFactory liquibaseFactoryForUsers; public void checkMigration() { // Use the liquibase instance manually try (Liquibase liquibase = liquibaseFactory.createLiquibase()) { liquibase.dropAll(); (4) liquibase.validate(); liquibase.update(liquibaseFactory.createContexts(), liquibaseFactory.createLabels()); // Get the list of liquibase change set statuses List<ChangeSetStatus> status = liquibase.getChangeSetStatuses(liquibaseFactory.createContexts(), liquibaseFactory.createLabels()); (5) } } }
1 LiquibaseFactory オブジェクトをインジェクトする
2 Quarkus LiquibaseDataSource 修飾子を使用して、指定されたデータソースに Liquibase を注入します。
3 指定されたデータソースに Liquibase を注入する
4 Liquibase インスタンスを直接使う
5 適用された、または適用されていない liquibase ChangeSets のリスト

Kubernetes上でのLiquibase

時には、アプリケーションの起動毎に Liquibase の初期化を実行しない方が良い場合もあります。そのような例として、Kubernetes でデプロイするとき、すべてのレプリカで Liquibase を実行することは意味がありません。その代わりに、一度実行し、その後 Liquibase なしで実際のアプリケーションを開始することが望ましいです。このユースケースをサポートするために、Kubernetesのためのマニフェストを生成するとき、生成されたマニフェストはLiquibaseのためのKubernetes初期化 Job を含んでいます。 Job は初期化を行い、 Job が正常に完了すると、実際の Pod が開始されます。

無効化

この機能はデフォルトで有効になっており、以下を使用してグローバルに無効にすることができます:

quarkus.kubernetes.init-task-defaults.enabled=false

あるいはOpenShift上の場合:

quarkus.openshift.init-task-defaults.enabled=false

ジョブ待機をコントロールするカスタム画像の使用

デフォルトでは groundnuty/k8s-wait-for:no-root-v1.7 である wait-for イメージを変更するには、次を使用できます。

quarkus.kubernetes.init-task-defaults.wait-for-container.image=my/wait-for-image:1.0

あるいはOpenShift上の場合:

quarkus.openshift.init-task-defaults.wait-for-container.image=my/wait-for-image:1.0

: この文脈では、グローバルとは、 初期化タスクの外部化をサポートする全てのエクステンションに対して を意味します。

設定リファレンス

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは実行時にオーバーライド可能

Configuration property

デフォルト

Flag to enable / disable Liquibase.

Environment variable: QUARKUS_LIQUIBASE_ENABLED

Show more

boolean

true

Datasources

デフォルト

quarkus.liquibase."datasource-name".change-log

The liquibase change log file. All included change log files in this file are scanned and add to the projects.

Environment variable: QUARKUS_LIQUIBASE_CHANGE_LOG

Show more

string

db/changeLog.xml

quarkus.liquibase."datasource-name".search-path

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE_SEARCH_PATH

Show more

list of string

quarkus.liquibase."datasource-name".migrate-at-start

true to execute Liquibase automatically when the application starts, false otherwise.

Environment variable: QUARKUS_LIQUIBASE_MIGRATE_AT_START

Show more

boolean

false

quarkus.liquibase."datasource-name".validate-on-migrate

true to validate the applied changes against the available ones, false otherwise. It is only used if migration-at-start is true

Environment variable: QUARKUS_LIQUIBASE_VALIDATE_ON_MIGRATE

Show more

boolean

true

quarkus.liquibase."datasource-name".clean-at-start

true to execute Liquibase clean command automatically when the application starts, false otherwise.

Environment variable: QUARKUS_LIQUIBASE_CLEAN_AT_START

Show more

boolean

false

quarkus.liquibase."datasource-name".contexts

Comma-separated case-sensitive list of ChangeSet contexts to execute for liquibase.

Environment variable: QUARKUS_LIQUIBASE_CONTEXTS

Show more

list of string

quarkus.liquibase."datasource-name".labels

Comma-separated case-sensitive list of expressions defining labeled ChangeSet to execute for liquibase.

Environment variable: QUARKUS_LIQUIBASE_LABELS

Show more

list of string

quarkus.liquibase."datasource-name".change-log-parameters."parameter-name"

Map of parameters that can be used inside Liquibase changeLog files.

Environment variable: QUARKUS_LIQUIBASE_CHANGE_LOG_PARAMETERS__PARAMETER_NAME_

Show more

Map<String,String>

quarkus.liquibase."datasource-name".database-change-log-lock-table-name

The liquibase change log lock table name. Name of table to use for tracking concurrent Liquibase usage.

Environment variable: QUARKUS_LIQUIBASE_DATABASE_CHANGE_LOG_LOCK_TABLE_NAME

Show more

string

DATABASECHANGELOGLOCK

quarkus.liquibase."datasource-name".database-change-log-table-name

The liquibase change log table name. Name of table to use for tracking change history.

Environment variable: QUARKUS_LIQUIBASE_DATABASE_CHANGE_LOG_TABLE_NAME

Show more

string

DATABASECHANGELOG

quarkus.liquibase."datasource-name".default-catalog-name

The name of Liquibase’s default catalog.

Environment variable: QUARKUS_LIQUIBASE_DEFAULT_CATALOG_NAME

Show more

string

quarkus.liquibase."datasource-name".default-schema-name

The name of Liquibase’s default schema. Overwrites the default schema name (returned by the RDBMS) with a different database schema.

Environment variable: QUARKUS_LIQUIBASE_DEFAULT_SCHEMA_NAME

Show more

string

quarkus.liquibase."datasource-name".username

The username that Liquibase uses to connect to the database. If no specific username is configured, falls back to the datasource username and password.

Environment variable: QUARKUS_LIQUIBASE_USERNAME

Show more

string

quarkus.liquibase."datasource-name".password

The password that Liquibase uses to connect to the database. If no specific password is configured, falls back to the datasource username and password.

Environment variable: QUARKUS_LIQUIBASE_PASSWORD

Show more

string

quarkus.liquibase."datasource-name".liquibase-catalog-name

The name of the catalog with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_CATALOG_NAME

Show more

string

quarkus.liquibase."datasource-name".liquibase-schema-name

The name of the schema with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_SCHEMA_NAME

Show more

string

quarkus.liquibase."datasource-name".liquibase-tablespace-name

The name of the tablespace where the -LOG and -LOCK tables will be created (if they do not exist yet).

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_TABLESPACE_NAME

Show more

string

quarkus.liquibase."datasource-name".allow-duplicated-changeset-identifiers

Allows duplicated changeset identifiers without failing Liquibase execution.

Environment variable: QUARKUS_LIQUIBASE_ALLOW_DUPLICATED_CHANGESET_IDENTIFIERS

Show more

boolean

quarkus.liquibase."datasource-name".secure-parsing

Whether Liquibase should enforce secure parsing.

If secure parsing is enforced, insecure files may not be parsed.

Environment variable: QUARKUS_LIQUIBASE_SECURE_PARSING

Show more

boolean

true

関連コンテンツ