Flyway is a open source database migration tool that allows you to manage database changes using migrations. Last week the version 4.0.1 has been released and I decided to write my first post about Flyway.
I started to use Flyway command-line almost 3 years ago (version 2.2.1) and the main reason that took me to use and keep using nowadays is: it’s simplicity, “database migrations made easy”. This key factor is translated into the following:
- Zero dependencies (you need java and your jdbc driver)
- You can download the version that already includes both: java and the driver;
- This is a key factor for the easy setup process;
- Easy to setup, no need to install
- You just have to configure Flyway: target server, migrations location, etc;
- This makes the deploy process extremely easy;
- The scripts are written in SQL
- You, or your team, do not have to learn or use a different language to create migrations.
Flyway commands
Flyway provides 6 basic commands:
- migrate
- Apply all migrations until the latest version, or until a specific target version;
- If the metadata table doesn’t exist this command will create it automatically;
- This is they key command of the Flyway workflow;
- clean
- Drops all database objects in the configured schemas;
- This command should be used with caution, especially in system databases or in production environment;
- Its useful in development and test environments enabling a fresh start cleaning completely your database;
- info
- Gives the current status information about all the migrations;
- This is done by checking the migrations scripts against the metadata table;
- Allows you to know if a migration was applied with success, or still pending or was ignored;
- validate
- Validates applied migrations against the available migration scripts on your folder;
- Allows to validate if all migrations were applied, i.e. do not exist pending migrations;
- Allows to validate if a migration script was change after being successfully applied;
- This validation is made trough checksum validation;
- Allows to reliably recreate the database schema;
- baseline
- Allows to set the baseline of an existing database;
- All migrations upto and including the baseline version will me ignored;
- If the metadata table doesn’t exist this command will create it automatically;
- repair
- This command repairs the metadata table;
- Remove migrations from the table marked as failed;
- Realign the checksums of the applied migrations to the ones of the available migrations
Flyway configuration
The Flyway configuration can be specified in two ways:
- In the configuration file: flyway.conf
- In the command-line using the format “-key=value” (this way overrides the previous one)
The following picture shows all available configuration options for Flyway version 3.2.1:
Flyway metadata table
The metadata table is used to track the state of the database. Allows to know which migrations have already been applied, when were applied and by whom. Additionally also tracks migration checksums.
The default name of the metadata table is “schema_version”. If the database is empty and the metadata table do not exist, Flyway will create it automatically.
Flyway scans the migrations directory and check migrations against the metadata table. Migrations are sorted based on their version number and applied in order.
Flyway command-line structure
When you download and extract Flyway command-line you will find the following structure:
- conf
- In the folder you will find the configuration file “flyway.conf”
- drivers
- This folder contains the jdbc drivers
- jars
- In this folder you can add java migrations
- lib
- This folder contains Flyway jar files
- sql
- In this folder you can add SQL migrations
- flyway.cmd
- File responsible for executing Flyway (Windows command script)