使用 Liquibase
Liquibase 是一个用于数据库模式变更管理的开源工具。
Quarkus 为使用 Liquibase 提供了头等支持,正如本指南中所述。
解决方案
我们建议您按照以下章节中的说明,逐步创建应用程序。但是,您可以直接转到完整的示例。
克隆 Git 存储库: git clone https://github.com/quarkusio/quarkus-quickstarts.git
,或下载一个存档。
解决方案位于 liquibase-quickstart
目录中。
设置 Liquibase 支持
要开始在项目中使用 Liquibase,您只需
-
将您的 changelog 添加到
src/main/resources/db/changeLog.xml
文件中,就像您通常使用 Liquibase 一样。 -
激活
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 数据源配置。它可以针对默认数据源以及每个命名数据源进行自定义。首先,您需要将数据源配置添加到 application.properties
文件中,以便 Liquibase 管理模式。
以下是 application.properties
文件的示例
# configure your datasource
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=sarah
quarkus.datasource.password=connor
quarkus.datasource.jdbc.url=jdbc:postgresql://: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 的 update 方法。
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:///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:///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:///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.[可选名称.][数据源属性]
。
在没有配置的情况下,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
执行初始化,而实际的 Pod
将在 Job
成功完成后启动。
配置参考
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
布尔值 |
|
|
类型 |
默认 |
|
liquibase changelog 文件。该文件中的所有包含的 changelog 文件都会被扫描并添加到项目中。 环境变量: 显示更多 |
字符串 |
|
DirectoryResourceAccessor 的搜索路径 环境变量: 显示更多 |
字符串列表 |
|
环境变量: 显示更多 |
布尔值 |
|
环境变量: 显示更多 |
布尔值 |
|
环境变量: 显示更多 |
布尔值 |
|
用于 Liquibase 执行的 ChangeSet context 的逗号分隔的区分大小写的列表。 环境变量: 显示更多 |
字符串列表 |
|
用于 Liquibase 执行的标签 ChangeSet 的逗号分隔的区分大小写的表达式列表。 环境变量: 显示更多 |
字符串列表 |
|
可在 Liquibase changelog 文件中使用的参数映射。 环境变量: 显示更多 |
Map<String,String> |
|
liquibase changelog 锁定表名。用于跟踪并发 Liquibase 使用的表名。 环境变量: 显示更多 |
字符串 |
|
liquibase changelog 表名。用于跟踪更改历史的表名。 环境变量: 显示更多 |
字符串 |
|
Liquibase 的默认目录名称。 环境变量: 显示更多 |
字符串 |
|
Liquibase 的默认模式名称。用不同的数据库模式覆盖 RDBMS 返回的默认模式名称。 环境变量: 显示更多 |
字符串 |
|
Liquibase 用于连接数据库的用户名。如果没有配置特定的用户名,则回退到数据源的用户名和密码。 环境变量: 显示更多 |
字符串 |
|
Liquibase 用于连接数据库的密码。如果没有配置特定的密码,则回退到数据源的用户名和密码。 环境变量: 显示更多 |
字符串 |
|
包含 liquibase 表的目录名称。 环境变量: 显示更多 |
字符串 |
|
包含 liquibase 表的模式名称。 环境变量: 显示更多 |
字符串 |
|
创建 -LOG 和 -LOCK 表(如果它们尚不存在)的表空间名称。 环境变量: 显示更多 |
字符串 |
|
允许重复的 changeset 标识符而不中断 Liquibase 执行。 环境变量: 显示更多 |
布尔值 |
|
Liquibase 是否应强制执行安全解析。 如果强制执行安全解析,不安全的文件可能无法被解析。 环境变量: 显示更多 |
布尔值 |
|