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

Liquibase MongoDBの使用

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

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

ソリューション

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

Gitリポジトリをクローンする: git clone https://github.com/quarkusio/quarkus-quickstarts.git 、または archive をダウンロードする。

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

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

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

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

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

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

コマンドラインインタフェース
quarkus extension add liquibase-mongodb
Maven
./mvnw quarkus:add-extension -Dextensions='liquibase-mongodb'
Gradle
./gradlew addExtension --extensions='liquibase-mongodb'

これにより、pom.xml に以下が追加されます:

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

# 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 MongoDB は接続文字列を使用して設定されます。MongoDB クライアントの設定にマッチする接続文字列を作成するよう最善を尽くしますが、いくつかの設定プロパティが動作しない場合は、 quarkus.mongodb.connection-string の設定プロパティに直接追加してください。

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 オブジェクトを直接使用したい場合は、次のようにして注入します。

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

デフォルト

The change log file

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CHANGE_LOG

Show more

string

db/changeLog.xml

Flag to enable / disable Liquibase.

Environment variable: QUARKUS_LIQUIBASE_MONGODB_ENABLED

Show more

boolean

true

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

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CONTEXTS

Show more

list of string

The list of labels

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LABELS

Show more

list of string

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

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

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CHANGE_LOG_PARAMETERS

Show more

Map<String,String>

関連コンテンツ