Micronaut Flyway

Integration between Micronaut and Flyway

Version: 1.1.0

1 Introduction

To use the Micronaut’s integration with Flyway you must have the micronaut-flyway dependency on your classpath:

compile 'io.micronaut.configuration:micronaut-flyway'
<dependency>
    <groupId>io.micronaut.configuration</groupId>
    <artifactId>micronaut-flyway</artifactId>
</dependency>

2 What's New

This section will outline any breaking changes between major or milestone releases as well as detail any new features that have been added.

1.1.0

  • Added support for GORM.

  • Upgrade to Micronaut 1.1.3.

1.0.0

  • Underlying implementation has been changed to run the migrations as soon as possible. If you are not extending or overriding the API, there are no functional changes to note.

1.0.0.RC3

  • Upgrade to Micronaut 1.0.4.

  • Upgrade to Flyway 5.2.4.

1.0.0.RC2

  • Add configuration property to clean the schema before running the migrations.

  • Fire events after clean the schema and after run the migrations.

1.0.0.RC1

  • First public release.

3 Configuration

3.1 JPA/Hibernate

You can define Flyway configuration for each datasource. The following example demonstrates using it:

src/main/resources/application.yml
datasources:
  default: (3)
    url: 'jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE'
    username: 'sa'
    password: ''
    driverClassName: 'org.h2.Driver'
jpa:
  default: (3)
    packages-to-scan:
      - 'example.micronaut'
    properties:
      hibernate:
        hbm2ddl:
          auto: none (1)
        show_sql: true
flyway:
    datasources: (2)
        default: (3)
            locations: classpath:databasemigrations (4)
1 Disable schema DDL creation.
2 Define flyway configuration under flyway.datasources key.
3 Configure flyway configuration for default data source.
4 The migrations directory is src/main/resources/databsemigrations.

In that directory you need to include all your migrations, for example:

