29th Aug

Flyway database migrator

Monday, August 29, 2016 - 19:06

Usually our applications are not used in only one environment. Each environment has its own database. These databases can be different. When we upgrade our application we have to know which database changes had been made on this given environment and which is not. This can be a huge task and can cause errors when we had more clients with more environments.

Flyway can help manage this problem. The way as Flyway helps us is the following. Every database is aware of its own sate. When we make changes on the database with the help of Flyway, it checks the actual database’s version number which is managed by Flyway also with the help of a metadata table. After that, Flyway decides which database patches' version number are greater than the target database’s version number and these patches will be executed by Flyway.

Flyway provides different modes to make database changes: Command-line tool; JAVA API; Maven Plugin; Gradle Plugin; Ant Task and SBT Plugin. We will deal with the Command-line tool.

Patch types and naming conventions

Flyway manages two types of database patch files:

  • Versioned migration: executed only once
  • Repeatable migration: executed when file content changes

Flyway follows a naming pattern. The file name has to consist of the following parts:

  • prefix: default V for the versioned; R for the repeatable migrations
  • version number (only for versioned): you can separate version number parts with dot or underscore
  • separator: default __
  • description
  • suffix: default .sql

All default values can be changed.



Command-line tool

The database version management is based on 6 commands.

Migrates the database to the current version. Flyway checks the file system (./sql folder by default) for the available migration files and compare them to the database. If there is any differences Flyway migrates them to the database (only with higher version number). If the metadata table does not exist, Flyway creates it.

Delete all objects from the database.

Shows the status of the database and the .SQL files. There are some .SQL file states:

  • Success: it was migrated
  • Pending: it will be migrated
  • Target: it won’t be migrated (version number is greater than the target)
  • Missing: it was migrated but mission on file system


Validates the already executed database patches against the patch can be find locally.

Baselines an existing database to the given baseline version number. After that you can migrate the database patches with the greater version number.

Repairs the metadata table after something went wrong. 

It helps to:

  • Remove failed migration entries
  • Realign the executed migrations’ checksums to the available ones.


Flyway gives a handle to make standalone database patches. These patches do not related to versions. Flyway executes them at a specified point of the migration process. You can decide the execution time by the name of the patches. 




Before Migrate runs


Before every single migration during Migrate


After every single migration during Migrate


After Migrate runs


Before Clean runs


After Clean runs


Before Info runs


After Info runs


Before Validate runs


After Validate runs


Before Baseline runs


After Baseline runs


Before Repair runs


After Repair runs

Detailed information


Comments (0)