Introduction

The code version subject is not a news. The database version is not so much, but it is so important such as the first one.

This kind of database version control is named of database migration, on which you can handle the historical state of the database and recreate. The database migration will be worried about the version data and schema.

A solution is the Flyway, a tool implemented in Java to be applied to the database that supports a Java application. It enables the database to be compatible, using plain SQL scripts (or java) in the lifecycle of an application.

The Flyway always compare the versions and applying new migrations automatically. Any change after that should be done through the use of a script in the directory read by Flyway, usually classpath:db/migration folder.

Internally, the Flyway use a table, created automatically on the first execution, to read the records with the versions. It kept track by a checksum for each Migration that has been executed (together with other information).


The spets are:

  • It checks the database schema (SCHEMA_VERSION)
  • It searches for available migrations
  • It compares migrations (version number)
  • It marks any remaining migrations as pending migrations.
  • It updates the metadata after the migration.

Name Convention

Flyway's name convention is:

  • Prefix: Defaults to V, for versioned, U for undo and R for repeatable migrations 
  • Version: Dots or underscores separated in as many parts as one likes.
  • Separator: Defaults to __ (two underscores) and separates the version from the description.
  • Description: A text with words separated by underscores or spaces.
  • You can use a Suffix.De default is .sql. 
V1_1__description_indexes
V1.0001__some_description.sql

For a single migration, all statements are run within a single database transaction. The repeatable migrations are run in order of their description and after all the pending versioned migrations.

Config

To config the flyway in your app using maven you should to add dependencies and plugins in pom.xml. See [1] and [2].

<!-- DEPENDENCY -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>${flyway.version}</version>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-commandline</artifactId>
    <version>${flyway.version}</version>
   <optional>true</optional>
</dependency>

<!-- PLUGIN -->
<groupId>org.flywaydb</groupId>
<artifactId>flyway-maven-plugin</artifactId>
<version>5.2.4</version>

You can use flyway.conf to define global attributes. Also, you can have another specific file by the project to set attributes that will overwrite the global ones. 

Commands

A migration run in a database sequentially using a set of commands. For example:

mvn clean flyway:migrate

The “migrate” is one of them. But which one you will use depends on your objective. So, some basic commands are [3]:

  • Info: Prints detail but with no persistence. It will show status/version of a database schema, which migrations are pending or applied, etc.
  • Migrate: Migrates a database schema applying what is pending.
  • Baseline: Baselines an existing database, excluding all migrations.
  • Validate: Validates current database schema against available migrations.
  • Repair: Repairs metadata table.
  • Clean: Drops all objects in a configured schema. 

Conclusion

It is an important topic that you should pay attention to. In a big company many times you don't need to know about this, but it's a great deal have an overview of planning changes in the applications.

References