Liquibaseの使用
Liquibase はデータベーススキーマ変更管理のためのオープンソースツールです。
Quarkusは、このガイドで説明するように、Liquibaseを使用するためのファーストクラスのサポートを提供しています。
ソリューション
次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。
Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.git
、 アーカイブ をダウンロードします。
ソリューションは liquibase-quickstart
ディレクトリ にあります。
Liquibaseサポートの設定
Liquibase をプロジェクトで使い始めるためには、以下のことを行う必要があります。
-
Liquibase で通常行うように、変更ログを
src/main/resources/db/changeLog.xml
ファイルに追加してください。 -
migrate-at-start
オプションを有効にしてスキーマを自動的に移行するか、Liquibase
オブジェクトをインジェクトして通常通りにマイグレーションを実行します。
pom.xml
で、以下の依存関係を追加します:
-
Liquibaseエクステンション
-
お使いの JDBC ドライバーエクステンション (
quarkus-jdbc-postgresql
,quarkus-jdbc-h2
,quarkus-jdbc-mariadb
, …)
<!-- Liquibase specific dependencies -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-liquibase</artifactId>
</dependency>
<!-- JDBC driver dependencies -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
// Liquibase specific dependencies
implementation("io.quarkus:quarkus-liquibase")
// JDBC driver dependencies
implementation("io.quarkus:quarkus-jdbc-postgresql")
Liquibaseのサポートは、Quarkusのデータソース設定に依存しています。この設定は、デフォルトのデータソースだけでなく、すべての 名前付きデータソース 用にカスタマイズすることができます。まず、Liquibaseがスキーマを管理できるようにするために、 application.properties
ファイルにデータソース設定を追加する必要があります。
application.properties
ファイルの例は以下の通りです。
# configure your datasource
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=sarah
quarkus.datasource.password=connor
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mydatabase
# Liquibase minimal config properties
quarkus.liquibase.migrate-at-start=true
# Liquibase optional config properties
# quarkus.liquibase.change-log=db/changeLog.xml
# quarkus.liquibase.validate-on-migrate=true
# quarkus.liquibase.clean-at-start=false
# quarkus.liquibase.database-change-log-lock-table-name=DATABASECHANGELOGLOCK
# quarkus.liquibase.database-change-log-table-name=DATABASECHANGELOG
# quarkus.liquibase.contexts=Context1,Context2
# quarkus.liquibase.labels=Label1,Label2
# quarkus.liquibase.default-catalog-name=DefaultCatalog
# quarkus.liquibase.default-schema-name=DefaultSchema
# quarkus.liquibase.liquibase-catalog-name=liquibaseCatalog
# quarkus.liquibase.liquibase-schema-name=liquibaseSchema
# quarkus.liquibase.liquibase-tablespace-name=liquibaseSpace
Liquibase の命名規則に従って、デフォルトのフォルダーに changeLog ファイルを追加します: src/main/resources/db/changeLog.xml
yaml, json, xml, sql changeLog ファイル形式もサポートされています。
<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext
https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
http://www.liquibase.org/xml/ns/dbchangelog
https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
<changeSet author="quarkus" id="1">
<createTable tableName="quarkus">
<column name="ID" type="VARCHAR(255)">
<constraints nullable="false"/>
</column>
<column name="NAME" type="VARCHAR(255)"/>
</createTable>
</changeSet>
</databaseChangeLog>
これでアプリケーションを起動することが出来るようになり、Quarkusはあなたの設定に従ってLiquibaseの更新メソッドを実行します:
import io.quarkus.liquibase.LiquibaseFactory; (1)
@ApplicationScoped
public class MigrationService {
// You can Inject the object if you want to use it manually
@Inject
LiquibaseFactory liquibaseFactory; (2)
public void checkMigration() {
// Get the list of liquibase change set statuses
try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
List<ChangeSetStatus> status = liquibase.getChangeSetStatuses(liquibaseFactory.createContexts(), liquibaseFactory.createLabels());
}
}
}
1 | Quarkusエクステンションは、Liquibaseインスタンスを初期化するためのファクトリーを提供します。 |
2 | Liquibaseメソッドを直接使用したい場合は、QuarkusのLiquibaseファクトリーをインジェクトします。 |
複数のデータソース
Liquibase は複数のデータソースに対して設定することができます。Liquibase のプロパティーは、例えば、名前のついたデータソースと全く同じように接頭辞が付けられます。
quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:default
quarkus.datasource.jdbc.max-size=13
quarkus.datasource.users.db-kind=h2
quarkus.datasource.users.username=username1
quarkus.datasource.users.jdbc.url=jdbc:h2:tcp://localhost/mem:users
quarkus.datasource.users.jdbc.max-size=11
quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:tcp://localhost/mem:inventory
quarkus.datasource.inventory.jdbc.max-size=12
# Liquibase configuration for the default datasource
quarkus.liquibase.schemas=DEFAULT_TEST_SCHEMA
quarkus.liquibase.change-log=db/changeLog.xml
quarkus.liquibase.migrate-at-start=true
# Liquibase configuration for the "users" datasource
quarkus.liquibase.users.schemas=USERS_TEST_SCHEMA
quarkus.liquibase.users.change-log=db/users.xml
quarkus.liquibase.users.migrate-at-start=true
# Liquibase configuration for the "inventory" datasource
quarkus.liquibase.inventory.schemas=INVENTORY_TEST_SCHEMA
quarkus.liquibase.inventory.change-log=db/inventory.xml
quarkus.liquibase.inventory.migrate-at-start=true
キーに余分なビットがあることに注意してください。構文は以下の通りです。 quarkus.liquibase.[optional name.][datasource property]
.
設定をしないと、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
LiquibaseFactory liquibaseFactory; (1)
@Inject
@LiquibaseDataSource("inventory") (2)
LiquibaseFactory liquibaseFactoryForInventory;
@Inject
@Named("liquibase_users") (3)
LiquibaseFactory liquibaseFactoryForUsers;
public void checkMigration() {
// Use the liquibase instance manually
try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
liquibase.dropAll(); (4)
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()); (5)
}
}
}
1 | LiquibaseFactory オブジェクトをインジェクトする |
2 | Quarkus LiquibaseDataSource 修飾子を使用して、指定されたデータソースに Liquibase を注入します。 |
3 | 指定されたデータソースに Liquibase を注入する |
4 | Liquibase インスタンスを直接使う |
5 | 適用された、または適用されていない liquibase ChangeSets のリスト |
Kubernetes上でのLiquibase
時には、アプリケーションの起動毎に 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 liquibase change log file. All included change log files in this file are scanned and add to the projects. 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 |
|
Environment variable: Show more |
boolean |
|
Environment variable: Show more |
boolean |
|
Environment variable: Show more |
boolean |
|
Comma-separated case-sensitive list of ChangeSet contexts to execute for liquibase. Environment variable: Show more |
list of string |
|
Comma-separated case-sensitive list of expressions defining labeled ChangeSet to execute for liquibase. Environment variable: Show more |
list of string |
|
Map of parameters that can be used inside Liquibase changeLog files. Environment variable: Show more |
Map<String,String> |
|
The liquibase change log lock table name. Name of table to use for tracking concurrent Liquibase usage. Environment variable: Show more |
string |
|
The liquibase change log table name. Name of table to use for tracking change history. Environment variable: Show more |
string |
|
The name of Liquibase’s default catalog. Environment variable: Show more |
string |
|
The name of Liquibase’s default schema. Overwrites the default schema name (returned by the RDBMS) with a different database schema. Environment variable: Show more |
string |
|
The username that Liquibase uses to connect to the database. If no specific username is configured, falls back to the datasource username and password. Environment variable: Show more |
string |
|
The password that Liquibase uses to connect to the database. If no specific password is configured, falls back to the datasource username and password. Environment variable: Show more |
string |
|
The name of the catalog with the liquibase tables. Environment variable: Show more |
string |
|
The name of the schema with the liquibase tables. Environment variable: Show more |
string |
|
The name of the tablespace where the -LOG and -LOCK tables will be created (if they do not exist yet). Environment variable: Show more |
string |
|
Allows duplicated changeset identifiers without failing Liquibase execution. Environment variable: Show more |
boolean |
|
型 |
デフォルト |
|
The liquibase change log file. All included change log files in this file are scanned and add to the projects. Environment variable: Show more |
string |
|
The search path for DirectoryResourceAccessor Environment variable: Show more |
list of string |
|
Environment variable: Show more |
boolean |
|
Environment variable: Show more |
boolean |
|
Environment variable: Show more |
boolean |
|
Comma-separated case-sensitive list of ChangeSet contexts to execute for liquibase. Environment variable: Show more |
list of string |
|
Comma-separated case-sensitive list of expressions defining labeled ChangeSet to execute for liquibase. Environment variable: Show more |
list of string |
|
Map of parameters that can be used inside Liquibase changeLog files. Environment variable: Show more |
Map<String,String> |
|
The liquibase change log lock table name. Name of table to use for tracking concurrent Liquibase usage. Environment variable: Show more |
string |
|
The liquibase change log table name. Name of table to use for tracking change history. Environment variable: Show more |
string |
|
The name of Liquibase’s default catalog. Environment variable: Show more |
string |
|
The name of Liquibase’s default schema. Overwrites the default schema name (returned by the RDBMS) with a different database schema. Environment variable: Show more |
string |
|
The username that Liquibase uses to connect to the database. If no specific username is configured, falls back to the datasource username and password. Environment variable: Show more |
string |
|
The password that Liquibase uses to connect to the database. If no specific password is configured, falls back to the datasource username and password. Environment variable: Show more |
string |
|
The name of the catalog with the liquibase tables. Environment variable: Show more |
string |
|
The name of the schema with the liquibase tables. Environment variable: Show more |
string |
|
The name of the tablespace where the -LOG and -LOCK tables will be created (if they do not exist yet). Environment variable: Show more |
string |
|
Allows duplicated changeset identifiers without failing Liquibase execution. Environment variable: Show more |
boolean |