Flyway 是一种流行的数据库迁移工具,常用于 JVM 环境。 Flyway
Quarkus 为 Flyway 提供一流支持,本指南介绍其使用方式。
设置 Flyway 支持 相关文档
如“使用 Flyway 开发”一节所示,在项目中开始使用 Flyway,只需: Developing with Flyway
-
像通常使用 Flyway 一样,把迁移文件放到 src/main/resources/db/migration。
-
启用 migrate-at-start,在启动时自动迁移 schema;或者注入 Flyway 对象,按常规方式运行迁移。
在构建文件中添加以下依赖:
-
Flyway 扩展。
-
所用 JDBC 驱动扩展,例如 quarkus-jdbc-postgresql、quarkus-jdbc-h2、quarkus-jdbc-mariadb 等。
-
除非使用 H2、SQLite 等内存或文件数据库,否则还需添加与数据库对应的 Flyway 模块依赖,详情见链接。 for more details
<!-- Flyway specific dependencies -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-flyway</artifactId>
</dependency>
<!-- JDBC driver dependencies -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
<!-- Flyway SQL Server specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-sqlserver</artifactId>
</dependency>
<!-- Flyway MariaDB/MySQL specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-mysql</artifactId>
</dependency>
<!-- Flyway Oracle specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-oracle</artifactId>
</dependency>
<!-- Flyway PostgreSQL specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>
<!-- Flyway DB2 specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-db2</artifactId>
</dependency>
<!-- HSQLDB specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-hsqldb</artifactId>
</dependency>
<!-- Informix specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-informix</artifactId>
</dependency>
<!-- Redshift specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-redshift</artifactId>
</dependency>
<!-- Saphana specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-saphana</artifactId>
</dependency>
<!-- Snowflake specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-snowflake</artifactId>
</dependency>
<!-- Sybasease specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-sybasease</artifactId>
</dependency>
<!-- Firebird specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-firebird</artifactId>
</dependency>
<!-- BigQuery specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-gcp-bigquery</artifactId>
</dependency>
<!-- Spanner specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-gcp-spanner</artifactId>
</dependency>
<!-- Singlestore specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-singlestore</artifactId>
</dependency>
// Flyway specific dependencies
implementation("io.quarkus:quarkus-flyway")
// JDBC driver dependencies
implementation("io.quarkus:quarkus-jdbc-postgresql")
// Flyway SQL Server specific dependencies
implementation("org.flywaydb:flyway-sqlserver")
// Flyway MariaDB/MySQL specific dependencies
implementation("org.flywaydb:flyway-mysql")
// Flyway Oracle specific dependencies
implementation("org.flywaydb:flyway-database-oracle")
// Flyway PostgreSQL specific dependencies
implementation("org.flywaydb:flyway-database-postgresql")
// Flyway DB2 specific dependencies
implementation("org.flywaydb:flyway-database-db2")
// HSQLDB specific dependencies
implementation("org.flywaydb:flyway-database-hsqldb")
// Informix specific dependencies
implementation("org.flywaydb:flyway-database-informix")
// Redshift specific dependencies
implementation("org.flywaydb:flyway-database-redshift")
// Saphana specific dependencies
implementation("org.flywaydb:flyway-database-saphana")
// Snowflake specific dependencies
implementation("org.flywaydb:flyway-database-snowflake")
// Sybasease specific dependencies
implementation("org.flywaydb:flyway-database-sybasease")
// Firebird specific dependencies
implementation("org.flywaydb:flyway-firebird")
// BigQuery specific dependencies
implementation("org.flywaydb:flyway-gcp-bigquery")
// Spanner specific dependencies
implementation("org.flywaydb:flyway-gcp-spanner")
// Singlestore specific dependencies
implementation("org.flywaydb:flyway-singlestore:10.15.0")
Flyway 支持依赖 Quarkus 数据源配置。默认数据源和每个命名数据源均可分别定制。首先,在 application.properties 中添加数据源配置,使 Flyway 能够管理 schema。还可以通过以下属性调整 Flyway 行为: named datasource
带标记的配置属性在构建时固定,其他配置属性可以在运行时覆盖。
|
配置属性 |
类型 |
默认值 |
|---|---|---|
|
是否在构建期间启用 Flyway。 如果禁用,不会创建 Flyway bean,也无法使用 Flyway。 Environment variable: 详细说明 |
布尔值 |
|
|
类型 |
默认值 |
|
|
逗号分隔的迁移扫描位置列表,递归扫描;位置类型由前缀决定。 没有前缀或以 classpath: 开头的位置指向类路径中的包,可以包含 SQL 和 Java 迁移。 以 filesystem: 开头的位置指向文件系统目录,只能包含 SQL 迁移,并且只会递归扫描非隐藏目录。 Environment variable: 详细说明 |
字符串列表 |
|
|
逗号分隔的 Callback 实现完整类名,用于接入 Flyway 生命周期。org.flywaydb.core.api.callback.Callback 子类必须有无参构造器,不能是抽象类;也不能有持有状态的字段,除非状态在构造器中初始化。 Environment variable: 详细说明 |
字符串列表 |
|
|
在运行时启用或禁用特定数据源的 Flyway。 Environment variable: 详细说明 |
布尔值 |
数据源激活时为 true,否则为 false。 |
|
尝试连接数据库的最大重试次数。 每次连接失败后,Flyway 等待的时间最多为 connect-retries-interval,再次尝试连接;最多重试 connectRetries 指定的次数。 Environment variable: 详细说明 |
整数 |
|
|
连接数据库时,两次重试之间的最长等待时间。 此值为连接重试间隔设置上限。 Environment variable: 详细说明 |
120秒 |
|
|
Flyway 管理的默认 schema,名称区分大小写。未指定但配置了 schemas 时,使用列表第一项;两者都未指定时,使用数据库连接的默认 schema。 Consequences:
Environment variable: 详细说明 |
字符串 |
|
|
Flyway 连接数据库使用的 JDBC URL。未指定时回退到数据源 URL。 Environment variable: 详细说明 |
字符串 |
|
|
Flyway 连接数据库使用的用户名。未单独配置 JDBC URL 时,若此值未指定,则回退到数据源用户名。 Environment variable: 详细说明 |
字符串 |
|
|
Flyway 连接数据库使用的密码。未单独配置 JDBC URL 时,若此值未指定,则回退到数据源密码。 Environment variable: 详细说明 |
字符串 |
|
|
Flyway 管理的 schema 列表,逗号分隔且区分大小写。迁移时第一项自动作为默认 schema,也用于存放 schema 历史表。 Environment variable: 详细说明 |
字符串列表 |
|
|
Flyway 的 schema 历史表名称。默认单 schema 模式下,它位于数据源连接的默认 schema。设置 flyway.schemas 后进入多 schema 模式,历史表位于列表第一项。 Environment variable: 详细说明 |
字符串 |
|
|
版本化 SQL 迁移的文件名前缀。文件名结构为 prefixVERSIONseparatorDESCRIPTIONsuffix,默认示例为 V1.1__My_description.sql。 Environment variable: 详细说明 |
字符串 |
|
|
可重复 SQL 迁移的文件名前缀。文件名结构为 prefixSeparatorDESCRIPTIONsuffix,默认示例为 R__My_description.sql。 Environment variable: 详细说明 |
字符串 |
|
|
true 表示应用启动时自动执行 Flyway clean,否则不执行。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示阻止 Flyway clean 操作,否则允许。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示应用启动时自动执行 Flyway,否则不执行。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示应用启动时执行 Flyway repair,否则不执行。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示应用启动时执行 Flyway validate,否则不执行。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示启动校验失败时自动执行 Flyway clean,否则不执行。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示迁移前执行 Flyway baseline。当前 schema 已有 flyway_schema_history 表,或当前 schema 为空时,忽略此标志。它不会自动调用 migrate。原文接着要求启用 baselineAtStart 或编程调用 flyway.migrate();执行迁移仍应以 migrate-at-start 或显式 migrate() 为准。 Environment variable: 详细说明 |
布尔值 |
|
|
true 表示应用启动时自动执行 Flyway baseline。当前 schema 已有 flyway_schema_history 表时忽略;即便 schema 为空也会生效。 Environment variable: 详细说明 |
布尔值 |
|
|
初始基线版本。 Environment variable: 详细说明 |
字符串 |
|
|
执行 baseline 时,为现有 schema 设置的描述。 Environment variable: 详细说明 |
字符串 |
|
|
执行迁移时是否自动调用 validate。 Environment variable: 详细说明 |
布尔值 |
|
|
允许不按顺序运行迁移。 Environment variable: 详细说明 |
布尔值 |
|
|
读取历史表时是否忽略缺失迁移。为 true 时,历史表中存在但配置位置中缺失的旧版本迁移会被忽略,并记录警告;为 false(默认)时,校验失败。 Environment variable: 详细说明 |
布尔值 |
|
|
读取历史表时是否忽略未来版本迁移。为 true 时,历史表中存在但配置位置中缺失的新版本迁移会被忽略,并记录警告;为 false(默认)时,校验失败。 Environment variable: 详细说明 |
布尔值 |
|
|
设置 SQL 迁移脚本中要替换的占位符。 Environment variable: 详细说明 |
Map<String,String> |
|
|
Flyway 是否尝试创建 schemas 属性中指定的 schema。 Environment variable: 详细说明 |
布尔值 |
|
|
所有占位符的前缀,默认为 ${。 Environment variable: 详细说明 |
字符串 |
|
|
所有占位符的后缀,默认为 }。 Environment variable: 详细说明 |
字符串 |
|
|
新数据库连接打开后,立即运行以初始化连接的 SQL 语句。 Environment variable: 详细说明 |
字符串 |
|
|
是否校验迁移和回调脚本的命名约定。校验失败有助于发现迁移前缀大小写等错误。 Environment variable: 详细说明 |
布尔值 |
|
|
按指定模式列表,在 validate 和 repair 中忽略迁移,详细规则见 ignoreMigrationPatterns 文档。设置此配置后,ignoreFutureMigrations 和 ignoreMissingMigrations 被忽略。模式之间用逗号分隔。 https://flywaydb.org/documentation/configuration/parameters/ignoreMigrationPatterns Environment variable: 详细说明 |
字符串列表 |
|
About the Duration format
时长值使用标准 java.time.Duration 格式。详情见 Duration#parse() Java API 文档。 Duration#parse() Java API documentation 也可以使用以数字开头的简化格式:
其他情况下,简化格式会转换为 java.time.Duration 格式再解析:
|
使用 Flyway 开发 相关文档
下面是 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
# Run Flyway migrations automatically
quarkus.flyway.migrate-at-start=true
# More Flyway configuration options
# quarkus.flyway.baseline-on-migrate=true
# quarkus.flyway.baseline-version=1.0.0
# quarkus.flyway.baseline-description=Initial version
# quarkus.flyway.connect-retries=10
# quarkus.flyway.schemas=TEST_SCHEMA
# quarkus.flyway.table=flyway_quarkus_history
# quarkus.flyway.locations=db/location1,db/location2
# quarkus.flyway.sql-migration-prefix=X
# quarkus.flyway.repeatable-sql-migration-prefix=K
按照 Flyway 命名约定,在默认目录中添加 SQL 迁移:src/main/resources/db/migration/V1.0.0__Quarkus.sql。
CREATE TABLE quarkus
(
id INT,
name VARCHAR(20)
);
INSERT INTO quarkus(id, name)
VALUES (1, 'QUARKED');
现在启动应用,Quarkus 会根据配置运行 Flyway 的 migrate 方法。
| 像上例一样设置 quarkus.flyway.migrate-at-start=true 时,Quarkus 会在应用启动过程中执行 Flyway 迁移。 application startup |
@ApplicationScoped
public class MigrationService {
// You can Inject the object if you want to use it manually
@Inject
Flyway flyway; (1)
public void checkMigration() {
// This will print 1.0.0
System.out.println(flyway.info().current().getVersion().toString());
}
}
| 1 | 需要直接使用时,注入 Flyway 对象。 |
| 开发模式下,任何现有迁移脚本修改后,Quarkus 都会自动重启应用。开发和测试新迁移脚本时,若要利用此机制,应设置 %dev.quarkus.flyway.clean-at-start=true,让 Flyway 真正重新运行修改后的迁移。 |
修复 Flyway schema 历史表 相关文档
多种情况可能需要修复 Flyway schema 历史表,例如在不支持事务性 DDL 的数据库中迁移失败。
此时可使用 Flyway repair。Quarkus 中可以设置 quarkus.flyway.repair-at-start=true,在迁移前自动执行;也可以注入 Flyway 对象,手动调用 Flyway#repair()。 Flyway repair command
多个数据源 相关文档
Flyway 可以配置多个数据源,其属性前缀与命名数据源完全一致,例如:
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
# Flyway configuration for the default datasource
quarkus.flyway.schemas=DEFAULT_TEST_SCHEMA
quarkus.flyway.locations=db/default/location1,db/default/location2
quarkus.flyway.migrate-at-start=true
# Flyway configuration for the "users" datasource
quarkus.flyway.users.schemas=USERS_TEST_SCHEMA
quarkus.flyway.users.locations=db/users/location1,db/users/location2
quarkus.flyway.users.migrate-at-start=true
# Flyway configuration for the "inventory" datasource
quarkus.flyway.inventory.schemas=INVENTORY_TEST_SCHEMA
quarkus.flyway.inventory.locations=db/inventory/location1,db/inventory/location2
quarkus.flyway.inventory.migrate-at-start=true
注意键中多出的名称部分。语法为 quarkus.flyway.[optional name.][datasource property]。
| 没有额外配置时,每个数据源都按默认设置配置 Flyway。 |
定制 Flyway 相关文档
如果需要 Quarkus 已提供选项之外的配置,可以使用 io.quarkus.flyway.FlywayConfigurationCustomizer。
要定制默认数据源的 Flyway,只需添加如下 bean:
@Singleton
public static class MyCustomizer implements FlywayConfigurationCustomizer {
@Override
public void customize(FluentConfiguration configuration) {
// do something with configuration
}
}
使用命名数据源时,可以通过 @FlywayDataSource 指定定制器作用的数据源。例如多个数据源中有一个名为 users,并且只需要定制它的 Flyway,可以使用以下代码:
@Singleton
@FlywayDataSource("users")
public static class UsersCustomizer implements FlywayConfigurationCustomizer {
@Override
public void customize(FluentConfiguration configuration) {
// do something with configuration
}
}
使用 Flyway 对象 相关文档
需要直接使用 Flyway 对象时,可以这样注入:
@ApplicationScoped
public class MigrationService {
// You can Inject the object if you want to use it manually
@Inject
Flyway flyway; (1)
@Inject
@FlywayDataSource("inventory") (2)
Flyway flywayForInventory;
@Inject
@Named("flyway_users") (3)
Flyway flywayForUsers;
public void checkMigration() {
// Use the flyway instance manually
flyway.clean(); (4)
flyway.migrate();
// This will print 1.0.0
System.out.println(flyway.info().current().getVersion().toString());
}
}
| 1 | 注入 Flyway 对象以直接使用。 |
| 2 | 使用 Quarkus 的 FlywayDataSource 限定符,注入命名数据源的 Flyway。 |
| 3 | 注入命名数据源的 Flyway。 |
| 4 | 直接使用 Flyway 实例。 |
Flyway 与 Hibernate ORM 相关文档
Flyway 配合 Hibernate ORM 使用时,可以通过 Dev UI 生成初始 schema 创建脚本。
更多信息见 Hibernate ORM 指南。 Hibernate ORM guide
Flyway 与响应式数据源 相关文档
Flyway 内部依赖 JDBC 数据源,而响应式场景使用响应式 SQL 客户端,可以直接使用,也可以通过 Hibernate Reactive 使用。Quarkus 允许同一个配置的数据源同时通过响应式客户端和 JDBC 提供访问,因此二者可以共存。 reactive SQL clients Hibernate Reactive a single configured datasource can be made available both through reactive clients and JDBC
Kubernetes 上的 Flyway 相关文档
有时不希望每次应用启动都执行 Flyway 初始化,例如部署到
Kubernetes 时,不应该让每个副本都重复执行 Flyway。更合适的做法是执行一次初始化,然后启动不再运行 Flyway 的应用。为此,生成的 Kubernetes 清单会包含用于 Flyway 初始化的 Job。Job 完成初始化后,实际 Pod 才启动。
禁用 相关文档
该功能默认启用,可以通过以下设置全局禁用:
quarkus.kubernetes.init-task-defaults.enabled=false
OpenShift 中使用:
quarkus.openshift.init-task-defaults.enabled=false
自定义等待 Job 完成的镜像 相关文档
默认等待镜像为 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
注意:这里的“全局”指所有支持初始化任务外置的扩展。
Flyway 已知问题 相关文档
Oracle:Dev Services 中的多个 schema 相关文档
Oracle 使用多个 schema 时,可通过 quarkus.flyway.schemas 指定需要管理的 schema。但数据库操作以 quarkus 用户执行,因此必须为执行迁移的 quarkus 用户授予 DBA 权限,或者在 Dev Service 启动前完成必要的 DDL;后者通过 quarkus.datasource.devservices.init-privileged-script-path 配置。
授予用户 DBA 权限 相关文档
-
在应用的 src/main/resources 中创建 001-devservice-init.sql,名称用于控制顺序,也可以使用其他名称,内容如下:
ALTER SESSION SET CONTAINER=quarkus;
GRANT DBA TO quarkus;
-
在 application.properties 中添加以下配置:
quarkus.datasource.devservices.init-privileged-script-path=001-devservice-init.sql











暂无评论内容