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:

<groupid>org.flywaydb</groupid>

<artifactid>flyway-core</artifactid>

</dependency>

📁 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(

"<strong>INSERT </strong>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

Scenario	What Happens
New migration added	Flyway applies it in order
Already applied	Skipped
Missing script	Fails validation
Manual DB change	Validation fails (unless `ignoreMissingMigrations=true`)

🛑 Disabling Flyway

You can disable Flyway if needed:

spring.flyway.enabled=false

✅ Best Practices

Practice	Reason
Use semantic versions (V1, V2, V3)	Easy tracking
Keep scripts idempotent	Safer re-execution
Never modify applied migrations	Use a new migration file
Test migrations on dev DBs	Avoid surprises
Use consistent naming (`V1__name.sql`)	Enforced by Flyway
Don’t rely on Hibernate DDL in prod	Use Flyway for full control

⚡ Comparison: Flyway vs Liquibase

Feature	Flyway	Liquibase
Learning Curve	Easier	Moderate
Format	SQL (default), Java	XML, YAML, JSON, SQL
Undo Support	Paid	Yes
Community Adoption	High	High
Integrated in Spring Boot	✅	✅

🧹 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.