Flyway Liquibase — Cheat Sheet

Tags: flyway, liquibase, database, migrations, sql, devops, ci-cd

Level: intermediate

TL;DR: Database schema migration tools that treat database structures like code. Flyway is simpler and SQL-driven, while Liquibase is more flexible, database-agnostic, and relies on structural changelogs.

Key concepts

Both tools version-control database schemas to ensure consistency and repeatability across environments.

They track executed migrations using a dedicated metadata table (flyway_schema_history for Flyway, DATABASECHANGELOG for Liquibase).

Migrations run automatically during application startup (e.g., via Spring Boot) or step-by-step in CI/CD pipelines.

Flyway: Relies on strict file naming conventions (e.g., V1_1__Create_table.sql) and plain SQL scripts.

Flyway: Ideal for teams highly comfortable with SQL and targeting a single specific database engine.

Liquibase: Uses changesets defined in XML, YAML, JSON, or SQL formats.

Liquibase: Database-agnostic; it abstracts SQL commands so the same changeset can deploy to PostgreSQL, MySQL, or Oracle.

Liquibase: Offers robust built-in rollback support using <rollback> tags in changesets.

Typical questions and ready answers

Q: What is the main difference between Flyway and Liquibase?R: Flyway is SQL-centric and highly opinionated with file naming, making it simpler if you only use one database type. Liquibase uses abstract changesets (XML/YAML), making it database-agnostic and generally better for complex out-of-the-box rollbacks.

Q: What happens if you modify a migration script that has already been applied?R: The tool will detect a checksum mismatch and the migration will fail, halting the application startup. I would need to either revert the script, write a new forward-migration, or manually run a repair command if the change was safe and intentional.

Q: How do you handle rollbacks?R: In Liquibase, I explicitly write rollback tags in the changeset. In Flyway Community, rollbacks are manual via new forward scripts, whereas Flyway Teams supports specific U (Undo) scripts.

Pitfalls and common mistakes

Modifying historically applied migration files instead of creating new ones, causing checksum validation failures.

Failing to test downgrades or rollback scripts locally before deploying to staging/production.

Using Liquibase XML abstractions for highly complex, database-specific optimizations where raw SQL would be clearer and more performant.

Manually altering the database schema outside of the migration tools, causing state drift.

Snippets and commands

# Flyway basic commands (CLI)
flyway info
flyway migrate
flyway repair

# Liquibase basic commands (CLI)
liquibase status
liquibase update
liquibase rollbackCount 1

SQL

```-- Flyway naming convention example (V1_0_1__Create_users.sql)

CREATE TABLE users (

id INT PRIMARY KEY,

username VARCHAR(50) NOT NULL

);

<!-- Liquibase changeset example -->

<changeSet id="1" author="umberto">

<createTable tableName="users">

<column name="id" type="int">

<constraints primaryKey="true"/>

</column>

<column name="username" type="varchar(50)"/>

</createTable>

<rollback>

<dropTable tableName="users"/>

</rollback>

</changeSet>

```