Flyway Database Migrations in Spring Boot 3 – Step-by-Step Guide

Managing database schema changes in a consistent, version-controlled way is critical for modern applications. While schema.sql and data.sql work for basic bootstrapping, Flyway is a professional-grade solution for automated, repeatable, and safe database migrations. Flyway Database Migrations in Spring Boot is easy as Sping Boot has first-class integration with Flyway.

🧠 What is Flyway?

Flyway is a database migration tool that tracks, version-controls, and applies SQL changes to your database.

It helps you:

• ✅ Version control your schema
• ✅ Track who changed what
• ✅ Apply schema changes automatically
• ✅ Avoid database drift

⚙️ How Flyway Works

Flyway looks for migration files in a specific location and applies them in version order.

Example file names:

V1__init_schema.sql
V2__add_user_table.sql
V3__insert_sample_data.sql

• V1, V2, etc. are version numbers.
• __ separates version and description.
• .sql is the migration script.

🚀 Adding Flyway to Spring Boot 3

If you’re using Spring Boot 3, Flyway is auto-configured if it’s on the classpath.

🔧 Step 1: Add dependency

For Maven:

  org.flywaydb
  flyway-core

📁 Project Structure

src/
 └── main/
      └── resources/
           ├── application.properties
           └── db/
                └── migration/
                     ├── V1__create_users_table.sql
                     └── V2__add_initial_users.sql

Flyway by default looks for scripts in:
classpath:db/migration

✍️ Example Migration Scripts

✅ V1__create_users_table.sql

CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL
);

✅ V2__add_initial_users.sql

INSERT INTO users (name, email) VALUES (‘Alice’, ‘alice@example.com’);
INSERT INTO users (name, email) VALUES (‘Bob’, ‘bob@example.com’);

🔧 Configuration in application.properties

# Optional: Flyway settings
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-on-migrate=true

Note:

• baseline-on-migrate=true: Useful when integrating Flyway with an existing DB.

🧪 Verifying Migrations

Flyway tracks migrations in a table called flyway_schema_history.
Run your app and check your DB — this table will show applied migrations.

You can inspect it in your DB:

SELECT * FROM flyway_schema_history;

🧱 Advanced Flyway Features

1️⃣ Java-based migrations

You can write migrations in Java if needed:

@Component
public class V3__CustomJavaMigration implements JavaMigration {
    @Override
    public void migrate(Context context) throws Exception {
        context.getConnection().prepareStatement(
          "INSERT INTO users (name, email) VALUES ('Charlie', 'charlie@example.com')"
        ).execute();
    }
}

2️⃣ Undo Migrations (Paid feature in Flyway Teams)

Flyway Community Edition does not support undo migrations.
Use it carefully and keep backups before running migrations in production.

🔄 How Flyway Applies Migrations

🛑 Disabling Flyway

You can disable Flyway if needed:

spring.flyway.enabled=false

✅ Best Practices

⚡ Comparison: Flyway vs Liquibase

🧹 Summary

• Flyway is the easiest way to handle versioned DB migrations in Spring Boot 3.
• It automatically picks up files from db/migration.
• Follows naming: Vx__description.sql
• Add scripts as you evolve your schema.
• Use in combination with baseline-on-migrate for existing DBs.