The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

使用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 , …​)

  • MariaDB/MySQL的支持现在在一个单独的依赖中,MariaDB/MySQL的用户从现在开始需要添加 flyway-mysql 的依赖。

  • Microsoft SQL Server的支持现在在一个单独的依赖中,Microsoft SQL Server的用户从现在开始需要添加 flyway-sqlserver 的依赖。

pom.xml
<!-- Flyway specific dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-flyway</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>

<!-- JDBC driver dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
build.gradle
// Flyway specific dependencies
implementation("io.quarkus:quarkus-flyway")
// Flyway SQL Server specific dependencies
implementation("org.flywaydb:flyway-sqlserver")
// Flyway MariaDB/MySQL specific dependencies
implementation("org.flywaydb:flyway-mysql")
// JDBC driver dependencies
implementation("io.quarkus:quarkus-jdbc-postgresql")

Flyway支持依赖于Quarkus的数据源配置。它可以为默认的数据源以及每个 命名的数据源 进行定制。首先,你需要将数据源配置添加到 application.properties 文件中,以便让Flyway管理数据库模型。另外,你可以根据以下属性来设置Flyway。

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

类型

默认

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: QUARKUS_FLYWAY_LOCATIONS

list of string

db/migration

Comma-separated list of fully qualified class names of Callback implementations to use to hook into the Flyway lifecycle. The org.flywaydb.core.api.callback.Callback subclass must have a no-args constructor and must not be abstract. These classes must also not have any fields that hold state (unless that state is initialized in the constructor).

Environment variable: QUARKUS_FLYWAY_CALLBACKS

list of string

The maximum number of retries when attempting to connect to the database. After each failed attempt, Flyway will wait 1 second before attempting to connect again, up to the maximum number of times specified by connectRetries.

Environment variable: QUARKUS_FLYWAY_CONNECT_RETRIES

int

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: - This schema will be the one containing the schema history table. - This schema will be the default for the database connection (provided the database supports this concept).

Environment variable: QUARKUS_FLYWAY_DEFAULT_SCHEMA

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: QUARKUS_FLYWAY_SCHEMAS

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: QUARKUS_FLYWAY_TABLE

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: QUARKUS_FLYWAY_SQL_MIGRATION_PREFIX

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: QUARKUS_FLYWAY_REPEATABLE_SQL_MIGRATION_PREFIX

string

true to execute Flyway clean command automatically when the application starts, false otherwise.

Environment variable: QUARKUS_FLYWAY_CLEAN_AT_START

boolean

false

true to prevent Flyway clean operations, false otherwise.

Environment variable: QUARKUS_FLYWAY_CLEAN_DISABLED

boolean

false

true to automatically call clean when a validation error occurs, false otherwise.

Environment variable: QUARKUS_FLYWAY_CLEAN_ON_VALIDATION_ERROR

boolean

false

true to execute Flyway automatically when the application starts, false otherwise.

Environment variable: QUARKUS_FLYWAY_MIGRATE_AT_START

boolean

false

Enable the creation of the history table if it does not exist already.

Environment variable: QUARKUS_FLYWAY_BASELINE_ON_MIGRATE

boolean

false

The initial baseline version.

Environment variable: QUARKUS_FLYWAY_BASELINE_VERSION

string

The description to tag an existing schema with when executing baseline.

Environment variable: QUARKUS_FLYWAY_BASELINE_DESCRIPTION

string

Whether to automatically call validate when performing a migration.

Environment variable: QUARKUS_FLYWAY_VALIDATE_ON_MIGRATE

boolean

false

Allows migrations to be run "out of order".

Environment variable: QUARKUS_FLYWAY_OUT_OF_ORDER

boolean

false

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: QUARKUS_FLYWAY_IGNORE_MISSING_MIGRATIONS

boolean

false

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: QUARKUS_FLYWAY_IGNORE_FUTURE_MIGRATIONS

boolean

false

Whether Flyway should attempt to create the schemas specified in the schemas property

Environment variable: QUARKUS_FLYWAY_CREATE_SCHEMAS

boolean

true

Prefix of every placeholder (default: ${ )

Environment variable: QUARKUS_FLYWAY_PLACEHOLDER_PREFIX

string

Suffix of every placeholder (default: } )

Environment variable: QUARKUS_FLYWAY_PLACEHOLDER_SUFFIX

string

The SQL statements to run to initialize a new database connection immediately after opening it.

Environment variable: QUARKUS_FLYWAY_INIT_SQL

string

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__LOCATIONS

list of string

db/migration

Comma-separated list of fully qualified class names of Callback implementations to use to hook into the Flyway lifecycle. The org.flywaydb.core.api.callback.Callback subclass must have a no-args constructor and must not be abstract. These classes must also not have any fields that hold state (unless that state is initialized in the constructor).

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__CALLBACKS

list of string

Sets the placeholders to replace in SQL migration scripts.

Environment variable: QUARKUS_FLYWAY_PLACEHOLDERS

Map<String,String>

The maximum number of retries when attempting to connect to the database. After each failed attempt, Flyway will wait 1 second before attempting to connect again, up to the maximum number of times specified by connectRetries.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__CONNECT_RETRIES

int

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: - This schema will be the one containing the schema history table. - This schema will be the default for the database connection (provided the database supports this concept).

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__DEFAULT_SCHEMA

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__SCHEMAS

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__TABLE

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__SQL_MIGRATION_PREFIX

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__REPEATABLE_SQL_MIGRATION_PREFIX

string

true to execute Flyway clean command automatically when the application starts, false otherwise.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__CLEAN_AT_START

boolean

false

true to prevent Flyway clean operations, false otherwise.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__CLEAN_DISABLED

boolean

false

true to automatically call clean when a validation error occurs, false otherwise.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__CLEAN_ON_VALIDATION_ERROR

boolean

false

true to execute Flyway automatically when the application starts, false otherwise.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__MIGRATE_AT_START

boolean

false

Enable the creation of the history table if it does not exist already.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__BASELINE_ON_MIGRATE

boolean

false

The initial baseline version.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__BASELINE_VERSION

string

The description to tag an existing schema with when executing baseline.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__BASELINE_DESCRIPTION

string

Whether to automatically call validate when performing a migration.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__VALIDATE_ON_MIGRATE

boolean

false

Allows migrations to be run "out of order".

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__OUT_OF_ORDER

boolean

false

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__IGNORE_MISSING_MIGRATIONS

boolean

false

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: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__IGNORE_FUTURE_MIGRATIONS

boolean

false

Sets the placeholders to replace in SQL migration scripts.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__PLACEHOLDERS

Map<String,String>

Whether Flyway should attempt to create the schemas specified in the schemas property

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__CREATE_SCHEMAS

boolean

true

Prefix of every placeholder (default: ${ )

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__PLACEHOLDER_PREFIX

string

Suffix of every placeholder (default: } )

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__PLACEHOLDER_SUFFIX

string

The SQL statements to run to initialize a new database connection immediately after opening it.

Environment variable: QUARKUS_FLYWAY__NAMED_DATA_SOURCES__INIT_SQL

string

用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会运行被修改的迁移脚本。

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对每个数据源都是使用默认设置。

使用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找到更多相关信息。