このページを編集

Using Liquibase MongoDB

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

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

ソリューション

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

git clone https://github.com/quarkusio/quarkus-quickstarts.git で Git リポジトリーをクローンします。または、https://github.com/quarkusio/quarkus-quickstarts/archive/main.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 がスキーマを管理できるようにするには、MongoDB 設定を application.properties ファイルに追加する必要があります。

以下は、 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 MongoDB は、複数のクライアントをサポートするように設定できます。プロパティーには、名前付き MongoDB クライアントと全く同じ方法でプレフィックスが付与されます。例:

quarkus.liquibase-mongodb.users.change-log=db/users.xml
quarkus.liquibase-mongodb.users.migrate-at-start=true

quarkus.mongodb.users.database=users
quarkus.mongodb.users.hosts=localhost:27017

quarkus.liquibase-mongodb.inventory.change-log=db/inventory.xml
quarkus.liquibase-mongodb.inventory.migrate-at-start=false

quarkus.mongodb.inventory.connection-string=mongodb://localhost:27017/inventory
The property quarkus.liquibase-mongodb.[MongoDB client name].change-log is the minimal configuration required for the extension to detect a new client setup.

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;
import io.quarkus.liquibase.mongodb.runtime.LiquibaseMongodbClient;

@ApplicationScoped
public class MigrationService {
    // You can Inject the object if you want to use it manually
    @Inject
    LiquibaseMongodbFactory liquibaseMongodbFactory; (1)

    @Inject
    @LiquibaseMongodbClient("inventory") (2)
    LiquibaseMongodbFactory liquibaseMongodbFactoryForInventory;

    public void checkMigration() {
        // Use the liquibase instance manually
        try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
            liquibase.dropAll(); (3)
            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()); (4)
        }
    }
}
1 LiquibaseFactory オブジェクトのインジェクション
2 Quarkus の LiquibaseMongodbClient 修飾子を使用して、名前付きクライアントに Liquibase MongoDB を注入します
3 Liquibaseのインスタンスの直接使用
4 適用された、または適用されていない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

タイプ

デフォルト

Flag to enable / disable Liquibase.

Environment variable: QUARKUS_LIQUIBASE_MONGODB_ENABLED

Show more

boolean

true

The liquibase configuration config by client name

タイプ

デフォルト

quarkus.liquibase-mongodb."client-name".change-log

The change log file

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CHANGE_LOG

Show more

string

db/changeLog.xml

quarkus.liquibase-mongodb."client-name".search-path

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE_MONGODB_SEARCH_PATH

Show more

文字列のリスト

quarkus.liquibase-mongodb."client-name".mongo-client-name

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

quarkus.liquibase-mongodb."client-name".migrate-at-start

The migrate at start flag

Environment variable: QUARKUS_LIQUIBASE_MONGODB_MIGRATE_AT_START

Show more

boolean

false

quarkus.liquibase-mongodb."client-name".validate-on-migrate

The validate on update flag

Environment variable: QUARKUS_LIQUIBASE_MONGODB_VALIDATE_ON_MIGRATE

Show more

boolean

true

quarkus.liquibase-mongodb."client-name".clean-at-start

The clean at start flag

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CLEAN_AT_START

Show more

boolean

false

quarkus.liquibase-mongodb."client-name".change-log-parameters."change-log-parameters"

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>

quarkus.liquibase-mongodb."client-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_MONGODB_DATABASE_CHANGE_LOG_LOCK_TABLE_NAME

Show more

string

quarkus.liquibase-mongodb."client-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_MONGODB_DATABASE_CHANGE_LOG_TABLE_NAME

Show more

string

quarkus.liquibase-mongodb."client-name".contexts

The list of contexts

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CONTEXTS

Show more

文字列のリスト

quarkus.liquibase-mongodb."client-name".labels

The list of labels

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LABELS

Show more

文字列のリスト

quarkus.liquibase-mongodb."client-name".default-catalog-name

The default catalog name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_DEFAULT_CATALOG_NAME

Show more

string

quarkus.liquibase-mongodb."client-name".default-schema-name

The default schema name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_DEFAULT_SCHEMA_NAME

Show more

string

quarkus.liquibase-mongodb."client-name".liquibase-catalog-name

The liquibase tables catalog name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LIQUIBASE_CATALOG_NAME

Show more

string

quarkus.liquibase-mongodb."client-name".liquibase-schema-name

The liquibase tables schema name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LIQUIBASE_SCHEMA_NAME

Show more

string

quarkus.liquibase-mongodb."client-name".liquibase-tablespace-name

The liquibase tables tablespace name

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LIQUIBASE_TABLESPACE_NAME

Show more

string

関連コンテンツ