Unravel › Java concepts › Persistence and JPA
Database migrations (Flyway, Liquibase)
A migration tool applies numbered SQL scripts to the database in order and remembers which ones ran, so every environment, from a laptop to production, ends up with exactly the same schema.
At a glance
A recipe book for the database where each page is a numbered step.
- 1Flyway reads files like V1__create_orders.sql, V2__add_status.sql from classpath:db/migration, runs unapplied ones in version order and records them in flyway_schema_history with a checksum
- 2Liquibase describes changes in changelog files (YAML, XML, SQL) as change sets with an id and author, tracked in DATABASECHANGELOG
- 3Spring Boot runs the migration automatically on startup, before the application serves traffic, when the library is on the classpath
- 4Set spring.jpa.hibernate.ddl-auto to validate or none in real environmentsLetting Hibernate alter the schema (update) skips review and cannot handle data changes.
- Never edit a migration that has already run anywhere; the checksum check will fail startup
- Make migrations safe for rolling deployments: old and new application versions run against the same schema for a while
- On startup the tool takes a lock (a table row or advisory lock) so only one instance migrates when several start together, reads the history table, validates checksums of applied scripts, and executes the pending ones, each in a transaction where the database supports transactional DDL (PostgreSQL does, MySQL and Oracle do not)
Flyway flyway = Flyway.configure() .dataSource(url, user, password) .locations("classpath:db/migration") .baselineOnMigrate(true) .load();flyway.migrate();- line 1 uses Flyway, the core of Database migrations (Flyway, Liquibase)
Read the full explanation (about 2 min)
A migration tool applies numbered SQL scripts to the database in order and remembers which ones ran, so every environment, from a laptop to production, ends up with exactly the same schema.
A mental model
A recipe book for the database where each page is a numbered step. A history table is the bookmark: a new server starts at page one, an existing one continues from where it stopped.
How it works
Flyway reads files like V1__create_orders.sql, V2__add_status.sql from classpath:db/migration, runs unapplied ones in version order and records them in flyway_schema_history with a checksum.
Liquibase describes changes in changelog files (YAML, XML, SQL) as change sets with an id and author, tracked in DATABASECHANGELOG.
Spring Boot runs the migration automatically on startup, before the application serves traffic, when the library is on the classpath.
Set spring.jpa.hibernate.ddl-auto to validate or none in real environments. Letting Hibernate alter the schema (update) skips review and cannot handle data changes.
Going deeper
Never edit a migration that has already run anywhere; the checksum check will fail startup. Fix mistakes with a new, later migration.
Make migrations safe for rolling deployments: old and new application versions run against the same schema for a while. Use the expand and contract pattern: add a column first, deploy, backfill, and drop the old column in a later release.
Big table rewrites (adding a column with a default, creating an index) can lock a table for minutes in some databases. Use online variants (CREATE INDEX CONCURRENTLY) and test timings on production-sized data.
Under the hood
On startup the tool takes a lock (a table row or advisory lock) so only one instance migrates when several start together, reads the history table, validates checksums of applied scripts, and executes the pending ones, each in a transaction where the database supports transactional DDL (PostgreSQL does, MySQL and Oracle do not).
Common mistakes
- Editing an already applied migration.
- Using
ddl-auto=updatein production. - Destructive changes that break the previous application version during rollout.
- Long locking migrations run at peak time.
How Unravel recognises it
When you paste code, Unravel looks for these signs of database migrations (flyway, liquibase). Spotting them yourself is a good habit when you read unfamiliar code:
- Annotations:
@FlywayDataSource - Types:
FlywayFlywayConfigurationCustomizerBaseJavaMigrationJavaMigrationMigrationVersionSpringLiquibaseLiquibaseFlywayMigrationStrategyFlywayException - Configuration keys:
spring.flyway.enabledspring.flyway.locationsspring.liquibase.change-logclasspath:db/migrationspring.jpa.hibernate.ddl-autohibernate.hbm2ddl.autovalidatedb/changelog/db.changelog-master.yaml
Part of a learning path
- JPA and Hibernate in depth · previous: Auditing, lifecycle callbacks and soft delete · next: Connection pools (HikariCP)
Related concepts
Frequently asked questions
What is Database migrations (Flyway, Liquibase)?
A migration tool applies numbered SQL scripts to the database in order and remembers which ones ran, so every environment, from a laptop to production, ends up with exactly the same schema.
What are the most common mistakes with Database migrations (Flyway, Liquibase)?
Editing an already applied migration. Using ddl-auto=update in production. Destructive changes that break the previous application version during rollout. Long locking migrations run at peak time.
How can I see Database migrations (Flyway, Liquibase) in real code?
Paste your own Java into Unravel and it will point out where database migrations (flyway, liquibase) appears, explain how it works at the detail level you choose, and draw the flow of the code around it.