Using Liquibase

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

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

ソリューション

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

git clone -b 3.15 https://github.com/quarkusio/quarkus-quickstarts.git で Git リポジトリーをクローンします。または、https://github.com/quarkusio/quarkus-quickstarts/archive/3.15.zip[アーカイブ] をダウンロードします。

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

Liquibaseのサポートをセットアップする

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

  • Liquibase で通常行っているように、changeLog を src/main/resources/db/changeLog.xml ファイルに追加します。

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

ビルドファイルに、以下の依存関係を追加します:

  • Liquibaseエクステンション

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

pom.xml
<!-- 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>
build.gradle
// 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] .

Without configuration, Liquibase is set up for every datasource using the default settings.

Liquibaseオブジェクトの使用

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

If you enabled the quarkus.liquibase.migrate-at-start property, by the time you use the Liquibase instance, Quarkus will already have run the migrate operation.
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 fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

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

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE_SEARCH_PATH

Show more

文字列のリスト

Flag to enable / disable Liquibase.

Environment variable: QUARKUS_LIQUIBASE_ENABLED

Show more

boolean

true

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

Environment variable: QUARKUS_LIQUIBASE_MIGRATE_AT_START

Show more

boolean

false

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

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

Environment variable: QUARKUS_LIQUIBASE_CLEAN_AT_START

Show more

boolean

false

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

Environment variable: QUARKUS_LIQUIBASE_CONTEXTS

Show more

文字列のリスト

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

Environment variable: QUARKUS_LIQUIBASE_LABELS

Show more

文字列のリスト

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>

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

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

The name of Liquibase’s default catalog.

Environment variable: QUARKUS_LIQUIBASE_DEFAULT_CATALOG_NAME

Show more

string

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

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

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

The name of the catalog with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_CATALOG_NAME

Show more

string

The name of the schema with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_SCHEMA_NAME

Show more

string

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

Allows duplicated changeset identifiers without failing Liquibase execution.

Environment variable: QUARKUS_LIQUIBASE_ALLOW_DUPLICATED_CHANGESET_IDENTIFIERS

Show more

boolean

Named datasources

タイプ

デフォルト

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CHANGE_LOG

Show more

string

db/changeLog.xml

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__SEARCH_PATH

Show more

文字列のリスト

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__MIGRATE_AT_START

Show more

boolean

false

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__DATASOURCE_NAME__VALIDATE_ON_MIGRATE

Show more

boolean

true

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CLEAN_AT_START

Show more

boolean

false

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CONTEXTS

Show more

文字列のリスト

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LABELS

Show more

文字列のリスト

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CHANGE_LOG_PARAMETERS__PARAMETER_NAME_

Show more

Map<String,String>

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DATABASE_CHANGE_LOG_LOCK_TABLE_NAME

Show more

string

DATABASECHANGELOGLOCK

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DATABASE_CHANGE_LOG_TABLE_NAME

Show more

string

DATABASECHANGELOG

The name of Liquibase’s default catalog.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DEFAULT_CATALOG_NAME

Show more

string

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__DATASOURCE_NAME__DEFAULT_SCHEMA_NAME

Show more

string

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__DATASOURCE_NAME__USERNAME

Show more

string

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__DATASOURCE_NAME__PASSWORD

Show more

string

The name of the catalog with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LIQUIBASE_CATALOG_NAME

Show more

string

The name of the schema with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LIQUIBASE_SCHEMA_NAME

Show more

string

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

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LIQUIBASE_TABLESPACE_NAME

Show more

string

Allows duplicated changeset identifiers without failing Liquibase execution.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__ALLOW_DUPLICATED_CHANGESET_IDENTIFIERS

Show more

boolean

関連コンテンツ