How do you create and manage database migrations with Flyway?

Table of Contents

Introduction

Flyway is a powerful tool for managing database migrations in Java applications. It helps you version control your database schema and apply incremental changes over time. By using Flyway, you can automate database updates, ensure consistency across environments, and manage complex schema changes with minimal effort. In this guide, we will walk you through how to create and manage database migrations with Flyway, from setup to running migrations in a Java application.

Setting Up Flyway in Your Project

1. Adding Flyway to Your Project

First, you need to add Flyway as a dependency to your project. If you are using Maven, add the following dependency to your pom.xml:

For Gradle users, add the following to your build.gradle:

2. Configure Flyway in Your Application

Once Flyway is added as a dependency, you need to configure it. For a Spring Boot application, Flyway can be configured in the application.properties or application.yml file.

In application.properties:

In application.yml:

This configuration ensures that Flyway will look for migration scripts in the classpath:db/migration directory, where you will store your SQL migration files.

Creating and Managing Migrations

1. Versioned Migrations

Flyway requires you to define migration scripts that follow a specific naming convention. The general format for migration script filenames is:

Where:

  • V: Denotes the version.
  • <Version>: A numeric version identifier.
  • <Description>: A brief description of what the migration does.

For example:

These migration files will be applied in order based on their version number.

2. Writing a Migration Script

To create your first migration, you might write a SQL script to create a table. For example, the script V1__Create_Employee_Table.sql could look like this:

3. Applying Migrations

Once the migration files are in place, Flyway automatically detects them when the application starts and applies any new migrations that haven’t been applied yet. If the version is new (i.e., a higher version number), Flyway will apply the SQL scripts in order.

To run the migration manually using the Flyway command-line tool, use the following command:

This command will apply any outstanding migrations.

4. Tracking Applied Migrations

Flyway keeps track of which migrations have been applied by maintaining a special table in the database called flyway_schema_history. This table stores information about each applied migration, including the version, description, and checksum of the SQL file.

You don’t need to manually manage this table—it is created and updated by Flyway automatically.

5. Baseline and Repair

In some cases, when you are starting with an existing database, Flyway may need to "baseline" the migrations. This means that you can tell Flyway where to start tracking migrations by creating a baseline version. This can be done by adding the following configuration to your application.properties:

Alternatively, you can run the following command in the Flyway CLI to baseline an existing database:

If you encounter issues, such as corruption in the flyway_schema_history table or missing migration files, you can use the flyway repair command to fix the schema history:

Advanced Features in Flyway

1. Repeatable Migrations

Flyway also supports repeatable migrations, which are useful for handling changes that may need to be reapplied, such as views, stored procedures, or other database objects that can change over time. Repeatable migrations are given a R prefix:

Flyway will reapply these migrations whenever their content changes.

2. Validation

Flyway can validate the migrations already applied to ensure that the database schema matches the current state of the migrations. You can run the following command to perform validation:

This checks that the migrations in your flyway_schema_history table are consistent with the current migration scripts.

3. Undo Migrations

Flyway has an "undo" feature that can be used to roll back migrations. However, this is an advanced feature that requires specific SQL scripts. You would need to define undo scripts for each migration.

To use undo, the script would look like this:

Flyway would then apply the undo scripts to roll back changes.

4. Multiple Environments

In a typical application, you may have different environments (development, staging, production). Flyway allows you to manage migrations across different environments by configuring different locations or using different databases for each environment.

For instance, you can set up environment-specific properties in application-dev.properties, application-prod.properties, etc.

This would allow you to manage migrations independently for each environment.

Example of Full Flyway Migration Setup

  1. Add Flyway dependency to your project.
  2. Configure Flyway in your application.properties.
  3. Create your first migration: V1__Create_Employee_Table.sql.
  4. Run the migrations using Flyway’s automatic migration feature (for Spring Boot) or manually through the CLI.
  5. Add more migrations as your database schema evolves.
  6. Monitor and manage migrations using Flyway's commands, such as migrate, validate, and repair.

Conclusion

Flyway provides a straightforward and efficient way to manage database migrations in Java applications. By creating versioned SQL migration scripts and using Flyway's built-in commands, you can automate schema changes and ensure consistency across different environments. The Flyway approach simplifies the complex task of maintaining and deploying database schema changes, making it a popular choice for developers working with relational databases. Whether you're using it with Spring Boot or a stand-alone Java application, Flyway’s powerful features like validation, repeatable migrations, and rollback support help you manage your database schema with confidence.

Share
Similar Questions