编辑此页面

使用 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-postgresqlquarkus-jdbc-h2quarkus-jdbc-mariadb,...)

pom.xml
<!-- 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>
build.gradle
// 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 初始化 JobJob 执行初始化,而实际的 Pod 将在 Job 成功完成后启动。

禁用

该功能默认启用,可以使用以下方式全局禁用

quarkus.kubernetes.init-task-defaults.enabled=false

或在 OpenShift 上

quarkus.openshift.init-task-defaults.enabled=false

使用控制等待 Job 的自定义镜像

要更改默认的 wait-for 镜像 groundnuty/k8s-wait-for:no-root-v1.7,您可以使用

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

注意:在此上下文中,全局意味着对于所有支持初始化任务外部化的扩展

配置参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

启用/禁用 Liquibase 的标志。

环境变量:QUARKUS_LIQUIBASE_ENABLED

显示更多

布尔值

true

数据源

类型

默认

quarkus.liquibase."datasource-name".change-log

liquibase changelog 文件。该文件中的所有包含的 changelog 文件都会被扫描并添加到项目中。

环境变量:QUARKUS_LIQUIBASE_CHANGE_LOG

显示更多

字符串

db/changeLog.xml

quarkus.liquibase."datasource-name".search-path

DirectoryResourceAccessor 的搜索路径

环境变量:QUARKUS_LIQUIBASE_SEARCH_PATH

显示更多

字符串列表

quarkus.liquibase."datasource-name".migrate-at-start

true 表示在应用程序启动时自动执行 Liquibase,否则为 false

环境变量:QUARKUS_LIQUIBASE_MIGRATE_AT_START

显示更多

布尔值

false

quarkus.liquibase."datasource-name".validate-on-migrate

true 表示验证已应用的更改与可用更改是否一致,否则为 false。仅当 migration-at-starttrue 时使用。

环境变量:QUARKUS_LIQUIBASE_VALIDATE_ON_MIGRATE

显示更多

布尔值

true

quarkus.liquibase."datasource-name".clean-at-start

true 表示在应用程序启动时自动执行 Liquibase clean 命令,否则为 false

环境变量:QUARKUS_LIQUIBASE_CLEAN_AT_START

显示更多

布尔值

false

quarkus.liquibase."datasource-name".contexts

用于 Liquibase 执行的 ChangeSet context 的逗号分隔的区分大小写的列表。

环境变量:QUARKUS_LIQUIBASE_CONTEXTS

显示更多

字符串列表

quarkus.liquibase."datasource-name".labels

用于 Liquibase 执行的标签 ChangeSet 的逗号分隔的区分大小写的表达式列表。

环境变量:QUARKUS_LIQUIBASE_LABELS

显示更多

字符串列表

quarkus.liquibase."datasource-name".change-log-parameters."parameter-name"

可在 Liquibase changelog 文件中使用的参数映射。

环境变量:QUARKUS_LIQUIBASE_CHANGE_LOG_PARAMETERS__PARAMETER_NAME_

显示更多

Map<String,String>

quarkus.liquibase."datasource-name".database-change-log-lock-table-name

liquibase changelog 锁定表名。用于跟踪并发 Liquibase 使用的表名。

环境变量:QUARKUS_LIQUIBASE_DATABASE_CHANGE_LOG_LOCK_TABLE_NAME

显示更多

字符串

DATABASECHANGELOGLOCK

quarkus.liquibase."datasource-name".database-change-log-table-name

liquibase changelog 表名。用于跟踪更改历史的表名。

环境变量:QUARKUS_LIQUIBASE_DATABASE_CHANGE_LOG_TABLE_NAME

显示更多

字符串

DATABASECHANGELOG

quarkus.liquibase."datasource-name".default-catalog-name

Liquibase 的默认目录名称。

环境变量:QUARKUS_LIQUIBASE_DEFAULT_CATALOG_NAME

显示更多

字符串

quarkus.liquibase."datasource-name".default-schema-name

Liquibase 的默认模式名称。用不同的数据库模式覆盖 RDBMS 返回的默认模式名称。

环境变量:QUARKUS_LIQUIBASE_DEFAULT_SCHEMA_NAME

显示更多

字符串

quarkus.liquibase."datasource-name".username

Liquibase 用于连接数据库的用户名。如果没有配置特定的用户名,则回退到数据源的用户名和密码。

环境变量:QUARKUS_LIQUIBASE_USERNAME

显示更多

字符串

quarkus.liquibase."datasource-name".password

Liquibase 用于连接数据库的密码。如果没有配置特定的密码,则回退到数据源的用户名和密码。

环境变量:QUARKUS_LIQUIBASE_PASSWORD

显示更多

字符串

quarkus.liquibase."datasource-name".liquibase-catalog-name

包含 liquibase 表的目录名称。

环境变量:QUARKUS_LIQUIBASE_LIQUIBASE_CATALOG_NAME

显示更多

字符串

quarkus.liquibase."datasource-name".liquibase-schema-name

包含 liquibase 表的模式名称。

环境变量:QUARKUS_LIQUIBASE_LIQUIBASE_SCHEMA_NAME

显示更多

字符串

quarkus.liquibase."datasource-name".liquibase-tablespace-name

创建 -LOG 和 -LOCK 表(如果它们尚不存在)的表空间名称。

环境变量:QUARKUS_LIQUIBASE_LIQUIBASE_TABLESPACE_NAME

显示更多

字符串

quarkus.liquibase."datasource-name".allow-duplicated-changeset-identifiers

允许重复的 changeset 标识符而不中断 Liquibase 执行。

环境变量:QUARKUS_LIQUIBASE_ALLOW_DUPLICATED_CHANGESET_IDENTIFIERS

显示更多

布尔值

quarkus.liquibase."datasource-name".secure-parsing

Liquibase 是否应强制执行安全解析。

如果强制执行安全解析,不安全的文件可能无法被解析。

环境变量:QUARKUS_LIQUIBASE_SECURE_PARSING

显示更多

布尔值

true

相关内容