resources/databasemigrations/V1__create-books-schema.sql
create table books (
  id int not null primary key,
  name varchar(255) not null,
  constraint id unique (id),
  constraint name unique (name),
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Starting with Micronaut 1.1.3 it is not necessary to define the jpa configuration if you only want to run the migrations but not actually use JPA.

3.2 GORM

There is also support for running Flyway migrations when using GORM.

1.- Add the dependency:

compile 'io.micronaut.configuration:micronaut-hibernate-gorm'
<dependency>
    <groupId>io.micronaut.configuration</groupId>
    <artifactId>micronaut-hibernate-gorm</artifactId>
</dependency>

2.- You also need at least one class annotated with @grails.gorm.annotation.Entity to trigger the migrations.

src/main/groovy/example/Book.groovy
import grails.gorm.annotation.Entity

@Entity
class Book {
    String name
}

3.- Then it is necessary to configure GORM datasource:

src/main/resources/application.yml
dataSource: (1)
  pooled: true
  jmxExport: true
  dbCreate: none (2)
  url: 'jdbc:h2:mem:GORMDb'
  driverClassName: org.h2.Driver
  username: sa
  password: ''

flyway:
  datasources: (3)
    default: (4)
      locations: classpath:databasemigrations (5)
1 Definition of the first data source in GORM. The name it’s default and it can’t be changed.
2 Disable schema DDL creation.
3 Define flyway configuration under flyway.datasources key.
4 Define flyway configuration for the default datasource.
5 The migrations directory is src/main/resources/databsemigrations.

Multiple Data sources

It is also possible to configure Flyway migrations with multiple data sources when using GORM:

src/main/resources/application.yml
dataSource: (1)
  pooled: true
  jmxExport: true
  dbCreate: none
  url: 'jdbc:h2:mem:flywayGORMDb'
  driverClassName: org.h2.Driver
  username: sa
  password: ''

dataSources:
  books: (2)
    pooled: true
    jmxExport: true
    dbCreate: none
    url: 'jdbc:h2:mem:flywayBooksDb'
    driverClassName: org.h2.Driver
    username: sa
    password: ''

flyway:
  datasources:
    default: (3)
      locations: classpath:databasemigrations
    books: (4)
      locations: classpath:databasemigrations
1 Definition of the first data source in GORM. The name it’s default and it can’t be changed.
2 Name of the additional data source.
3 Define flyway configuration for the default datasource.
4 Define flyway configuration for the books datasource.
For more information about how to configure GORM, take a look at the documentation.

3.3 Additional configuration

There are several options available for configuration:

🔗
Table 1. Configuration Properties for FlywayConfigurationProperties
Property Type Description

flyway.datasources.*.configuration

org.flywaydb.core.api.configuration.Configuration

flyway.datasources.*.dry-run-output

java.io.OutputStream

flyway.datasources.*.error-overrides

java.lang.String[]

flyway.datasources.*.group

boolean

flyway.datasources.*.installed-by

java.lang.String

flyway.datasources.*.mixed

boolean

flyway.datasources.*.ignore-missing-migrations

boolean

flyway.datasources.*.ignore-ignored-migrations

boolean

flyway.datasources.*.ignore-pending-migrations

boolean

flyway.datasources.*.ignore-future-migrations

boolean

flyway.datasources.*.validate-on-migrate

boolean

flyway.datasources.*.clean-on-validation-error

boolean

flyway.datasources.*.clean-disabled

boolean

flyway.datasources.*.encoding

java.lang.String

flyway.datasources.*.schemas

java.lang.String[]

flyway.datasources.*.table

java.lang.String

flyway.datasources.*.target

org.flywaydb.core.api.MigrationVersion

flyway.datasources.*.placeholder-replacement

boolean

flyway.datasources.*.placeholders

java.util.Map

flyway.datasources.*.placeholder-prefix

java.lang.String

flyway.datasources.*.placeholder-suffix

java.lang.String

flyway.datasources.*.sql-migration-prefix

java.lang.String

flyway.datasources.*.undo-sql-migration-prefix

java.lang.String

flyway.datasources.*.repeatable-sql-migration-prefix

java.lang.String

flyway.datasources.*.sql-migration-separator

java.lang.String

flyway.datasources.*.sql-migration-suffixes

java.lang.String[]

flyway.datasources.*.data-source

javax.sql.DataSource

flyway.datasources.*.connect-retries

int

flyway.datasources.*.init-sql

java.lang.String

flyway.datasources.*.baseline-version

org.flywaydb.core.api.MigrationVersion

flyway.datasources.*.baseline-description

java.lang.String

flyway.datasources.*.baseline-on-migrate

boolean

flyway.datasources.*.out-of-order

boolean

flyway.datasources.*.callbacks

org.flywaydb.core.api.callback.Callback[]

flyway.datasources.*.skip-default-callbacks

boolean

flyway.datasources.*.resolvers

org.flywaydb.core.api.resolver.MigrationResolver[]

flyway.datasources.*.skip-default-resolvers

boolean

flyway.datasources.*.stream

boolean

flyway.datasources.*.batch

boolean

flyway.datasources.*.oracle-sqlplus

boolean

flyway.datasources.*.license-key

java.lang.String

flyway.datasources.*.enabled

boolean

Set whether this flyway configuration is enabled. Default value (true).

flyway.datasources.*.async

boolean

Whether flyway migrations should run asynchronously.

flyway.datasources.*.clean-schema

boolean

Set whether Flyway will clean the schema before running the migrations. Default value (false).

flyway.datasources.*.url

java.lang.String

The JDBC url of the database to migrate

flyway.datasources.*.user

java.lang.String

The user of the database to migrate

flyway.datasources.*.password

java.lang.String

The password of the database to migrate

flyway.datasources.*.username

java.lang.String

The username of the database to migrate

flyway.datasources.*.locations

java.lang.String[]

The locations for the migrations

By default Micronaut will configure Flyway to use the datasources defined under datasources configuration key. If you want to use a different datasource you need to define the properties flyway.datasources.*.url, flyway.datasources.*.user and flyway.datasources.*.password.

4 Events

Micronaut fires two different events when:

5 Endpoint

This configuration also provides a built-in endpoint to expose all the applied migrations in /flyway.

To enable the endpoint add the following to the configuration:

resources/application.yml
endpoints:
    flyway:
        enabled: true (1)
        sensitive: false (2)
1 /flyway endpoint is enabled (this is the default).
2 /flyway endpoint is open for unauthenticated access.
$ curl http://localhost:8080/flyway

[{
    "name": "default",
    "migrations": [{
        "checksum": 1952043475,
        "installedOn": "2018-11-12T11:32:52.000+0000",
        "executionTime": 96,
        "installedRank": 1,
        "version": {
            "version": "1"
        },
        "description": "init",
        "installedBy": "root",
        "state": "SUCCESS",
        "type": "SQL",
        "script": "V1__init.sql"
    }, {
        "checksum": -1926058189,
        "installedOn": "2018-11-12T11:32:52.000+0000",
        "executionTime": 10,
        "installedRank": 2,
        "version": {
            "version": "2"
        },
        "description": "testdata",
        "installedBy": "root",
        "state": "SUCCESS",
        "type": "SQL",
        "script": "V2__testdata.sql"
    }]
}]
See the section on Built-in endpoints in the user guide for more information.