Spring Boot Database Migration using Flyway

Flyway detected that the file no longer matches what was applied. The right fix depends on where the old version ran:

• It ran on shared or production databases: undo your edit, restoring the original file, and put the change in a new migration.
• It ran only on your own local database: either recreate your local database, or tell Flyway to accept the new checksum with the repair command.

# With the Flyway Maven plugin configured for your local database
./mvnw flyway:repair

Never use repair on production just to silence the error. The error is protecting you from databases that differ without anyone knowing.

In the free edition, Flyway does not undo migrations automatically. The common approach is to roll forward: write a new migration that reverses the change.

-- V7__add_discount_column.sql
ALTER TABLE books ADD COLUMN discount NUMERIC(5,2);

-- V8__remove_discount_column.sql  (the "rollback")
ALTER TABLE books DROP COLUMN discount;

Rolling forward keeps the history honest: every database goes through the same steps. Paid editions offer undo files (U prefix), but even then, many teams prefer forward fixes plus regular database backups.

Flyway refuses to start when two files share a version. Before merging, the second developer renames their file to the next free number. To make collisions rare in busy teams:

• Use timestamp versions, such as V2026_10_04_1015__add_genre.sql, which are almost never identical.
• Check for pending migrations from main before merging your branch.

If an older version arrives after newer ones have already run, Flyway skips it by default. Setting spring.flyway.out-of-order=true lets it run, but use that carefully, because the order then differs between databases.

Only slightly when nothing is pending. Flyway reads the history table, compares checksums and finishes in a fraction of a second.

Startup is slow only while new migrations run, and only as slow as their SQL. A migration that adds an index to a table with millions of rows may take minutes. Run such heavy migrations during a quiet period, or consider running Flyway as a separate step before deploying the application (see the next question).

Yes. Many teams run migrations as a separate deployment step, so a failure stops the release before any new code starts:

• The Flyway Maven or Gradle plugin: ./mvnw flyway:migrate.
• The Flyway command-line tool, or its Docker image, in your deployment pipeline.
• A Kubernetes job or init container that runs before the application pods.

If you migrate this way, set spring.flyway.enabled=false in the application, or leave it on as a harmless check, since nothing will be pending.

Only one of them migrates. Flyway takes a lock in the database before applying migrations; the other instances wait until it is released, then see that the schema is already up to date and continue.

This makes it safe to start several instances, for example several Kubernetes pods. Long migrations will make the waiting instances start slowly, so keep migrations short, or run them as a separate step.

Use the {vendor} placeholder in the location. Spring Boot replaces it with the detected database type:

spring.flyway.locations=classpath:db/migration/common,classpath:db/migration/{vendor}

db/migration/common/V1__create_books_table.sql      <- works everywhere
db/migration/postgresql/V2__add_search_index.sql    <- PostgreSQL only
db/migration/h2/V2__add_search_index.sql            <- H2 only

Keep this to a minimum: two versions of the same change can drift apart. Testing against the real production database type, as shown in section 15, usually removes the need for it.

Reference data that every environment needs belongs in a normal versioned migration:

-- V9__insert_book_categories.sql
INSERT INTO categories (code, name) VALUES
    ('FIC', 'Fiction'),
    ('SCI', 'Science'),
    ('HIS', 'History');

Data that only makes sense in development, such as sample books, belongs in a separate location used only by the dev profile, as shown in section 13. Never put test users or fake orders in migrations that run in production.

During a rolling deployment, old and new application versions run at the same time. A direct rename breaks the old version immediately. Use the expand and contract approach, spread over several releases:

1. Expand: add the new column and copy the data. Both columns exist.
2. Migrate code: release code that writes to both columns and reads the new one.
3. Contract: once no old version is running, drop the old column in a later migration.

-- Release 1: V10__add_published_date.sql
ALTER TABLE books ADD COLUMN published_date DATE;
UPDATE books SET published_date = published_on;

-- Release 3: V12__drop_published_on.sql
ALTER TABLE books DROP COLUMN published_on;

