Quarkus - Using Flyway

Flyway is a popular database migration tool that is commonly used in JVM environments.

Quarkus provides first class support for using Flyway as will be explained in this guide.

Setting up support for Flyway

To start using Flyway with your project, you just need to:

  • add your migrations to the src/main/resources/db/migration folder as you usually do with Flyway

  • activate the migrate-at-start option to migrate the schema automatically or inject the Flyway object and run your migration as you normally do

In your pom.xml, add the following dependencies:

  • the Flyway extension

  • your JDBC driver extension (quarkus-jdbc-postgresql, quarkus-jdbc-h2, quarkus-jdbc-mariadb, …​)

<dependencies>
    <!-- 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>
</dependencies>

Flyway support relies on the Quarkus datasource config. It can be customized for the default datasource as well as for every named datasource. First, you need to add the datasource config to the application.properties file in order to allow Flyway to manage the schema. Also, you can customize the Flyway behaviour by using the following properties:

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

Configuration property

Type

Default

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.

list of string

db/migration

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.

int

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.

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.

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

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

string

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

boolean

false

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

boolean

false

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

boolean

false

The initial baseline version.

string

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

string

Whether to automatically call validate when performing a migration.

boolean

false

Allows migrations to be run "out of order".

boolean

false

Ignore missing migrations when reading the history table. When set to true any migration 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.

boolean

false

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

boolean

true

Prefix of every placeholder (default: ${ )

string

Suffix of every placeholder (default: } )

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.

list of string

db/migration

Sets the placeholders to replace in SQL migration scripts.

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.

int

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.

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.

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

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

string

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

boolean

false

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

boolean

false

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

boolean

false

string

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

string

Whether to automatically call validate when performing a migration.

boolean

false

Allows migrations to be run "out of order".

boolean

false

Ignore missing migrations when reading the history table. When set to true any migration 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.

boolean

false

Sets the placeholders to replace in SQL migration scripts.

Map<String,String>

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

boolean

true

Prefix of every placeholder (default: ${ )

string

Suffix of every placeholder (default: } )

string

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

# Flyway minimal config properties
quarkus.flyway.migrate-at-start=true

# Flyway optional config properties
# 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

Add a SQL migration to the default folder following the Flyway naming conventions: 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');

Now you can start your application and Quarkus will run the Flyway’s migrate method according to your config:

@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 Inject the Flyway object if you want to use it directly

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.min-size=3
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.min-size=1
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.min-size=2
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

Notice there’s an extra bit in the key. The syntax is as follows: quarkus.flyway.[optional name.][datasource property].

Without configuration, Flyway is set up for every datasource using the default settings.

Using the Flyway object

In case you are interested in using the Flyway object directly, you can inject it as follows:

If you enabled the quarkus.flyway.migrate-at-start property, by the time you use the Flyway instance, Quarkus will already have run the migrate operation
@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 Inject the Flyway object if you want to use it directly
2 Inject Flyway for named datasources using the Quarkus FlywayDataSource qualifier
3 Inject Flyway for named datasources
4 Use the Flyway instance directly