Persistence top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:


1. Introduction

This article describes key concepts of Flyway and how we can use this framework to continuously remodel our application's database schema reliably and easily. At the end, we'll present an example of managing an in-memory H2 database using a Maven Flyway plugin.

Flyway updates a database from one version to a next using migrations. We can write migrations either in SQL with database-specific syntax or in Java for advanced database transformations.

Further reading:

Use Liquibase to Safely Evolve Your Database Schema

How to use Liquibase to safely and maturely evolve the database schema of your Java app.

Rolling Back Migrations with Flyway

Learn how to safely roll back migrations using Flyway.

A Guide to Flyway Callbacks

A guide to implementing SQL and Java command-callbacks in Flyway

Migrations can either be versioned or repeatable. The former has a unique version and is applied exactly once. The latter does not have a version. Instead, they are (re-)applied every time their checksum changes.

Within a single migration run, repeatable migrations are always applied last, after pending versioned migrations have been executed. Repeatable migrations are applied in order of their description. For a single migration, all statements are run within a single database transaction.

In this article, we mainly focus on how we may use the Maven plugin to perform database migrations.

2. Flyway Maven Plugin

To install a Flyway Maven plugin, let's add the following plugin definition to our pom.xml:


We can check the latest version of the plugin available at Maven Central.

This Maven plugin may be configured in four different ways. Please refer to the documentation to get a list of all configurable properties.

2.1. Plugin Configuration

We may configure the plugin directly via the <configuration> tag in the plugin definition of our pom.xml:


2.2. Maven Properties

We may also configure the plugin by specifying configurable properties as Maven properties in our pom:


2.3. External Configuration File

We may also provide plugin configuration in a separate .properties file:


The default configuration file name is and it should reside in the same directory as the pom.xml file. Encoding is specified by flyway.encoding (Default is UTF-8).

