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")
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: Show more |
string |
|
The search path for DirectoryResourceAccessor Environment variable: Show more |
list of string |
|
Flag to enable / disable Liquibase. Environment variable: Show more |
boolean |
|
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 |