implementation("io.micronaut.flyway:micronaut-flyway")
Micronaut Flyway
Integration between Micronaut and Flyway
Version:
1 Introduction
To use the Micronaut’s integration with Flyway you must have the micronaut-flyway
dependency on your classpath:
<dependency>
<groupId>io.micronaut.flyway</groupId>
<artifactId>micronaut-flyway</artifactId>
</dependency>
You also need dependencies for the JDBC connection pool and the JDBC driver as described in Configuring a JDBC DataSource.
2 Release History
For this project, you can find a list of releases (with release notes) here:
3 Configuration
3.1 JPA/Hibernate
You can define Flyway configuration for each datasource. The following example demonstrates using it:
datasources.default.url=jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
datasources.default.username=sa
datasources.default.password=
datasources.default.driverClassName=org.h2.Driver
jpa.default.packages-to-scan[0]=example.micronaut
jpa.default.properties.hibernate.hbm2ddl.auto=none
jpa.default.properties.hibernate.show_sql=true
flyway.datasources.default.enabled=true
datasources:
default:
url: 'jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE'
username: 'sa'
password: ''
driverClassName: 'org.h2.Driver'
jpa:
default:
packages-to-scan:
- 'example.micronaut'
properties:
hibernate:
hbm2ddl:
auto: none
show_sql: true
flyway:
datasources:
default:
enabled: true
[datasources]
[datasources.default]
url="jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"
username="sa"
password=""
driverClassName="org.h2.Driver"
[jpa]
[jpa.default]
packages-to-scan=[
"example.micronaut"
]
[jpa.default.properties]
[jpa.default.properties.hibernate]
[jpa.default.properties.hibernate.hbm2ddl]
auto="none"
show_sql=true
[flyway]
[flyway.datasources]
[flyway.datasources.default]
enabled=true
datasources {
'default' {
url = "jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"
username = "sa"
password = ""
driverClassName = "org.h2.Driver"
}
}
jpa {
'default' {
packagesToScan = ["example.micronaut"]
properties {
hibernate {
hbm2ddl {
auto = "none"
}
show_sql = true
}
}
}
}
flyway {
datasources {
'default' {
enabled = true
}
}
}
{
datasources {
default {
url = "jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"
username = "sa"
password = ""
driverClassName = "org.h2.Driver"
}
}
jpa {
default {
packages-to-scan = ["example.micronaut"]
properties {
hibernate {
hbm2ddl {
auto = "none"
}
show_sql = true
}
}
}
}
flyway {
datasources {
default {
enabled = true
}
}
}
}
{
"datasources": {
"default": {
"url": "jdbc:h2:mem:flywayDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE",
"username": "sa",
"password": "",
"driverClassName": "org.h2.Driver"
}
},
"jpa": {
"default": {
"packages-to-scan": ["example.micronaut"],
"properties": {
"hibernate": {
"hbm2ddl": {
"auto": "none"
},
"show_sql": true
}
}
}
},
"flyway": {
"datasources": {
"default": {
"enabled": true
}
}
}
}
-
Disable schema DDL creation with
jpa.default.properties.hibernate.hbm2ddl.auto
set to 'none' -
Define flyway configuration under
flyway.datasources
key. -
Configure flyway configuration for
default
datasource underdatasources.default
andjpa.default
-
Enable the flyway migrations for the
default
datasource underflyway.datasources.default
You need to put the migrations in Flyway default directory src/main/resources/db/migration . If you want to
modify the default directory or add more, you need to set the property flyway.datasources.default.locations .
For example:
|
flyway.datasources.default.enabled=true
flyway.datasources.default.locations[0]=classpath:databasemigrations
flyway.datasources.default.locations[1]=classpath:other
flyway:
datasources:
default:
enabled: true
locations:
- classpath:databasemigrations
- classpath:other
[flyway]
[flyway.datasources]
[flyway.datasources.default]
enabled=true
locations=[
"classpath:databasemigrations",
"classpath:other"
]
flyway {
datasources {
'default' {
enabled = true
locations = ["classpath:databasemigrations", "classpath:other"]
}
}
}
{
flyway {
datasources {
default {
enabled = true
locations = ["classpath:databasemigrations", "classpath:other"]
}
}
}
}
{
"flyway": {
"datasources": {
"default": {
"enabled": true,
"locations": ["classpath:databasemigrations", "classpath:other"]
}
}
}
}
-
The
locations
properties configure Flyway to look for migrations in the directoriessrc/main/resources/databasemigrations
andsrc/main/resources/other
.
Now, in the migration directory you can include your migrations:
create table books(
id bigint auto_increment primary key,
name varchar(255) not null,
constraint UK_name unique (name)
);
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.
|
Run migrations manually
If you need more control to decide when the migrations are executed it is possible to configure the application like this:
flyway.enabled=true
flyway.datasources.default.enabled=false
flyway:
enabled: true
datasources:
default:
enabled: false
[flyway]
enabled=true
[flyway.datasources]
[flyway.datasources.default]
enabled=false
flyway {
enabled = true
datasources {
'default' {
enabled = false
}
}
}
{
flyway {
enabled = true
datasources {
default {
enabled = false
}
}
}
}
{
"flyway": {
"enabled": true,
"datasources": {
"default": {
"enabled": false
}
}
}
}
-
Enable Flyway and disable flyway migrations for your specific datasource
Now you can inject the FlywayMigrator
bean and call manually the method run
to execute the migrations when you want.
3.2 Additional configuration
There are several options available for configuration:
Property | Type | Description |
---|---|---|
|
boolean |
Set whether this flyway configuration is enabled. Default value (true). |
|
boolean |
Whether the flyway migrations should run asynchronously. Default value: false. |
|
boolean |
Whether Flyway will clean the schema before running the migrations. Default value (false). |
|
java.lang.String |
The JDBC url of the database to migrate. |
|
java.lang.String |
The user of the database to migrate. |
|
java.lang.String |
The username of the database to migrate |
|
java.lang.String |
The password of the database to migrate. |
|
boolean |
|
|
java.io.OutputStream |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
boolean |
|
|
java.lang.String |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
boolean |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
org.flywaydb.core.api.MigrationVersion |
|
|
org.flywaydb.core.api.MigrationPattern |
|
|
boolean |
|
|
java.util.Map |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
org.flywaydb.core.api.migration.JavaMigration |
|
|
javax.sql.DataSource |
|
|
int |
|
|
int |
|
|
java.lang.String |
|
|
org.flywaydb.core.api.MigrationVersion |
|
|
java.lang.String |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
org.flywaydb.core.api.callback.Callback |
|
|
boolean |
|
|
org.flywaydb.core.api.resolver.MigrationResolver |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
int |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
org.flywaydb.core.api.ResourceProvider |
|
|
org.flywaydb.core.api.ClassProvider |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
java.lang.String |
|
|
java.util.Map |
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 .
|
Flyway Parameters
You can setup flyway parameters. For example, you can setup PostgreSQL Transactional Lock:
flyway.datasources.default.properties.flyway.postgresql.transactional.lock=false
flyway:
datasources:
default:
properties:
flyway:
postgresql:
transactional:
lock: false
[flyway]
[flyway.datasources]
[flyway.datasources.default]
[flyway.datasources.default.properties]
[flyway.datasources.default.properties.flyway]
[flyway.datasources.default.properties.flyway.postgresql]
[flyway.datasources.default.properties.flyway.postgresql.transactional]
lock=false
flyway {
datasources {
'default' {
properties {
flyway {
postgresql {
transactional {
lock = false
}
}
}
}
}
}
}
{
flyway {
datasources {
default {
properties {
flyway {
postgresql {
transactional {
lock = false
}
}
}
}
}
}
}
}
{
"flyway": {
"datasources": {
"default": {
"properties": {
"flyway": {
"postgresql": {
"transactional": {
"lock": false
}
}
}
}
}
}
}
}
4 GraalVM support
Micronaut Flyway is compatible with GraalVM so it is possible to create native images and run the migrations during application startup.
The list of migrations to run is precomputed during native image build time and by default Micronaut looks for migrations
in the Flyway default directory src/main/resources/db/migration
. If you want to change that directory or add more directories
to look for migrations you need to add an additional parameter to native-image
command.
For example, if you have the following configuration:
flyway.datasources.default.locations[0]=classpath:databasemigrations
flyway.datasources.default.locations[1]=classpath:other
flyway:
datasources:
default:
locations:
- classpath:databasemigrations
- classpath:other
[flyway]
[flyway.datasources]
[flyway.datasources.default]
locations=[
"classpath:databasemigrations",
"classpath:other"
]
flyway {
datasources {
'default' {
locations = ["classpath:databasemigrations", "classpath:other"]
}
}
}
{
flyway {
datasources {
default {
locations = ["classpath:databasemigrations", "classpath:other"]
}
}
}
}
{
"flyway": {
"datasources": {
"default": {
"locations": ["classpath:databasemigrations", "classpath:other"]
}
}
}
}
-
The
locations
properties configure Flyway to look for migrations in the directoriessrc/main/resources/databasemigrations
andsrc/main/resources/other
.
You need to use the parameter flyway.locations
with a comma separated list of directories to look for:
native-image --no-server --no-fallback \
--class-path build/libs/micronaut-flyway-graal-*-all.jar \
-Dflyway.locations='classpath:databasemigrations,classpath:other' (1)
1 | Define the locations to look for migrations. |
See the section on GraalVM in the user guide for more information. |
5 Events
Micronaut fires two different events when:
-
The schema has been cleaned: SchemaCleanedEvent.
-
The migrations have been executed: MigrationFinishedEvent.
6 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:
endpoints.flyway.enabled=true
endpoints.flyway.sensitive=false
endpoints:
flyway:
enabled: true
sensitive: false
[endpoints]
[endpoints.flyway]
enabled=true
sensitive=false
endpoints {
flyway {
enabled = true
sensitive = false
}
}
{
endpoints {
flyway {
enabled = true
sensitive = false
}
}
}
{
"endpoints": {
"flyway": {
"enabled": true,
"sensitive": false
}
}
}
-
/flyway
endpoint is enabled (this is the default) and 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. |
7 Repository
You can find the source code of this project in this repository: