Java.DBMigrationTools.What is a Flyway baseline and when would you use it?

Short definition (what you say first)

A Flyway baseline marks an existing database schema as a starting point so Flyway can begin managing migrations without reapplying old ones.

📌 One-liner:

“Baseline tells Flyway: assume the schema up to this version already exists.”

---

The problem baseline solves

Imagine this situation:

• You have a legacy database
• Tables already exist
• No Flyway history table
• You want to start using Flyway without dropping anything

If you run flyway migrate directly:

• Flyway will try to run V1__create_tables.sql
• ❌ Boom — tables already exist

👉 Baseline prevents that

---

What flyway baseline actually does

When you run:

flyway baseline

Flyway:

1. Creates flyway_schema_history
2. Inserts a baseline marker row
3. Marks all migrations below the baseline version as applied
4. Does NOT execute any SQL

Important:

• No schema changes
• Metadata only

---

Baseline version & description

Defaults:

• baselineVersion = 1
• baselineDescription = << Flyway Baseline >>

Configurable:

flyway.baselineVersion=5
flyway.baselineDescription=legacy schema

Result:

• Flyway will only apply migrations V6+

📌 Interview phrase:

“Baseline defines the first migration Flyway is allowed to execute.”

---

Typical real-world use cases (this matters)

✅ 1. Introducing Flyway to an existing database

Most common case.

• DB already in production
• Schema managed manually or by scripts
• You want Flyway from now on

---

✅ 2. Brownfield systems

• Old monolith
• Years of unmanaged schema drift
• Baseline at “current reality”

---

✅ 3. Environment alignment

• Prod already exists
• New environments start clean
• Baseline ensures consistent starting point

---

What baseline is NOT

This is where people fail interviews.

❌ Not a migration
❌ Not a rollback
❌ Not a schema sync
❌ Not something you run repeatedly

📌 Strong sentence:

“Baseline is a one-time operation per database.”

---

baselineOnMigrate (important variant)

Config option:

flyway.baselineOnMigrate=true

Behavior:

• If schema exists and
• flyway_schema_history is missing
• Flyway automatically baselines before migrate

⚠️ Use carefully:

• Safe for controlled environments
• Dangerous if used blindly in prod

Senior wording:

“baselineOnMigrate trades safety for convenience.”

Risks & best practices

⚠️ Risks

• You can lie to Flyway about schema state
• Past migrations are no longer reproducible
• Drift before baseline is untracked forever

✅ Best practices

• Baseline at a clear, documented version
• Commit migrations starting after baseline
• Never baseline repeatedly
• Never baseline to hide problems

---

Interview-ready answer (perfect)

2–3 sentences:

“A Flyway baseline marks an existing database schema as the starting point for migration tracking without executing historical migrations. It’s typically used when introducing Flyway to a legacy or already-populated database. After baselining, Flyway will only apply migrations newer than the baseline version.”