Flyway

Flyway is based on the concept of migrations. A migration is a script that performs some changes on your database. Every migration is versioned. As you implement new features, you add new migrations to the project. Flyway keeps track of which migrations have been applied to the database in a separate table. This table includes a checksum of every migration script.

When Flyway runs, either at application startup, or as a part of your deployment pipeline, it compares the contents of this table with the migrations in your project. It then executes all the migrations that were missing, from the oldest to the newest version. If the database is new, Flyway creates its metadata table and executes all the migrations.

Versioned migrations should not change after they have been applied. When Flyway runs, it recalculates the checksums of all the migrations in your project, and compares them with the checksums in the table. If there are any mismatches, it throws an exception and aborts.

In addition to versioned migrations, Flyway also supports repeatable migrations. These migrations can change after they have been applied, and are automatically re-applied after every change. Repeatable migrations are always applied after the versioned migrations.

You can write migrations in multiple languages, including Java, but the most common one is ordinary SQL. The migration scripts should follow a specific naming pattern. Versioned migrations start with an uppercase V, followed by a version number, two underscores __, a description, and the suffix .sql. For example, a migration could be named V1__initial_schema_setup.sql.

Repeatable migrations start with an uppercase R, followed by two underscores __, a description, and the suffix .sql. For example, a repeatable migration could be named R__people_view.sql. Repeatable migrations are sorted by their descriptions before they are applied. Take this into account if you need to apply one repeatable migration before another.

You should store your SQL scripts in the src/main/resources/db/migration directory of your project. If you are using a multi-module project, you should store the migrations in the module that handles persistence.

For information about writing migrations in other languages than SQL, see the Flyway Documentation.

Spring Boot has built-in support for Flyway. If the org.flywaydb:flyway-core module is on the classpath, Flyway is automatically executed on application startup.

Flyway has built-in support for clustered environments. If you launch multiple instances of the same application, pointing to the same database, Flyway makes sure that every migration is applied only once, in the correct order.

Unless you are using an in-memory database like H2, you have to add a database specific module to the classpath, in addition to the database’s own JDBC driver. For example, use org.flywaydb:flyway-database-postgresql with PostgreSQL and org.flywaydb:flyway-mysql with MySQL.

Spring Boot declares the modules in its parent POM, so you don’t have to look up their versions. To use them, add them to your project POM-file, like this:

By default, Flyway uses your application’s primary data source to apply the migrations. This means that the database user that you use to connect to the database must have enough privileges to execute Data Definition Language (DDL) statements.

From a security point of view, it is better to have one database user for DDL, and another for Data Modification Language (DML) statements. The DDL user is used by Flyway to migrate the database schema. The DML user is used by the application to query and modify data without touching the schema itself.

To make Flyway use its own data source, set the spring.flyway.[url,user,password] configuration properties. If you leave out spring.flyway.url, Flyway uses the same URL as the application’s primary data source.

For more information, see the Spring Boot Documentation.

Sometimes, you may want to run the Flyway migrations as a separate build step. For example, you may not want to make the DDL user credentials available to the application itself for security reasons. Flyway has a Maven plugin that allows you to run the migration scripts as a part of your build chain.

To run Flyway with Maven, you should still keep the migration scripts in the same directory as you did when running Flyway at application startup. However, you should not add any Flyway dependencies to your project. Instead, you should add the Flyway plugin, like this:

Note, that when you are adding dependencies to a Maven plugin, you have to specify their versions even if they have been declared in a parent POM. Spring Boot declares the versions of all its dependencies as properties, so you don’t have to look them up yourself.

Now, whenever you want to run Flyway, execute the following command:

For more information about what you can do with the Flyway Maven plugin and how to configure it, see the Flyway Documentation.