Flyway

Flyway is a database migration tool that manages schema changes using versioned scripts.

It makes database changes repeatable, auditable, and automatable across environments.

Prevents ad-hoc/manual schema drift and inconsistent database states.

A script that changes database schema (and sometimes reference data) in controlled steps.

A migration with ordered version prefix, applied once in sequence.

Migration re-applied when its checksum/content changes.

V1__init.sql, V2__add_user_table.sql.

R__views.sql or R__functions.sql.

Applied migrations metadata in a schema history table.

Internal table (default often flyway_schema_history) recording applied migrations.

It is source of truth for migration state and ordering.

Hash of migration content used to detect unexpected changes.

Changing them breaks auditability and causes checksum validation failures.

Applies pending migrations in order.

Checks applied migrations against available files and checksums.

Shows migration status (applied, pending, failed, etc.).

Drops objects in configured schemas (destructive).

Usually disabled/forbidden in production.

Initializes schema history at a baseline version for existing databases.

Onboard legacy DBs without replaying all historical scripts.

Fixes schema history metadata issues (e.g., checksums/failed markers) carefully.

After understanding root cause; not as blind fix.

Applying lower version migration after higher version already applied.

No, only controlled exceptional situations.

Path(s) where Flyway scans SQL/Java migrations.

Yes, via migration classes for complex logic.

SQL is transparent/simple; Java handles complex conditional logic.

Migration executed within transaction if DB supports DDL transactions.

No, behavior varies by database engine.

Rollback/failure semantics differ across engines.

Scripts written to avoid failure if rerun accidentally (where appropriate).

No, ordering/history guarantees are primary; idempotency is extra safety.

Variable substituted in migration scripts at runtime.

Environment-specific values without duplicating scripts.

Usually V for versioned and R for repeatable migrations.

Typically double underscore between version and description.

Improve readability, review quality, and audit trails.

Typically at startup or CI/CD deploy stage before app serves traffic.

Boot can auto-run Flyway migrations on startup when configured.

Editing old applied migration instead of creating a new one.

Putting risky data backfills and schema changes in one untested script.

Easier review, testing, rollback planning, and incident recovery.

Schema before dependent code paths requiring new schema.

Prefer new corrective migrations over editing history.

Environment schemas diverge unintentionally.

Consistent scripted migrations + validation/history tracking.

Review SQL plan and test on staging before production.

Performance/locking behavior may differ from small dev datasets.

Backups, staging test, validate, and rollback/mitigation plan.

Application team co-owns schema evolution with DBA/platform guidance.

Promote same migration files across environments unchanged.

Breaks history consistency and reproducibility.

Run validate/migrate on ephemeral DB in pipeline.

Versioned scripts, validation gates, tested backups.

Treat DB schema as code with reviews, tests, and automation.

Backward-compatible phased schema change for zero-downtime deploys.

Add new columns/tables/indexes without breaking old code.

Remove deprecated schema only after all code paths migrated.

Supports rolling/canary deployments with mixed app versions.

Application release depends on fragile schema timing/order.

Backward-compatible DB changes and feature flags.

Extended locks/downtime impacting availability.

Chunking, online DDL tools/features, off-peak scheduling.

DDL/DML blocks application traffic or vice versa.

May lock table or consume heavy resources depending DB/options.

Use concurrent/online index options where supported.

Populate new columns/tables from existing data.

Independent rollback/control and reduced blast radius.

Views, stored procedures, functions, grants definitions.

Checksum/content change causes reapplication.

Applying selected migrations to specific env (special cases).

Can create version graph inconsistencies across environments.

Upper version limit to migrate up to.

Controlled phased rollout and safer release orchestration.

Auto-baseline non-empty schema on first migrate (use carefully).

Can mask incorrect initialization in wrong environment.

Allowing transactional and non-transactional migrations together.

Failure semantics become harder to reason about.

Applying multiple pending migrations in one transaction where supported.

Atomicity vs larger rollback scope/lock duration.

Configurable tolerance for certain validation differences.

No, use narrowly with explicit governance.

Runtime substitution in SQL scripts for configurable tokens.

Using placeholders for structural logic that should be explicit migrations.

Configure Flyway schemas/default schema explicitly per environment.

Avoid accidental object creation in wrong schema.

Put history table in controlled durable schema.

Applied script content differs from current artifact.

Investigate root cause; prefer new migration or controlled repair after verification.

Fix script/versioning issue, assess partial changes, then repair/retry safely.

