# 1. The problem, and the smallest correct mental model [Index](../README.md) · Next: [2. Anatomy of a Flyway migration run →](02-anatomy-of-a-migration-run.md) Every app with a database eventually needs a second table added, or a column renamed, or a default changed — and it needs that to happen the same way on the laptop where it was written, on the CI database that only exists for four minutes, and on production, which nobody wants to SSH into and run SQL by hand against. A migration tool's whole job is to make "the same way" true without a human re-typing SQL in three places. Both tools this module compares solve that with the same core idea: number or name every schema change, keep a table *inside the database itself* that records which ones have already run, and on startup, apply whatever is missing. That tracking table is the single most important thing to understand before either tool's specific behaviour makes sense — it is the reason a second `mvn spring-boot:run` doesn't re-run migration 1, and it is the reason two things you're about to read about (checksum validation, and locking) exist at all. The tracking table is not a cache or a convenience — it is the source of truth the tool consults before touching your schema at all, and it lives in the same database the schema lives in, so it survives redeploys, restarts, and different machines running the same migration set. Flyway's is called `flyway_schema_history`; Liquibase's is called `DATABASECHANGELOG`, with a second table, `DATABASECHANGELOGLOCK`, purely for coordinating concurrent runs (chapters [8](08-concurrent-startup-and-locking.md) and [11](11-liquibase-locking.md)). ## What this module actually runs Everything in this article is one small Spring Boot 4.1.1 module, [`db-migrations-flyway-liquibase`](..), with both starters on the classpath: [`spring-boot-starter-flyway`](../pom.xml) and [`spring-boot-starter-liquibase`](../pom.xml). Two tiny migration sets live side by side — Flyway's under [`src/main/resources/db/migration`](../src/main/resources/db/migration), Liquibase's as one YAML changelog at [`db.changelog-master.yaml`](../src/main/resources/db/changelog/db.changelog-master.yaml) — and every scenario in the chapters that follow is a real JUnit test using Spring's [`ApplicationContextRunner`](../src/test/java/com/ankurm/dbmigrations/flyway/FlywayHappyPathTest.java), which boots a real `ApplicationContext` against a real H2 file database in milliseconds, with no web server needed. A small [`Transcript`](../src/test/java/com/ankurm/dbmigrations/Transcript.java) helper writes what each test asserts to a plain text file under [`docs/output/`](output) — every table and error message quoted in this documentation, and in the published article, was copied out of one of those committed files, not retyped from memory. The one part of the module that *is* a running app rather than a test is [`DbMigrationsApplication`](../src/main/java/com/ankurm/dbmigrations/DbMigrationsApplication.java), whose only purpose is to expose `/diag/migrations` (chapter [15](15-production-checklist.md)) so you can watch a real startup's bookkeeping instead of only reading about it. ## Going deeper - [Flyway: how migrations work](https://documentation.red-gate.com/fd/migrations-271585107.html) — the vendor's own concept page (`rel="nofollow"`). - [Liquibase: how it works](https://docs.liquibase.com/concepts/introduction-to-liquibase.html) — the vendor's own concept page (`rel="nofollow"`). - [Spring Boot 4.1 release notes](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.1-Release-Notes) — for the package relocation both tools' autoconfiguration went through (chapter [2](02-anatomy-of-a-migration-run.md) touches this).