Java.DBMigrationTools.What is a Flyway baseline?

A Flyway baseline tells Flyway:

“Start tracking from this version — assume all migrations before this are already applied.”

It lets you start using Flyway with an existing database without re-running old scripts.

---

🔍 Detailed Explanation

Imagine you have a production database with many tables, but you’re just now introducing Flyway.

If you add versioned migration files like:

V1__init_schema.sql
V2__add_users.sql

Flyway will try to apply them from scratch — and crash, because the tables already exist.

✅ Solution: Use a baseline

🛠️ How to Baseline a Database

You run:

flyway baseline

Or in Java:

flyway.baseline();

Or configure it via properties:

flyway.baselineVersion=1
flyway.baselineDescription=Baseline existing schema
flyway.baselineOnMigrate=true

This creates the flyway_schema_history table with a starting version (e.g. 1), without running any scripts.

💡 When to Use a Baseline

Scenario	Should You Baseline?
Existing schema, no Flyway yet	✅ Yes
Legacy systems with hundreds of tables	✅ Yes
Fresh, empty database	❌ No — start with V1

---

🧾 What Gets Recorded?

In flyway_schema_history:

installed_rank	version	description	success
1	1	Baseline existing schema	✅

Now Flyway knows to start from V2 and ignore earlier scripts.

---

⚠️ Important Notes

• You can only baseline before any migrations are applied
• If the history table exists, baseline() will fail unless it was empty
• Useful with baselineOnMigrate=true for auto-baselining on first migration

---

📌 Key Takeaways

✅ flyway baseline sets the starting point for tracking in a live schema
✅ Prevents Flyway from reapplying already existing changes
✅ Ideal for introducing Flyway into production projects
✅ Sets up versioning safely without touching existing data