If you are using any other name (e.g as the configuration file, then it should be specified explicitly when invoking the Maven command:

$ mvn

2.4. System Properties

Finally, all configuration properties may also be specified as system properties when invoking Maven on the command line:

$ mvn -Dflyway.user=databaseUser -Dflyway.password=databasePassword 

Following is an order of precedence when a configuration is specified in more than one way:

  1. System properties
  2. External configuration file
  3. Maven properties
  4. Plugin configuration

3. Example Migration

In this section, we walk through the required steps to migrate a database schema to an in-memory H2 database using the Maven plugin. We use an external file to configure Flyway.

3.1. Update POM

First, let's add H2 as a dependency:


We can, again, check the latest version of the driver available on Maven Central. We'd also add the Flyway plugin as explained earlier.

3.2. Configure Flyway Using External File

Next, we create in $PROJECT_ROOT with the following content:


The above configuration specifies that our migration scripts are located in the db/migration directory. It connects to an in-memory H2 instance using databaseUser and databasePassword.

The application database schema is app-db.

Of course, we replace flyway.user, flyway.password, and flyway.url with our own database username, database password, and database URL appropriately.

3.3. Define First Migration

Flyway adheres to the following naming convention for migration scripts:



  • <Prefix> – Default prefix is V, which may be configured in the above configuration file using the flyway.sqlMigrationPrefix property.
  • <Version> – Migration version number. Major and minor versions may be separated by an underscore. The migration version should always start with 1.
  • <Description> – Textual description of the migration. The description needs to be separated from the version numbers with a double underscore.

Example: V1_1_0__my_first_migration.sql

So, let's create a directory db/migration in $PROJECT_ROOT with a migration script named V1_0__create_employee_schema.sql containing SQL instructions to create the employee table:


    `name` varchar(20),
    `email` varchar(50),
    `date_of_birth` timestamp


3.4. Execute Migrations

Next, we invoke the following Maven command from $PROJECT_ROOT to execute database migrations:

$ mvn clean flyway:migrate

This should result in our first successful migration.

The database schema should now be depicted as follows:

| id | name | email | date_of_birth |

We can repeat definition and execution steps to do more migrations.

3.5. Define and Execute Second Migration

Let's see what a second migration looks like by creating a second migration file with name V2_0_create_department_schema.sql containing the following two queries:


`name` varchar(20)


ALTER TABLE `employee` ADD `dept_id` int AFTER `email`;

We'll execute a similar migration like we did the first time.

And now, our database schema has changed to add a new column to employee and a new table:

| id | name | email | dept_id | date_of_birth |
| id | name |

We may now verify that both migrations were indeed successful by invoking the following Maven command:

$ mvn flyway:info

4. Disabling Flyway in Spring Boot

Sometimes we may need to disable Flyway migrations under certain circumstances.

For example, it's a common practice to generate database schema based on the entities during tests. In such a situation, we can disable Flyway under the test profile.

Let's see how easy it is in Spring Boot.

4.1. Spring Boot 1.x

All we need to do is to set the flyway.enabled property in our file:


4.2. Spring Boot 2.x

In the more recent versions of Spring Boot, this property has been changed to spring.flyway.enabled:


4.3 Empty FlywayMigrationStrategy

If we only want to disable automatic Flyway migration on startup, but still be able to trigger the migration manually, then using the properties described above isn't a good choice.

That's because in such a situation Spring Boot will not auto-configure the Flyway bean anymore. Consequently, we'd have to provide it on our own which isn't very convenient.

So if this is our use case, we can leave Flyway enabled and implement an empty FlywayMigrationStrategy:

public class EmptyMigrationStrategyConfig {

    public FlywayMigrationStrategy flywayMigrationStrategy() {
        return flyway -> {
            // do nothing  

This will effectively disable Flyway migration on application startup.

But we'll still be able to trigger the migration manually:

public class ManualFlywayMigrationIntegrationTest {

    private Flyway flyway;

    public void skipAutomaticAndTriggerManualFlywayMigration() {

5. How Flyway Works

To keep track of which migrations have already been applied, when and by whom, it adds a special bookkeeping table to your schema. This metadata table also tracks migration checksums and whether or not the migrations were successful.

The framework performs the following steps to accommodate evolving database schemas:

  1. It checks a database schema to locate its metadata table (SCHEMA_VERSION by default). If the metadata table does not exist, it will create one
  2. It scans an application classpath for available migrations
  3. It compares migrations against the metadata table. If a version number is lower or equal to a version marked as current, it is ignored
  4. It marks any remaining migrations as pending migrations. These are sorted based on version number and are executed in order
  5. As each migration is applied, the metadata table is updated accordingly

6. Commands

Flyway supports the following basic commands to manage database migrations.

  • Info: Prints current status/version of a database schema. It prints which migrations are pending, which migrations have been applied, what is the status of applied migrations and when they were applied.
  • Migrate: Migrates a database schema to the current version. It scans the classpath for available migrations and applies pending migrations.
  • Baseline: Baselines an existing database, excluding all migrations, including baselineVersion. Baseline helps to start with Flyway in an existing database. Newer migrations can then be applied normally.
  • Validate: Validates current database schema against available migrations.
  • Repair: Repairs metadata table.
  • Clean: Drops all objects in a configured schema. All database objects are dropped. Of course, you should never use clean on any production database.

7. Conclusion

In this article, we've shown how Flyway works and how we can use this framework to remodel our application database reliably.

The code accompanying this article is available on GitHub.

Persistence bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

Inline Feedbacks
View all comments
Fosho Law
Fosho Law
4 years ago

Interesting but I’m confused about how this is different than having a ddl file with “CREATE TABLE IF NOT EXISTS” statements. Could you elaborate on the differences and advantages of this? Thanks in advance. -Avid reader

Eugen Paraschiv
4 years ago
Reply to  Fosho Law

Hey Fosho, So – the simple option to create tables when they don’t exist is a start, but frameworks such as Flyway and Liquibase go way beyond that simple usecase. A quick example that ties to your scenario is – say you already have the table, but you need to add a new column to it. Or you need to remove one, or change the type of one. All of these kinds of changes are more about evolution, for a project that’s already deployed and in use – which is of course, most projects. So – outside of greenfield development,… Read more »

Fosho Law
Fosho Law
4 years ago

Thanks for the reply Eugen. That clears up a bit but not completely. For adding/removing columns, shouldn’t there be SQL functions for checking if the column exist or not. These database migration projects sound really cool but I’m still having trouble seeing the difference between these tools and having different ddl files.

Eugen Paraschiv
4 years ago
Reply to  Fosho Law

Yes, of course – there is. And that’s what these frameworks use on the back-end.
It’s simply a way to manage these changes and provide a clean and consistent way of evolving (and rolling back) the structure of the schema.
If you don’t use one of these kinds of frameworks, your only other option is to manage these changes and these ddl files for deltas manually – which is a recipe for disaster (I know because I’ve tried).

Sanket Meghani
Sanket Meghani
4 years ago
Reply to  Fosho Law

Fosho, it may not be obvious for simple scenarios as you mentioned. Now consider you have a set of SQL statements which are either dependent on each other and needs to be executed in atomic way or in particular order. If we use migration tool, such things are manages by tools and we only need to concentrate on actual migration logic. In addition, such tools allow writing migrations in Java and other languages, which allows us to take advantage of ORM and we can implement any complex business rule (pre-condition/post-condition/validation etc) if need be. Having said that, there is nothing… Read more »

Cristi Iaroi
Cristi Iaroi
4 years ago

Good to have more of these frameworks as alternatives. However I think mybatis migrations are better.

Basically it provides the same approach with a table to keep track of your changes but also is more customizable ( can be configured per environment and per maven profile) . Additionally it has a gradle plugin as well.

Eugen Paraschiv
4 years ago
Reply to  Cristi Iaroi

That’s an interesting tool – but is it specific to MyBatis? If it is – then I’m not sure how helpful it is – because 99% of the world is not using MyBatis. If it’s generic, then besides the very unfortunate naming – it looks like an interesting alternative.

Cristi Iaroi
Cristi Iaroi
4 years ago

It isn’t mybatis specific. Just bad naming. Can be applied for any db and any db access technology. I used it with mybatis but also on projects with hibernate/spring data. In this second case it’s just sql for managing the migrations. I encourage you to try it out. It’s really easy to use.

Eugen Paraschiv
4 years ago
Reply to  Cristi Iaroi

That sounds good. However, bad naming is a bit of an understatement – it’s like calling a system like ElasticSearch – “the SOLR plugin”. Nobody would even suspect it can do more.
I’d love to explore it in a separate article, sure, but unfortunately with that name, nobody’s using it anyways, so I think we’ll have to skip this one. Of course when I say nobody – I mean very very few people, not actually nobody.
Hope that makes sense. Cheers,

Comments are closed on this article!