How do you configure Flyway migrations in Spring Boot?

Table of Contents

Introduction

Flyway is a popular database migration tool that automates the process of applying schema changes to your database in a controlled, versioned manner. When used in Spring Boot, Flyway provides an easy way to manage database migrations as part of the application's lifecycle. It applies SQL-based migration scripts on application startup, ensuring that the database schema is in sync with the application's current version.

In this guide, we’ll walk through how to configure Flyway migrations in a Spring Boot application, from setting up dependencies to configuring migration scripts and properties.

Step 1: Add Flyway Dependency to Your Project

The first step to configuring Flyway in a Spring Boot project is adding the Flyway dependency. Flyway is supported out-of-the-box by Spring Boot, so integrating it is straightforward.

For Maven:

In your pom.xml file, add the following Flyway dependency:

For Gradle:

In your build.gradle file, add:

Once you have added the dependency, Spring Boot will automatically detect and configure Flyway, but you can further customize the settings if necessary.

Step 2: Configure Flyway in application.properties or application.yml

You can configure Flyway through either the application.properties or application.yml file in your Spring Boot project. The default configuration assumes Flyway will look for migration scripts in the src/main/resources/db/migration directory.

Example Configuration in application.properties:

Example Configuration in application.yml:

Explanation of Common Configuration Properties:

  • **spring.flyway.enabled**: Enables Flyway migrations in the application. It’s true by default.
  • **spring.flyway.locations**: Specifies the location of your migration scripts. By default, it points to classpath:db/migration.
  • **spring.flyway.baseline-on-migrate**: If set to true, Flyway will create a baseline version when no flyway_schema_history table exists. Useful when you are adding Flyway to an existing project.
  • **spring.flyway.schemas**: Specifies the schema(s) that Flyway will use to manage migrations. By default, it uses the public schema.
  • **spring.flyway.table**: Specifies the name of the Flyway schema history table. By default, this table is named flyway_schema_history.

Step 3: Create Flyway Migration Scripts

Flyway applies database migrations based on versioned SQL scripts. These scripts must be placed in the directory specified by spring.flyway.locations (the default is src/main/resources/db/migration). Each migration script should follow a naming convention of V<version>__<description>.sql.

Example Migration Script:

  • **V1__Create_employee_table.sql**: The version is indicated by V1, and the description is Create_employee_table. The double underscore (__) separates the version from the description.
  • Flyway will automatically execute this migration script when the application is run for the first time.

Another migration script might be:

Flyway Migration Naming Convention:

  • **V<version>__<description>.sql**: The version number (e.g., V1, V2) determines the order of the migration scripts.
  • **__** (double underscore): Separates the version from the description in the migration script file name.

Flyway will apply migrations in the order of the version numbers, ensuring that the changes are applied incrementally and consistently.

Step 4: Run Migrations Automatically

Flyway will automatically run migrations on Spring Boot application startup, provided the Flyway dependency is present and properly configured. Flyway checks the flyway_schema_history table (or the custom table name you've set) in the database to see which migrations have already been applied.

How Flyway Works:

  • When the application starts, Flyway compares the versions of the migrations that have been applied (stored in the flyway_schema_history table) against the versions of the migration scripts available.
  • It then applies any pending migrations in order.
  • If a migration has already been applied, Flyway skips it.

Example Output:

When you run the Spring Boot application, Flyway will output the results of applying the migrations to the console:

Step 5: Verify Migrations in the Database

Flyway keeps track of the migrations in a special table called flyway_schema_history. This table records details such as:

  • The version number of each migration.
  • The description of each migration.
  • The date and time the migration was applied.
  • The status (applied or not applied) of each migration.

For example, after applying the migrations, you can check the flyway_schema_history table in the database:

This will show all the migrations that have been applied to the database.

Step 6: Advanced Configuration (Optional)

In some cases, you may need to configure additional options for Flyway migrations, such as running migrations on a specific schema, managing database versions, or controlling the behavior during rollback. These advanced configurations can be added through application.properties or application.yml files.

Common Advanced Configuration Options:

  • **spring.flyway.placeholders.<name>**: Allows you to define placeholders in your migration scripts and substitute values dynamically during migration. For example:

    And in your SQL migration script:

  • **spring.flyway.clean-on-validation-error**: When set to true, Flyway will clean the schema if it detects a validation error during migration.

  • **spring.flyway.sql-migration-prefix**: Customizes the prefix for the migration script files (default is V).

Conclusion

Configuring Flyway migrations in Spring Boot is a straightforward process that helps automate and version-control database schema changes. By adding the Flyway dependency, configuring it in application.properties or application.yml, and creating versioned SQL migration scripts, you can ensure that your database schema evolves alongside your application code. Flyway's integration with Spring Boot ensures that migrations are applied automatically at startup, making it an excellent choice for managing database versions in modern Java applications.

Share
Similar Questions