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
<!-- 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] .

設定をしないと、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

デフォルト

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

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

list of string

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

Environment variable: QUARKUS_LIQUIBASE_LABELS

Show more

list of 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 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

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

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__CHANGE_LOG

Show more

string

db/changeLog.xml

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

Environment variable: QUARKUS_LIQUIBASE_CHANGE_LOG_PARAMETERS

Show more

Map<String,String>

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

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__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__NAMED_DATA_SOURCES__VALIDATE_ON_MIGRATE

Show more

boolean

true

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

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__CLEAN_AT_START

Show more

boolean

false

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

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__CONTEXTS

Show more

list of string

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

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__LABELS

Show more

list of string

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

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__CHANGE_LOG_PARAMETERS

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__NAMED_DATA_SOURCES__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__NAMED_DATA_SOURCES__DATABASE_CHANGE_LOG_TABLE_NAME

Show more

string

DATABASECHANGELOG

The name of Liquibase’s default catalog.

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__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__NAMED_DATA_SOURCES__DEFAULT_SCHEMA_NAME

Show more

string

The name of the catalog with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__LIQUIBASE_CATALOG_NAME

Show more

string

The name of the schema with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE__NAMED_DATA_SOURCES__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__NAMED_DATA_SOURCES__LIQUIBASE_TABLESPACE_NAME

Show more

string

関連コンテンツ