Article 9: Database Migrations with Flyway

1. Introduction

So far, Spring Boot has been creating database tables automatically using JPA.

This is fine for learning — but dangerous in real projects.

In production:

• You must control database changes
• You must track schema history
• You must avoid accidental data loss

That’s where Flyway comes in.

---

2. What Is Database Migration?

Database migration means:

Managing database schema changes in a versioned, repeatable, and safe way.

Instead of:

• Manually running SQL
• Letting Hibernate auto-create tables

You:

• Write migration scripts
• Apply them in order
• Track versions

---

3. What Is Flyway?

Flyway is a lightweight database migration tool that:

• Runs SQL scripts automatically at startup
• Maintains a schema history table
• Works seamlessly with Spring Boot

Spring Boot has first-class Flyway support.

---

4. Why Not Use ddl-auto in Production?

spring.jpa.hibernate.ddl-auto=update

Problems:

• No version control
• Unpredictable changes
• Risk of data loss
• No rollback strategy

👉 Use ddl-auto=none + Flyway in real systems.

---

5. Adding Flyway Dependency

Add to pom.xml:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

Spring Boot auto-detects Flyway.

---

6. Flyway Folder Structure

Flyway looks for migrations in:

src/main/resources/db/migration

Create this folder structure exactly.

---

7. Naming Migration Files (Very Important)

Format:

V<version>__<description>.sql

Examples:

V1__create_user_table.sql
V2__add_email_column.sql

Rules:

• Version must increase
• Double underscore __ is mandatory

---

8. Writing Your First Migration

8.1 Disable Hibernate DDL

spring.jpa.hibernate.ddl-auto=none

---

8.2 Create Migration Script

File:

V1__create_user_table.sql

CREATE TABLE user (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100),
    email VARCHAR(100)
);

---

9. Running the Application

When the app starts:

1. Flyway checks schema history
2. Executes pending migrations
3. Records applied versions

Flyway creates:

flyway_schema_history

table automatically.

---

10. Adding a New Migration

Need a new column?

Create:

V2__add_age_column.sql

ALTER TABLE user ADD age INT;

Restart app → migration runs once.

---

11. Flyway vs Liquibase (Quick Note)

Flyway	Liquibase
SQL-based	XML/YAML/JSON
Simple	Feature-rich
Easy to learn	Steeper curve

Flyway is preferred for most Spring Boot projects.

---

12. Common Flyway Errors

❌ Wrong file naming
❌ Skipped version numbers
❌ Editing old migration files
❌ Mixing Flyway with ddl-auto=update

✔ Migrations are immutable once applied

---

13. Best Practices

✔ One migration per change
✔ Never modify applied migrations
✔ Use Flyway in all environments
✔ Review SQL carefully

---

14. What You Should Understand Before Moving On

You should now know:

• Why migrations matter
• How Flyway works
• How to write versioned SQL
• How schema history is tracked

---

15. What’s Next?

➡ Article 10: Request Validation

• @Valid
• Bean validation
• Clean API contracts

Type Next when you’re ready.