Flyway — Version Control for Your Database

Introduction

Flyway brings version control discipline to database schemas. Each migration is a versioned SQL file that Flyway applies in order, tracking which migrations have run in a metadata table. This ensures every environment — development, staging, production — has an identical schema without manual intervention.

What Flyway Does

• Applies versioned SQL or Java migrations in sequential order with automatic conflict detection
• Tracks applied migrations in a schema history table for audit and rollback awareness
• Validates that previously applied migrations have not been modified to prevent drift
• Supports repeatable migrations for views, procedures, and reference data that change over time
• Provides baseline support to adopt Flyway on existing databases without re-running history

Architecture Overview

Flyway reads migration files from a configured location, sorts them by version number, and compares them against the schema history table in the target database. Pending migrations are executed in a transaction where the database supports transactional DDL. After each migration, a checksum is stored so Flyway can detect unauthorized modifications on future runs. The tool connects via JDBC drivers for broad database compatibility.

Self-Hosting & Configuration

• Available as a standalone CLI, Docker image, or plugin for Maven, Gradle, and SBT
• Configure via flyway.conf file, environment variables, or command-line arguments
• Set locations to point to SQL migration directories, classpaths, or cloud storage
• Use placeholders for environment-specific values like schema names or table prefixes
• Enable callbacks for pre- and post-migration hooks for custom logic

Key Features

• Checksum validation ensures migration integrity across all environments
• Undo migrations (Teams edition) allow controlled rollback of applied changes
• Dry-run mode previews SQL that would be executed without applying it
• Cherry-pick specific migrations to apply or skip during targeted deployments
• Native integration with Spring Boot auto-configuration for Java applications

Comparison with Similar Tools

• Liquibase — XML/YAML/JSON changeset model; more flexible formats but steeper learning curve
• golang-migrate — Lightweight Go CLI and library; fewer database drivers and no checksum validation
• Atlas — Declarative schema approach with drift detection; newer with smaller ecosystem
• dbmate — Simple Go tool focused on SQL migrations; no Java integration or checksum tracking
• Alembic — Python-based migration tool tied to SQLAlchemy; best for Python-only projects

FAQ

Q: Does Flyway support rollbacks? A: The Community edition supports manual rollback via custom down scripts. The Teams edition adds automated undo migrations.

Q: Can I use Flyway with NoSQL databases? A: Flyway is designed for relational databases accessed via JDBC. It supports MongoDB in newer versions with limited features.

Q: How do I handle migration conflicts in a team? A: Use the outOfOrder option to allow later-versioned migrations to run even if earlier ones were added after deployment.

Q: Is there a GUI for Flyway? A: Flyway Desktop provides a visual interface for comparing schemas, generating migrations, and managing baselines.

Sources

• https://github.com/flyway/flyway
• https://documentation.red-gate.com/flyway