clean drops every object in the managed schemas: tables, views, data, everything. It is handy for resetting a local development database, and catastrophic anywhere else.

That is why recent versions disable it by default (spring.flyway.clean-disabled=true). Keep it that way in every shared configuration. If you need a fresh local database, it is often simpler to recreate the database container than to enable clean.

Yes, in most cases. When the migration and the code that needs it are in the same commit:

• Reviewers see the schema change next to the code that uses it.
• Every build of the application contains exactly the migrations it expects.
• Tests run the migrations automatically.

A separate repository makes sense mainly when a database is shared by several applications, which is itself something to avoid where possible: in microservices, each service should own its own database.

Yes. List them, and Flyway creates any that are missing and records its history in the first one:

spring.flyway.schemas=library,reporting

-- V11__create_reporting_tables.sql
CREATE TABLE reporting.monthly_loans (
    month       DATE    PRIMARY KEY,
    loans_count INTEGER NOT NULL
);

Inside migrations, use schema-qualified names, such as reporting.monthly_loans, for objects outside the default schema.

Three places to look:

• The scripts themselves in db/migration, which are the exact SQL that ran.
• The history table, which records each migration, who ran it, when, how long it took and whether it succeeded.
• Debug logging for detailed output during a run:

logging.level.org.flywaydb=DEBUG

SELECT installed_rank, version, description, installed_by, installed_on, execution_time, success
FROM flyway_schema_history
ORDER BY installed_rank;

At startup, after Flyway has migrated, Hibernate compares your entities with the real database and stops the application if they do not match. It checks that:

• Every entity’s table exists.
• Every mapped field has a column.
• Column types are compatible with the field types.

It does not change anything, and it ignores extra columns that no entity maps. This catches the classic mistake of adding a field to an entity but forgetting the migration, at startup instead of at the first failing query.

Not with Flyway: it uses plain SQL files and, when needed, Java classes. That is a deliberate design choice, because SQL is what your database actually runs, so there is nothing to translate or learn.

If you want database-independent change definitions in XML, YAML or JSON, Liquibase is built around that approach and is equally well supported by Spring Boot. The comparison table in section 16 helps you choose.

Adding a NOT NULL column without a value fails, because existing rows would break the rule. Do it in steps:

-- 1. Add the column as nullable
ALTER TABLE books ADD COLUMN language VARCHAR(10);

-- 2. Fill existing rows
UPDATE books SET language = 'en' WHERE language IS NULL;

-- 3. Now enforce the rule
ALTER TABLE books ALTER COLUMN language SET NOT NULL;

For a simple constant, many databases also accept ADD COLUMN language VARCHAR(10) NOT NULL DEFAULT 'en' in one statement. On very large tables, updating every row can take a long time, so test the migration on a copy of production-sized data first.

It depends on your database:

Either way, Flyway records the failure and refuses to continue until the problem is resolved. On databases without transactional schema changes, keep each migration to one schema change, so a failure never leaves a half-finished state, and test migrations before they reach production.

The Community edition is free and open source under the Apache 2.0 license, and includes everything covered in this tutorial: versioned and repeatable migrations, Java migrations, baselines, placeholders and Spring Boot integration.

Paid editions, now owned by Redgate, add features such as undo migrations, dry runs that show SQL without executing it, and extra database support. Most Spring Boot projects never need them.

Yes, but only carefully. A common approach once every environment is up to date:

1. Export the current schema as a single script, for example V200__baseline.sql.
2. Move the old migrations out of the active location, keeping them in version control history.
3. On existing databases, set baseline-version=200 with baseline-on-migrate, so they skip the new baseline.
4. New databases run the single baseline instead of hundreds of files.

Do it only when the number of files really causes slow builds or tests. Old migrations are otherwise harmless, and keeping them is simpler.

Very much. In microservices, each service should own its own database, and Flyway fits that perfectly: each service carries its own migrations and updates its own schema when it is deployed, independently of every other service.

This keeps services decoupled: no shared schema, no coordination of database changes across teams. See the Database per Service Pattern for the reasoning behind this design.