使用Flyway
Flyway 是一个流行的数据库迁移工具，通常用于JVM环境。
本指南将会介绍Quarkus为使用Flyway提供了哪些一流的支持。
建立对Flyway的支持
参照 [用flyway开发] ，要开始在项目中使用Flyway，只需要：
-
像通常使用Flyway那样，将你的迁移文件添加到
src/main/resources/db/migration文件夹中。 -
激活
migrate-at-start选项来自动迁移表，或者添加Flyway对象，然后像通常那样运行迁移。
在build文件中添加以下依赖项。
-
Flyway扩展
-
JDBC驱动扩展 (
quarkus-jdbc-postgresql,quarkus-jdbc-h2,quarkus-jdbc-mariadb, …) -
unless you’re using in-memory or file databases (such as H2 or SQLite), you need to add a flyway module dependency corresponding to the database you’re using. (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>
<!-- Derby specific dependencies -->
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-derby</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")
// Flyway Derby specific dependencies
implementation("org.flywaydb:flyway-database-derby")
// 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管理数据库模型。另外，你可以根据以下属性来设置Flyway。
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
类型 |
默认 |
|---|---|---|
Whether Flyway is enabled during the build. If Flyway is disabled, the Flyway beans won’t be created and Flyway won’t be usable. Environment variable: Show more |
boolean |
|
类型 |
默认 |
|
Comma-separated list of locations to scan recursively for migrations. The location type is determined by its prefix. Unprefixed locations or locations starting with classpath: point to a package on the classpath and may contain both SQL and Java-based migrations. Locations starting with filesystem: point to a directory on the filesystem, may only contain SQL migrations and are only scanned recursively down non-hidden directories. Environment variable: Show more |
list of string |
|
Comma-separated list of fully qualified class names of Callback implementations to use to hook into the Flyway lifecycle. The Environment variable: Show more |
list of string |
|
Flag to activate/deactivate Flyway for a specific datasource at runtime. Environment variable: Show more |
boolean |
|
The maximum number of retries when attempting to connect to the database. After each failed attempt, Flyway will wait up to the configured Environment variable: Show more |
int |
|
The maximum time between retries when attempting to connect to the database. This will cap the interval between connect retries to the value provided. Environment variable: Show more |
|
|
Sets the default schema managed by Flyway. This schema name is case-sensitive. If not specified, but schemas is, Flyway uses the first schema in that list. If that is also not specified, Flyway uses the default schema for the database connection. Consequences:
Environment variable: Show more |
string |
|
The JDBC URL that Flyway uses to connect to the database. Falls back to the datasource URL if not specified. Environment variable: Show more |
string |
|
The username that Flyway uses to connect to the database. If no specific JDBC URL is configured, falls back to the datasource username if not specified. Environment variable: Show more |
string |
|
The password that Flyway uses to connect to the database. If no specific JDBC URL is configured, falls back to the datasource password if not specified. Environment variable: Show more |
string |
|
Comma-separated case-sensitive list of schemas managed by Flyway. The first schema in the list will be automatically set as the default one during the migration. It will also be the one containing the schema history table. Environment variable: Show more |
list of string |
|
The name of Flyway’s schema history table. By default (single-schema mode), the schema history table is placed in the default schema for the connection provided by the datasource. When the flyway.schemas property is set (multi-schema mode), the schema history table is placed in the first schema of the list. Environment variable: Show more |
string |
|
The file name prefix for versioned SQL migrations. Versioned SQL migrations have the following file name structure: prefixVERSIONseparatorDESCRIPTIONsuffix , which using the defaults translates to V1.1__My_description.sql Environment variable: Show more |
string |
|
The file name prefix for repeatable SQL migrations. Repeatable SQL migrations have the following file name structure: prefixSeparatorDESCRIPTIONsuffix , which using the defaults translates to R__My_description.sql Environment variable: Show more |
string |
|
true to execute Flyway clean command automatically when the application starts, false otherwise. Environment variable: Show more |
boolean |
|
true to prevent Flyway clean operations, false otherwise. Environment variable: Show more |
boolean |
|
true to execute Flyway automatically when the application starts, false otherwise. Environment variable: Show more |
boolean |
|
true to execute a Flyway repair command when the application starts, false otherwise. Environment variable: Show more |
boolean |
|
true to execute a Flyway validate command when the application starts, false otherwise. Environment variable: Show more |
boolean |
|
true to automatically execute a Flyway clean command when a validation error occurs at start, false otherwise. Environment variable: Show more |
boolean |
|
true to execute Flyway baseline before migrations This flag is ignored if the flyway_schema_history table exists in the current schema or if the current schema is empty. Note that this will not automatically call migrate, you must either enable baselineAtStart or programmatically call flyway.migrate(). Environment variable: Show more |
boolean |
|
true to execute Flyway baseline automatically when the application starts. This flag is ignored if the flyway_schema_history table exists in the current schema. This will work even if the current schema is empty. Environment variable: Show more |
boolean |
|
The initial baseline version. Environment variable: Show more |
string |
|
The description to tag an existing schema with when executing baseline. Environment variable: Show more |
string |
|
Whether to automatically call validate when performing a migration. Environment variable: Show more |
boolean |
|
Allows migrations to be run "out of order". Environment variable: Show more |
boolean |
|
Ignore missing migrations when reading the history table. When set to true migrations from older versions present in the history table but absent in the configured locations will be ignored (and logged as a warning), when false (the default) the validation step will fail. Environment variable: Show more |
boolean |
|
Ignore future migrations when reading the history table. When set to true migrations from newer versions present in the history table but absent in the configured locations will be ignored (and logged as a warning), when false (the default) the validation step will fail. Environment variable: Show more |
boolean |
|
Sets the placeholders to replace in SQL migration scripts. Environment variable: Show more |
Map<String,String> |
|
Whether Flyway should attempt to create the schemas specified in the schemas property Environment variable: Show more |
boolean |
|
Prefix of every placeholder (default: ${ ) Environment variable: Show more |
string |
|
Suffix of every placeholder (default: } ) Environment variable: Show more |
string |
|
The SQL statements to run to initialize a new database connection immediately after opening it. Environment variable: Show more |
string |
|
Whether to validate migrations and callbacks whose scripts do not obey the correct naming convention. A failure can be useful to check that errors such as case sensitivity in migration prefixes have been corrected. Environment variable: Show more |
boolean |
|
Ignore migrations during validate and repair according to a given list of patterns (see https://flywaydb.org/documentation/configuration/parameters/ignoreMigrationPatterns for more information). When this configuration is set, the ignoreFutureMigrations and ignoreMissingMigrations settings are ignored. Patterns are comma separated. Environment variable: Show more |
list of string |
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|
用Flyway开发
The following is an example for the application.properties file:
# 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的迁移方法。
如上例所述，通过设置 quarkus.flyway.migrate-at-start=true Quarkus将在 应用启动 的时候通过Flyway进行迁移。
|
@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会运行被修改的迁移脚本。
|
Repairing the Flyway schema history table
There are different scenarios which may require repairing the Flyway schema history table. One such scenario is when a migration fails in a database which doesn’t support transactional DDL statements.
In such situations the Flyway repair command comes in handy. In Quarkus this can either be executed automatically before the migration by setting quarkus.flyway.repair-at-start=true or manually by injecting the Flyway object and calling Flyway#repair().
Multiple datasources
Flyway can be configured for multiple datasources. The Flyway properties are prefixed exactly the same way as the named datasources, for example:
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对每个数据源都是使用默认设置。 |
Customizing Flyway
In cases where Flyway needs to be configured in addition to the configuration options that Quarkus provides, the io.quarkus.flyway.FlywayConfigurationCustomizer class comes in handy.
To customize Flyway for the default datasource, simply add a bean like so:
@Singleton
public static class MyCustomizer implements FlywayConfigurationCustomizer {
@Override
public void customize(FluentConfiguration configuration) {
// do something with configuration
}
}When named datasources are used, the @FlywayDataSource annotation can be used to specify the datasource to which the customizer applies.
For example, if there are multiple datasources one of which is called users and customization of Flyway is needed for only that datasource,
then the following code can be used:
@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来生成初始表创建脚本。
你可以在Hibernate ORM guide找到更多相关信息。
Flyway and Reactive datasources
Flyway internally relies on a JDBC datasource, whereas reactive use cases will rely on reactive SQL clients, either directly or through Hibernate Reactive. This is not a problem in Quarkus, because a single configured datasource can be made available both through reactive clients and JDBC.
To use Flyway on a datasource you otherwise access reactively,
simply make sure to configure that datasource
both as JDBC
and reactive.
This involves in particular adding dependencies to Quarkus extensions
for both the JDBC driver and the reactive client,
for instance quarkus-jdbc-postgresql and quarkus-reactive-pg-client.
Flyway on Kubernetes
Sometimes, it’s helpful not to execute Flyway initialization on each application startup. One such example is when deploying
on Kubernetes, where it doesn’t make sense to execute Flyway on every single replica. Instead it’s desirable to execute it
once and then start the actual application without Flyway. To support this use case, when generating manifests for Kubernetes
the generated manifests contain a Kubernetes initialization Job for Flyway.
The Job performs initialization and the actual Pod, will starts once the Job is successfully completed.
Disabling
The feature is enabled by default and can be globally disabled, using:
quarkus.kubernetes.init-task-defaults.enabled=falseor on OpenShift:
quarkus.openshift.init-task-defaults.enabled=falseUsing a custom image that controls waiting for the Job
To change the wait-for image which by default is groundnuty/k8s-wait-for:no-root-v1.7 you can use:
quarkus.kubernetes.init-task-defaults.wait-for-container.image=my/wait-for-image:1.0or on OpenShift:
quarkus.openshift.init-task-defaults.wait-for-container.image=my/wait-for-image:1.0Note: In this context globally means for all extensions that support init task externalization.
