Share
Embed
Flyway vs Liquibase: Same Schema, Two Engines, One Measured Diff
One Spring Boot 4 application migrates two H2 databases, one with Flyway and one with Liquibase, then diffs the schemas at runtime. The schemas match; the trade-offs are in discovery, rollback, history and licensing. Code: https://github.com/wallaceespindola/flyway-vs-liquibase-db-migrations
Wallace Espindola
November 21, 2026
Transcript
25 slides
-
Flyway vs Liquibase Same Schema, Two Engines, One Measured Diff
Wallace Espindola, Solution Architect [email protected] linkedin.com/in/wallaceespindola | github.com/wallaceespindola -
The problem: schema drift Application code is versioned and reviewed;
the schema often is not "Run this script on prod" in a chat is not a deployment process Dev has the column, staging does not, prod has it with another type Nobody can say which changes a database has actually seen The root cause: DDL treated as an operational act instead of source code. Flyway vs Liquibase 2 -
What any migration tool must give you 1 2 3
4 Ordering: changes apply in a defined sequence, once, everywhere Bookkeeping: a table in the database records what ran Integrity: a checksum catches edits to applied changes Automation: migrations run at startup or in the pipeline Flyway and Liquibase both deliver all four. The rest of this talk is about how. Flyway vs Liquibase 3 -
Flyway: the filename is the configuration V1__create_category_table.sql : V versioned,
1 order, rest is the description R__ marks a repeatable migration, re-applied when its checksum changes Scan a location, sort by version, run what flyway_schema_history lacks Raw SQL in the target dialect, no abstraction layer No changelog file, no include list: discovery is a directory scan plus an ordering rule. Flyway vs Liquibase 4 -
Bootstrapping Flyway @Bean(name = "flyway", initMethod = "migrate") public Flyway
flyway(@Qualifier(DATA_SOURCE) DataSource dataSource) { return Flyway.configure() .dataSource(dataSource) .locations(locations) .baselineOnMigrate(baselineOnMigrate) .validateOnMigrate(true) .cleanDisabled(true) .load(); } config/FlywayConfig.java (log line trimmed) Flyway vs Liquibase 5 -
Liquibase: changesets in a declared changelog A changeset is the
unit: id + author + file identify it XML, YAML, JSON or SQL, all first-class and mixable A master changelog lists every file: order is declared, not inferred Abstract tags; Liquibase emits the dialect at runtime Per changeset: preConditions , context , labels , rollback , runOnChange The abstraction is the product: it buys portability and costs review readability. Flyway vs Liquibase 6 -
Bootstrapping Liquibase @Bean("liquibase") public SpringLiquibase liquibase(@Qualifier(DATA_SOURCE) DataSource dataSource) { SpringLiquibase
liquibase = new SpringLiquibase(); liquibase.setDataSource(dataSource); liquibase.setChangeLog(changeLog); liquibase.setContexts(contexts); liquibase.setDefaultSchema(defaultSchema); liquibase.setDropFirst(false); liquibase.setShouldRun(true); return liquibase; } config/LiquibaseConfig.java (log line trimmed) Flyway vs Liquibase 7 -
The experiment: two databases, one schema Each engine owns its
own H2 file. Neither ever touches the other. Flyway vs Liquibase 8 -
No query before the migration finishes @Bean(JDBC_TEMPLATE) @Primary @DependsOn("flyway") public
JdbcTemplate flywayJdbcTemplate(@Qualifier(DATA_SOURCE) DataSource dataSource) { return new JdbcTemplate(dataSource); } config/FlywayConfig.java; the Liquibase side uses @DependsOn("liquibase") Two of every JDBC bean, so @Qualifier is not optional Remove @DependsOn and a query can hit an unmigrated database Flyway vs Liquibase 9 -
A paired translation table: 6 vs 7 V5 does column
and backfill in one script; Liquibase splits them into 005 and 005b . Flyway vs Liquibase 10 -
The same table: V1 SQL vs 001 XML CREATE TABLE
category ( id BIGINT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100) NOT NULL, CONSTRAINT uk_category_name UNIQUE (name) ); <createTable tableName="category"> <column name="id" type="BIGINT" autoIncrement="true"> <constraints primaryKey="true" primaryKeyName="pk_category" nullable="false"/> </column> <column name="name" type="VARCHAR(100)"> <constraints nullable="false" unique="true" uniqueConstraintName="uk_category_name"/> </column> </createTable> Flyway vs Liquibase 11 -
Flyway V5: the expand step in plain SQL ALTER TABLE
product ADD COLUMN active BOOLEAN NOT NULL DEFAULT TRUE; UPDATE product SET active = FALSE WHERE stock_quantity = 0; CREATE INDEX idx_product_active ON product (active); V5__add_product_active_flag.sql (header comment trimmed) Readable in five seconds, no extra vocabulary No way to undo it in Community: reverting means writing V6 Flyway vs Liquibase 12 -
Liquibase 004: preconditions and rollback <changeSet id="004-add-product-audit-table" author="wallaceespindola" context="demo"> <preConditions
onFail="MARK_RAN" onFailMessage="product table missing, skipping audit table"> <tableExists tableName="product"/> </preConditions> <comment>Add the product audit trail, guarded by a precondition</comment> <createTable tableName="product_audit"> ... </createTable> <rollback> <dropIndex tableName="product_audit" indexName="idx_product_audit_product"/> <dropTable tableName="product_audit"/> </rollback> </changeSet> 004-add-product-audit-table.xml (columns, index and backfill trimmed) Flyway vs Liquibase 13 -
What each engine records flyway_schema_history DATABASECHANGELOG Identity version , one
ordered namespace id + author + filename Author not recorded mandatory Checksum CRC32 MD5 Execution time milliseconds per migration not recorded Contexts, labels, deployment id n/a recorded Locking database-level lock DATABASECHANGELOGLOCK table Flyway tells you which migration is slow. Liquibase tells you who wrote it. Flyway vs Liquibase 14 -
Reading the history: an API vs a table MigrationInfo[] all
= flyway.info().all(); service/FlywayHistoryService.java: applied and pending, ordered, as objects SELECT ID, AUTHOR, FILENAME, DATEEXECUTED, ORDEREXECUTED, EXECTYPE, MD5SUM, DESCRIPTION, COMMENTS, CONTEXTS, LABELS, DEPLOYMENT_ID FROM DATABASECHANGELOG ORDER BY ORDEREXECUTED service/LiquibaseHistoryService.java: SpringLiquibase exposes no status object, so query the table Flyway vs Liquibase 15 -
The measured result "schemasEquivalent": true, "schemaDifferences": [] GET /api/v1/comparison on
the running application Both sides: category , product , product_audit , view v_product_catalog Columns compared as TABLE.COLUMN:TYPE : zero differences Indexes deliberately ignored: H2 names constraint-backing indexes differently Same schema either way. The choice is about process, not outcome. Flyway vs Liquibase 16 -
18 capabilities, scored Edge Capabilities Flyway (6) learning curve, discovery,
review ergonomics, merge conflicts, execution timing, status API Liquibase (8) change formats, portability, rollback, conditional execution, drift diff, bookkeeping, authorship, licensing of advanced features Tie (4) repeatable changes, concurrency, Spring Boot integration, checksums Flyway wins where humans read changes. Liquibase wins where machines run them across environments. Flyway vs Liquibase 17 -
Rollback: matters less than the marketing says Flyway Community: no
undo, revert with a new forward migration Flyway undo exists only in the paid editions Liquibase: <rollback> sits next to the change; rollbackCount 1 is supported In production, rolling back after data is written destroys data Rollback pays off in pre-production: rehearsals, resets, local iteration Expand, migrate, contract makes forward-only recovery viable on either tool. Flyway vs Liquibase 18 -
Licensing changed in 2025 Liquibase 5.0: Community moved from Apache
2.0 to the Functional Source License FSL converts to Apache 2.0 after two years; Liquibase calls it source available Contributors now sign a CLA; the commercial product is Liquibase Secure Flyway: undo, dry-run and drift detection stay in the paid editions Run your legal review on the version you ship, not on the one you remember. Flyway vs Liquibase 19 -
Portability is real, and bounded - sql: comment: Check constraints
have no portable Liquibase tag, so raw SQL is used here sql: >ALTER TABLE product ADD CONSTRAINT ck_product_price_positive CHECK (price >= 0); ALTER TABLE product ADD CONSTRAINT ck_product_stock_non_negative CHECK (stock_quantity >= 0) 002-create-product-table.yaml (trimmed) Portable only while you stay inside the tag vocabulary How many times has your team changed database engine? Flyway vs Liquibase 20 -
Review and merge conflicts Flyway diffs are SQL: every reviewer
already reads them Two branches adding V6__ collide on the filename: loud and immediate Liquibase diffs are tags: reviewers must know what each one emits Two branches appending to the master changelog conflict in the include list Git can auto-merge that list in the wrong order; nothing fails until deploy If your team is large and merges often, weigh this row heavily. Flyway vs Liquibase 21 -
Choose Flyway when You target one database and expect to
keep it Your team is fluent in SQL and wants diffs it can read at a glance Forward-only migration fits your release process You want the smallest thing between intent and executed statement The most common mistake on the other side: buying portability you never use. Flyway vs Liquibase 22 -
Choose Liquibase when You ship to several database engines, or
customers pick the engine You need rollback, preconditions or contexts as first-class features Auditors want author and deployment id inside the database You want diff and rollback without a commercial licence, under FSL terms Whichever you pick: use it for everything, and never apply DDL by hand again. Flyway vs Liquibase 23 -
Run it yourself git clone https://github.com/wallaceespindola/flyway-vs-liquibase-db-migrations cd flyway-vs-liquibase-db-migrations mvn spring-boot:run
Endpoint Shows /api/v1/comparison full report with schemasEquivalent /api/v1/comparison/features the 18-row feature matrix /api/v1/migrations both engines' history side by side /swagger-ui.html , /h2-console API docs and both databases Flyway vs Liquibase 24 -
Thank You Which tool does your team run, and which
row decided it? github.com/wallaceespindola/flyway-vs-liquibase-db-migrations Wallace Espindola, Solution Architect linkedin.com/in/wallaceespindola | speakerdeck.com/wallacese