Using Liquibase MongoDB

Liquibaseは、データベースのスキーマ変更管理のためのオープンソースのツールで、 MongoDB エクステンションを通じて、MongoDB データベースを管理できます。

Quarkusは、このガイドで説明されるように、Liquibase MongoDB エクステンションを使用するためのファーストクラスのサポートを提供します。

ソリューション

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

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

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

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

Liquibase MongoDB エクステンションをあなたのプロジェクトで使い始めるには、以下が必要です。

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

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

プロジェクトのベース・ディレクトリで以下のコマンドを実行することで、 liquibase-mongodb エクステンションをプロジェクトに追加できます:

CLI
quarkus extension add liquibase-mongodb
Maven
./mvnw quarkus:add-extension -Dextensions='liquibase-mongodb'
Gradle
./gradlew addExtension --extensions='liquibase-mongodb'

これにより、ビルドファイルに以下が追加されます:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-liquibase-mongodb</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-liquibase-mongodb")

Liquibase MongoDB エクステンションのサポートは、Quarkus MongoDB クライアント設定に依存しています。 今のところ、複数のクライアントをサポートしていません。 Liquibase がスキーマを管理できるようにするために、 application.properties ファイルに MongoDB 設定を追加する必要があります。

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

# configure MongoDB
quarkus.mongodb.connection-string = mongodb://localhost:27017/mydatabase

# Liquibase MongoDB minimal config properties
quarkus.liquibase-mongodb.migrate-at-start=true

# Liquibase MongoDB optional config properties
# quarkus.liquibase-mongodb.change-log=db/changeLog.xml
# quarkus.liquibase-mongodb.validate-on-migrate=true
# quarkus.liquibase-mongodb.clean-at-start=false
# quarkus.liquibase-mongodb.contexts=Context1,Context2
# quarkus.liquibase-mongodb.labels=Label1,Label2
# quarkus.liquibase-mongodb.default-catalog-name=DefaultCatalog
# quarkus.liquibase-mongodb.default-schema-name=DefaultSchema
Liquibase needs a database either in the connection string or with the quarkus.mongodb.database property.
By default, Liquibase MongoDB is configured to use the default MongoDB client Quarkus creates, but you can configure the extension to use a named client by setting quarkus.liquibase-mongodb.mongo-client-name.

Liquibase の命名規則に従って、デフォルトフォルダに変更ログファイルを追加します: src/main/resources/db/changeLog.xml 変更ログは、YAML、JSON、XML 形式がサポートされています。

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd">

    <changeSet id="1" author="loic">
        <ext:createCollection collectionName="Fruit"/>

        <ext:createIndex collectionName="Fruit">
            <ext:keys>{color: 1}</ext:keys>
            <ext:options>{name: "colorIdx"}</ext:options>
        </ext:createIndex>

        <ext:insertOne collectionName="Fruit">
            <ext:document>{"name":"orange", "color": "orange"}</ext:document>
        </ext:insertOne>
    </changeSet>

</databaseChangeLog>

これで、アプリケーションを起動できるようになり、Quarkusは設定に従ってLiquibaseのアップデートメソッドを実行します。

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
    LiquibaseMongodbFactory liquibaseMongodbFactory; (1)

    public void checkMigration() {
        // Use the liquibase instance manually
        try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
            liquibase.dropAll(); (2)
            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()); (3)
        }
    }
}
1 LiquibaseFactory オブジェクトのインジェクション
2 Liquibaseのインスタンスの直接使用
3 適用された、または適用されていないliquibaseのChangeSetsのリスト

Kubernetes上でのLiquibase Mongodb

時には、アプリケーションの起動毎に 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 change log file

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CHANGE_LOG

Show more

string

db/changeLog.xml

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE_MONGODB_SEARCH_PATH

Show more

文字列のリスト

Flag to enable / disable Liquibase.

Environment variable: QUARKUS_LIQUIBASE_MONGODB_ENABLED

Show more

boolean

true

Mongodb client name to use to connect to database, defaults to the default mongodb client.

Environment variable: QUARKUS_LIQUIBASE_MONGODB_MONGO_CLIENT_NAME

Show more

string

The migrate at start flag

Environment variable: QUARKUS_LIQUIBASE_MONGODB_MIGRATE_AT_START

Show more

boolean

false

The validate on update flag

Environment variable: QUARKUS_LIQUIBASE_MONGODB_VALIDATE_ON_MIGRATE

Show more

boolean

true

The clean at start flag

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CLEAN_AT_START

Show more

boolean

false

The parameters to be passed to the changelog. Defined as key value pairs.

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CHANGE_LOG_PARAMETERS__CHANGE_LOG_PARAMETERS_

Show more

Map<String,String>

The list of contexts

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CONTEXTS

Show more

文字列のリスト

The list of labels

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LABELS

Show more

文字列のリスト

The default catalog name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_DEFAULT_CATALOG_NAME

Show more

string

The default schema name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_DEFAULT_SCHEMA_NAME

Show more

string

The liquibase tables catalog name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LIQUIBASE_CATALOG_NAME

Show more

string

The liquibase tables schema name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LIQUIBASE_SCHEMA_NAME

Show more

string

The liquibase tables tablespace name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LIQUIBASE_TABLESPACE_NAME

Show more

string

関連コンテンツ