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

The Liquibase MongoDB extension support relies on the Quarkus MongoDB client config. You need to add the MongoDB config to the application.properties file in order to allow Liquibase to manage the schema.

以下は、 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 は、接続文字列か quarkus.mongodb.database プロパティでデータベースを必要とします。
デフォルトでは、Liquibase MongoDB は Quarkus が作成するデフォルトの MongoDB クライアントを使うように設定されていますが、 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のアップデートメソッドを実行します。

Multiple Clients

Liquibase MongoDB can be configured to support multiple clients. The properties are prefixed exactly the same way as named MongoDB clients. For example:

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

quarkus.liquibase.migrate-at-start プロパティーを有効にした場合、Liquibase インスタンスを使用する時点で、Quarkus はすでにマイグレーション操作を実行しています。
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 Inject Liquibase MongoDB for named clients using the Quarkus LiquibaseMongodbClient qualifier
3 Liquibaseのインスタンスの直接使用
4 適用された、または適用されていないliquibaseのChangeSetsのリスト

Liquibase MongoDB on Kubernetes

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

list of string

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".contexts

The list of contexts

Environment variable: QUARKUS_LIQUIBASE_MONGODB_CONTEXTS

Show more

list of string

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

The list of labels

Environment variable: QUARKUS_LIQUIBASE_MONGODB_LABELS

Show more

list of string

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

関連コンテンツ