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
./mvnw quarkus:add-extension -Dextensions='liquibase-mongodb'
./gradlew addExtension --extensions='liquibase-mongodb'
これにより、 pom.xml
に以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-liquibase-mongodb</artifactId>
</dependency>
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: Show more |
boolean |
|
型 |
デフォルト |
|
The change log file Environment variable: Show more |
string |
|
The search path for DirectoryResourceAccessor Environment variable: Show more |
list of string |
|
Mongodb client name to use to connect to database, defaults to the default mongodb client. Environment variable: Show more |
string |
|
The migrate at start flag Environment variable: Show more |
boolean |
|
The validate on update flag Environment variable: Show more |
boolean |
|
The clean at start flag Environment variable: Show more |
boolean |
|
The parameters to be passed to the changelog. Defined as key value pairs. Environment variable: Show more |
Map<String,String> |
|
The list of contexts Environment variable: Show more |
list of string |
|
The list of labels Environment variable: Show more |
list of string |
|
The default catalog name Environment variable: Show more |
string |
|
The default schema name Environment variable: Show more |
string |
|
The liquibase tables catalog name Environment variable: Show more |
string |
|
The liquibase tables schema name Environment variable: Show more |
string |
|
The liquibase tables tablespace name Environment variable: Show more |
string |