How to Use Flyway with Spring Boot for Database Migrations

To use Flyway with Spring Boot, add the spring-boot-starter-data-jpa and flyway-core dependencies, then place your migration scripts in src/main/resources/db/migration. Spring Boot auto-runs Flyway migrations on startup, keeping your database schema up to date.

Syntax

Flyway integrates with Spring Boot mainly through configuration and migration scripts. Key parts include:

• Dependencies: Add flyway-core to your project.
• Migration scripts: SQL files named like V1__init.sql placed in src/main/resources/db/migration.
• Configuration: Optional properties in application.properties or application.yml to customize Flyway behavior.

properties

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.flywaydb:flyway-core'
}

# Migration scripts location:
src/main/resources/db/migration/V1__init.sql

# Optional config in application.properties
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-on-migrate=true

Example

This example shows a Spring Boot app with Flyway managing a simple database schema migration. The migration script creates a users table. On app startup, Flyway runs the script automatically.

sql,properties,java

/* src/main/resources/db/migration/V1__create_users_table.sql */
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL
);

/* src/main/resources/application.properties */
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.hibernate.ddl-auto=none
spring.flyway.enabled=true

/* src/main/java/com/example/demo/DemoApplication.java */
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Output

2024-06-01 12:00:00.000  INFO 12345 --- [           main] o.f.c.internal.license.VersionPrinter    : Flyway Community Edition 9.16.1 by Redgate
2024-06-01 12:00:00.500  INFO 12345 --- [           main] o.f.c.i.database.base.BaseDatabaseType    : Database: jdbc:h2:mem:testdb (H2 2.1)
2024-06-01 12:00:01.000  INFO 12345 --- [           main] o.f.core.internal.command.DbMigrate      : Successfully applied 1 migration to schema "PUBLIC" (execution time 00:00.123s)
2024-06-01 12:00:01.200  INFO 12345 --- [           main] com.example.demo.DemoApplication          : Started DemoApplication in 2.345 seconds (JVM running for 2.789)

Common Pitfalls

Common mistakes when using Flyway with Spring Boot include:

• Not placing migration scripts in the correct folder (db/migration inside resources).
• Incorrect naming of migration files; they must start with V followed by a version number and double underscore.
• Setting spring.jpa.hibernate.ddl-auto to create or update which conflicts with Flyway migrations.
• Forgetting to enable Flyway if it was disabled by default.

Example of wrong and right migration file naming:

sql

-- Wrong file name:
-- src/main/resources/db/migration/init.sql

-- Right file name:
-- src/main/resources/db/migration/V1__init.sql

Quick Reference

Summary tips for using Flyway with Spring Boot:

• Put SQL migration files in src/main/resources/db/migration.
• Name files like V1__description.sql, V2__another_change.sql.
• Use spring.flyway.enabled=true to activate migrations.
• Set spring.jpa.hibernate.ddl-auto=none to avoid conflicts.
• Check Flyway logs on startup to confirm migrations ran.

Key Takeaways

Add the flyway-core dependency and place migration scripts in src/main/resources/db/migration.

Name migration files starting with V and a version number, followed by a double underscore.

Enable Flyway in application properties and disable Hibernate auto schema updates.

Flyway runs migrations automatically on Spring Boot startup to keep your database updated.

Check logs to verify successful migration execution.