Chapter 4.7☕ 16 min read

Flyway & Liquibase Database Migrations

Stop guessing — version your SQL scripts like code.

01The Concept: Version Control for Databases

In previous chapters, we used spring.jpa.hibernate.ddl-auto=update. This means Hibernate guesses how to create tables. But in production, if you rename a column, Hibernate might delete your data! Enterprise apps use Database Migration Tools like Flyway to version-control SQL scripts.

The Hyderabad Metro Construction Analogy:

When the Hyderabad Metro was built, they didn't just randomly pour concrete and change tracks daily. They had blueprints (V1, V2). When a new station was added, they created a new blueprint file (V3__Add_Station.sql), reviewed it, and then applied it to the real city.

Flyway does this for databases. Every time you change a table (add a column, create a table), you write a SQL file with a version number. When Spring Boot starts, Flyway checks which version the database is on, and runs any new SQL files automatically.

02Technical Explanation

Flyway: A tool that tracks database schema changes. It creates a table called flyway_schema_history in your database to remember which scripts have already run.
Naming Convention: Files must be named V{Version}__{Description}.sql (e.g., V1__Create_Books_Table.sql). The double underscore __ is mandatory.
Execution Order: On startup, Flyway runs the scripts in version order (V1, then V2, then V3) exactly once.

03Full Working Code: Setting up Flyway

1. application.properties

# Tell Spring Boot NOT to auto-create tables
spring.jpa.hibernate.ddl-auto=none
# Enable Flyway
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration

2. Create the Migration Script

Create a folder structure: src/main/resources/db/migration/

Inside it, create a file named V1__Create_Book_Table.sql.

04The Migration Script

src/main/resources/db/migration/V1__Create_Book_Table.sql

-- This SQL will run automatically on app startup
CREATE TABLE Book (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    author VARCHAR(255) NOT NULL
);

-- Insert some initial data
INSERT INTO Book (title, author) VALUES ('Hyderabad History', 'Sai');

Now, when you start your Spring Boot app, Flyway will read this file, create the Book table exactly as you wrote it, and insert the data. If you later need to add a column, you create V2__Add_Pages_Column.sql — you never edit V1.

05Why It Matters / Interview Note

Interview Question: "Why shouldn't you use hibernate.hbm2ddl.auto=update in production? How do you manage schema changes?"

Answer: Hibernate's update is risky because it cannot handle complex schema changes (like renaming columns — it will just add a new column and leave the old one, losing data). We use Flyway or Liquibase to write explicit, reviewed SQL migration scripts. This ensures the exact same database structure is applied across Dev, QA, and Production environments.

Enterprise Note: Flyway is purely SQL-based, which DBAs love because they can read it. Liquibase uses XML/YAML/JSON formats, which is database-agnostic (it translates to different SQL for MySQL vs PostgreSQL). Most enterprise Java teams prefer Flyway for its simplicity and raw SQL control.

Key Takeaways

✅ Flyway version-controls database schemas using ordered SQL scripts
✅ Naming convention: V{Version}__{Description}.sql — never edit past scripts
✅ spring.jpa.hibernate.ddl-auto=none disables Hibernate schema auto-generation
✅ Flyway (SQL) vs Liquibase (XML/YAML) — most Java teams prefer Flyway

PreviousTransactions and Transactional 📋 All Chapters Next ChapterLombok Integration →