By WebNest Studio Engineering Team
Spring Boot Tutorial
Database Migrations with Flyway and Liquibase
Your schema evolves with your code: new tables, new columns, renamed fields, new indexes. On a developer laptop you can drop and recreate the database, but production data must be preserved and every environment must end up with exactly the same schema. Database migration tools solve this by keeping every schema change as a versioned script in source control and applying pending scripts automatically at startup.
Spring Boot integrates the two most popular tools, Flyway and Liquibase. In Spring Boot 4 you add them through dedicated starters (spring-boot-starter-flyway, spring-boot-starter-liquibase). This lesson covers both, with naming conventions, data migrations, safe changes for live systems, and testing.
How Migration Tools Work
The tool keeps a history table in your database (flyway_schema_history or DATABASECHANGELOG). At startup it compares the scripts in your project with that table and runs any new ones in order, recording each one and its checksum. Already applied scripts are never run again, and editing one is detected as a checksum mismatch. The rule is simple: never modify a migration that has been applied anywhere; add a new one.
Flyway
Flyway uses plain SQL files in src/main/resources/db/migration named V<version>__<description>.sql — for example V1__create_customers.sql, V2__add_phone_to_customers.sql. Repeatable migrations (R__refresh_views.sql) rerun whenever their content changes, useful for views and functions. Java-based migrations are available for complex data changes. Many databases (PostgreSQL, MySQL, SQL Server, Oracle) need an extra Flyway module such as flyway-database-postgresql.
Liquibase
Liquibase describes changes as changesets in YAML, XML, JSON or SQL, listed in a master changelog (db/changelog/db.changelog-master.yaml). Its database-independent change types (createTable, addColumn) let one changelog target several databases, and it supports automatic rollback for many change types. Choose Liquibase when you need multi-database support or rollbacks; choose Flyway for simplicity and plain SQL.
Hibernate and Migrations Together
Once migrations own the schema, set spring.jpa.hibernate.ddl-auto=validate. Hibernate then checks at startup that entities match the tables created by your scripts and fails fast if someone forgot a migration.
Zero-Downtime Changes (Expand and Contract)
During a rolling deployment, old and new versions of your application run against the same database at the same time. So never make a breaking change in one step. To rename a column: 1) add the new column, 2) deploy code that writes both and reads the new one, 3) backfill data, 4) deploy code that uses only the new column, 5) drop the old column in a later release. Add indexes concurrently on large PostgreSQL tables to avoid locking writes.
Examples
Flyway setup and the first migrations
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-flyway</artifactId>
</dependency>
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>
-- src/main/resources/db/migration/V1__create_customers.sql
create table customers (
id bigint generated by default as identity primary key,
email varchar(255) not null unique,
full_name varchar(200) not null,
created_at timestamp with time zone not null default now()
);
-- src/main/resources/db/migration/V2__create_orders.sql
create table orders (
id bigint generated by default as identity primary key,
customer_id bigint not null references customers(id),
status varchar(20) not null,
created_at timestamp with time zone not null default now()
);
create index idx_orders_customer on orders(customer_id);
-- src/main/resources/db/migration/V3__add_phone_to_customers.sql
alter table customers add column phone varchar(20);
Flyway Community Edition by Redgate
Database: jdbc:postgresql://localhost:5432/webnest (PostgreSQL 17.2)
Successfully validated 3 migrations
Current version of schema "public": << Empty Schema >>
Migrating schema "public" to version "1 - create customers"
Migrating schema "public" to version "2 - create orders"
Migrating schema "public" to version "3 - add phone to customers"
Successfully applied 3 migrations to schema "public", now at version v3
Flyway configuration and a data migration
# application.yml
spring:
flyway:
locations: classpath:db/migration
baseline-on-migrate: true # for adopting Flyway on an existing database
jpa:
hibernate:
ddl-auto: validate
-- V4__split_full_name.sql : expand step, keeps the old column for now
alter table customers add column first_name varchar(100);
alter table customers add column last_name varchar(100);
update customers
set first_name = split_part(full_name, ' ', 1),
last_name = nullif(substr(full_name, length(split_part(full_name, ' ', 1)) + 2), '');
Migrating schema "public" to version "4 - split full name"
Successfully applied 1 migration to schema "public", now at version v4
select version, description, success from flyway_schema_history;
1 | create customers | t
2 | create orders | t
3 | add phone to customers | t
4 | split full name | t
Liquibase with a YAML changelog
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-liquibase</artifactId>
</dependency>
# src/main/resources/db/changelog/db.changelog-master.yaml
databaseChangeLog:
- include:
file: db/changelog/001-create-courses.yaml
- include:
file: db/changelog/002-add-price.yaml
# db/changelog/001-create-courses.yaml
databaseChangeLog:
- changeSet:
id: 001-create-courses
author: webnest
changes:
- createTable:
tableName: courses
columns:
- column: { name: id, type: bigint, autoIncrement: true, constraints: { primaryKey: true } }
- column: { name: slug, type: varchar(100), constraints: { nullable: false, unique: true } }
- column: { name: title, type: varchar(200), constraints: { nullable: false } }
# db/changelog/002-add-price.yaml
databaseChangeLog:
- changeSet:
id: 002-add-price
author: webnest
changes:
- addColumn:
tableName: courses
columns:
- column: { name: price, type: decimal(10,2), defaultValueNumeric: 0 }
rollback:
- dropColumn: { tableName: courses, columnName: price }
Liquibase: Running Changeset: db/changelog/001-create-courses.yaml::001-create-courses::webnest
Liquibase: Running Changeset: db/changelog/002-add-price.yaml::002-add-price::webnest
Liquibase: Update command completed successfully.
Testing migrations against a real database with Testcontainers
@SpringBootTest
@Testcontainers
class MigrationTest {
@Container
@ServiceConnection
static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17");
@Autowired JdbcClient jdbc;
@Test
void allMigrationsApplyAndSchemaMatchesEntities() {
// Context startup already ran Flyway and Hibernate 'validate'
Integer applied = jdbc.sql("select count(*) from flyway_schema_history where success")
.query(Integer.class).single();
assertThat(applied).isGreaterThanOrEqualTo(4);
}
}
MigrationTest > allMigrationsApplyAndSchemaMatchesEntities() PASSED
(Catches broken SQL and entity/schema mismatches before they reach production.)
Common Mistakes
- Editing a migration file after it has been applied, causing "Validate failed: Migration checksum mismatch" in every other environment.
- Keeping ddl-auto=update alongside Flyway, so Hibernate and Flyway both change the schema.
- Making breaking changes (rename/drop column) in one step during rolling deployments.
- In Spring Boot 4, adding only flyway-core without spring-boot-starter-flyway, so Flyway is not auto-configured.
- Forgetting the database-specific Flyway module (e.g. flyway-database-postgresql) and getting "Unsupported Database".
Exercise
Using the lesson's Flyway setup and the first migrations example, create a small implementation or design sketch that demonstrates Migrations are versioned scripts in source control, applied automatically and recorded in a history table.. Add a test case or scenario that would catch Editing a migration file after it has been applied, causing "Validate failed: Migration checksum mismatch" in every other environment., and describe the expected result.
Show hints
- Start with How Migration Tools Work and compare your approach with Flyway setup and the first migrations. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows Migrations are versioned scripts in source control, applied automatically and recorded in a history table. and that it would catch the failure described by Editing a migration file after it has been applied, causing "Validate failed: Migration checksum mismatch" in every other environment..
Quick quiz
1. Which choice is a mistake to avoid in Database Migrations with Flyway and Liquibase?
- A. Migrations are versioned scripts in source control, applied automatically and recorded in a history table.
- B. Editing a migration file after it has been applied, causing "Validate failed: Migration checksum mismatch" in every other environment.
- C. Keeping ddl-auto=update alongside Flyway, so Hibernate and Flyway both change the schema.
Show answer
B. Avoid this approach: Editing a migration file after it has been applied, causing "Validate failed: Migration checksum mismatch" in every other environment. The lesson recommends: Migrations are versioned scripts in source control, applied automatically and recorded in a history table.
Interview questions
How would you apply the guidance in How Migration Tools Work to a real task, and what failure would you guard against?
Show answer
Migrations are versioned scripts in source control, applied automatically and recorded in a history table. Apply this in How Migration Tools Work; the example Flyway setup and the first migrations shows one way to do it. Avoid Editing a migration file after it has been applied, causing "Validate failed: Migration checksum mismatch" in every other environment. and explain how your implementation or design prevents that failure.
Key Points to Remember
- Migrations are versioned scripts in source control, applied automatically and recorded in a history table.
- Flyway: V<version>__<description>.sql in db/migration; Liquibase: changesets in a master changelog.
- In Spring Boot 4, use spring-boot-starter-flyway or spring-boot-starter-liquibase.
- Never edit applied migrations; set ddl-auto=validate so Hibernate checks the schema.
- Use expand-and-contract for zero-downtime schema changes and test migrations with Testcontainers.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering