Spring

Flyway is a database migration and version control tool

  • It has Java API, command line client, plugin for Maven and Gradle

  • Supports most of relational databases such as MySQL, PostgreSQL, SQL Server and Oracle

  • Migration scripts an be written in either SQL or Java

Spring Boot can auto run database migration at the application startup with a various of mechanisms such as javax.sql.DataSource, JPA and Hibernate, Flyway and Liquibase

This tutorial will give you some highlights and an implementation example of using Flyway in Spring Boot

Add Flyway into your project

You can add Flyway into your project as a dependency on pom.xml or build.gradle file. The library versions can be found on the Maven Central Repository

If you use Flyway in a Spring Boot project, the dependency version can be omitted as Spring Boot can help you to resolve

<dependency>  
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

You may also need Spring Boot Web and Actuator to query the Flyway migration status and history via web interface

<dependency>  
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>  
<dependency>  
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Learn more about Spring Boot Actuator

Recommend to use only a single migration mechanism

Using multiple of migration mechanisms can cause confuse and hard to manage, so it's a good practice to disable others when you are using Flyway

Spring Boot, via JPA and Hibernate, can auto export schema DDL to database via your definition on @Entity classes. You can turn it off by setting validate or none (none is the default value for non-embedded databases) to the spring.jpa.hibernate.ddl-auto property

Spring Boot can auto run classpath:schema.sql and classpath:data.sql script files for your DataSource. This feature can be controlled via spring.datasource.initialization-mode property. Its value is embedded (only apply for embedded databases) by default

Flyway migration scripts

Unlike JPA and Hibernate, database migration in Flyway is not based on the definition of @Entity classes, you have to manually write the migration scripts in either SQL or Java, SQL is the most commonly use

Typically, SQL scripts are in the form V<VERSION>__<DESCRIPTION>.sql

  • <VERSION> is a dot or underscore separated version, such as '1.0' or '1_1'). <VERSION> must be unique

  • <DESCRIPTION> should be informative for you able to remember what each migration does

The following give you some example SQL scripts

By default, Spring Boot looks for them in classpath:db/migration folder, you can modify that location by setting spring.flyway.locations

│       └── resources
│           ├── db
│           │   └── migration
│           │       ├── V1.0__create_book.sql
│           │       ├── V1.1__insert_book.sql
│           │       ├── V1.2__insert_book.sql
│           │       └── V1.3__delete_book.sql
│           └── application.properties
└── pom.xml

How Flyway works

Flyway applies migration scripts to the underlying database in the order based on the version number specified in the script file naming

At each execution, only pending migrations are applied. Flyway manages this via creating (if not exists) and updating a metadata table. You can find more details about this table in the latter part of this tutorial

The migration scripts can not be changed after applied. Flyway compares checksum of each script in every execution and throws exception if there's a mismatch

Config Flyway DataSource

Spring Boot uses either annotations or external properties to connect Flyway to the underlying datasource

  • @Primary DataSource or @FlywayDataSource annotation

  • spring.datasource.[url, username, password], or spring.flyway.[url, user, password] properties

How Spring Boot runs Flyway

Spring Boot auto enable and trigger Flyway at the application startup when you include the Flyway core library into the project. In case you'd like turn it off , update this setting spring.flyway.enabled to false (true is the default value)

The application startup may be failed if there's any exception (such as the checksum mismatch error of migration scripts mentioned in the previous section) thrown by Flyway during migration

Each migration script is run within a single transaction. You can configure to run all pending migrations in a single transaction with spring.flyway.group=true (the default value is false)

Query migration status and history

You can query migration status and history in web interface with Spring Boot Actuator by enabling it in this property management.endpoints.web.exposure.include=info,health,flyway and access to {endpoints}/actuator/flyway

Apart from that, you can also query table flyway_schema_history in your database. It is created by Flyway to manage the migration status and history. The table name can be changed via setting spring.flyway.table (flyway_schema_history is the default name)

Integrate Flyway into an existing database on production

A several steps have to be executed when you integrate Flyway into a project with an existing database on production environment. You can learn more about it at here

Conclusion

In this tutorial, we learned using Flyway in Spring Boot to auto migrate database at the application startup. You can find the implementation example on GitHub

Spring