Upsert-like controlled DML for seed/reference rows.

Reference data can be versioned; large mutable business data needs dedicated jobs.

Hook scripts/actions before/after migrate/each migration events (edition/support dependent).

Audit logging, guard checks, session settings.

Hidden side effects complicate debugging.

Static checks for SQL style/safety/performance patterns.

Catch risky statements before runtime.

Lock impact, index strategy, rollback plan, compatibility, execution time.

Run migration on subset/replica/shadow before full production rollout.

Apply migrations to schema copy to validate behavior.

Compare actual schema structure with expected model periodically.

Manual DB changes or out-of-band tools can bypass process.

Validate -> migrate test DB -> integration tests -> package/deploy gates.

Temporary database spun up for migration/test run and discarded.

Reproducible clean-state verification each pipeline run.

Multiple teams generating versions concurrently.

Timestamp-based versions or allocation conventions/tooling.

Lower collision risk across parallel branches.

Can reorder/conflict versions requiring careful reconciliation.

Massive “catch-all” migration touching many domains at once.

Bounded-context-specific incremental scripts.

Primarily roll-forward with corrective migration.

Safer audit trail and fewer unknowns than reversing complex live changes.

High-risk ops with rehearsed reversible steps (DB-specific).

Track migration duration, failures, lock waits, and deployment correlation.

Expected max migration time/error budget during deploy window.

Least-privilege migration user, audited access, secret rotation.

Principle of least privilege and safer operational boundaries.

Team can execute zero-downtime schema changes repeatedly.

Design every migration for compatibility, observability, and recovery.

Standards, approvals, tooling, and SLOs for schema delivery across teams.

Formal review for high-risk DDL/data operations.

Estimate impacted tables, services, queries, and peak traffic exposure.

Engine-specific tools/features minimizing locks for big-table alterations.

Flyway orchestrates versioning; specialized tools execute safer heavy DDL.

Add new column, dual-write/read migrate, backfill, switch reads, drop old.

Application compatibility and lock behavior may break rolling deploys.

Temporary writes to old and new schema fields for safe transition.

Inconsistency if write paths diverge; requires monitoring/reconciliation.

Limiting batch size/rate to reduce production load impact.

Track progress markers for resumable long-running data migrations.

Safe reruns without duplicating/corrupting data.

Both app versions must work against same evolving schema.

Forward-compatible phased migrations before traffic cutover.

Run schema changes compatible with old/new code; verify metrics before expand.

Coordinating schema timing with replication and staggered deployments.

DDL/DML spikes can delay replicas and stale reads.

Throttle changes, monitor lag, schedule carefully, route critical reads appropriately.

Apply consistent versioning across many shards safely.

Orchestrated rolling shard batches with health gates.

Migrate isolated tenant schemas incrementally to reduce risk.

Limit impact scope so one failure doesn’t affect all tenants/regions.

Automated checks that app queries remain valid across migration states.

Rolling deploys run mixed versions temporarily.

New indexes/stats/schema changes may worsen critical query plans.

Pre-prod load tests and plan baselines on realistic data.

Per-statement timing, lock metrics, replication lag, app error/latency correlation.

Abort/pause rollout when SLO thresholds degrade.

Schema rollbacks can be unsafe; prefer halt + roll-forward mitigation.

Auditable approvals, traceable artifacts, and separation of duties.

Cryptographically verifiable migration bundle integrity.

Tampered scripts or unreviewed changes entering deploy pipeline.

Protected branches, signed commits/artifacts, CI policy gates.

Migration role gets only required DDL/DML rights per schema and time window.

Controlled emergency access with audit and post-incident review.

Detect unauthorized schema differences and codify corrective migrations.

Announce, dual-support, usage telemetry, retire old objects safely.

Know when columns/tables/views are safe to drop.

Treating Flyway as mere startup step without DB engineering discipline.

Provide templates, linting, guardrails, and migration runbooks.

Practice failure scenarios: lock contention, timeout, partial apply, recovery.

Backups are only useful if restore is tested.

Defines acceptable data loss and recovery time objectives for incidents.

Every migration must have tested forward-fix and incident response plan.

Evaluate lock/time/query impacts on production-like data before rollout.

Control who can change schema, how, and with what audit trail.

Promote immutable reviewed migration artifacts consistently across environments.

Design app and schema for backward-compatible evolution.

Observe migrations as first-class production events with SLO guardrails.

Flyway excellence is disciplined, reversible-in-practice, low-downtime schema evolution.