Understanding Flyway: Database Migration Tool Overview and Spring Integration

Flyway is a database migration (migration) tool that helps keep databases synchronized across different environments, reduces manual operations, prevents ordering errors, and minimizes the chance of omissions. It can be integrated into projects and works with Spring, automatically executing database scripts during releases.

The traditional deployment process involves developers packaging the application, DBA reviewing and executing database upgrade scripts, and deployment personnel handling application deployment. After introducing Flyway, the deployment process is simplified: developers package the application, deployment personnel replace the package, and Flyway automatically runs the upgrade scripts.

Flyway Introduction

Concept: Flyway is a database version‑control tool independent of any specific database, managing and tracking schema changes much like Git manages code, allowing multiple developers to coordinate SQL scripts.

Supported Databases: Oracle, SQL Server, SQL Azure, DB2, DB2 z/OS, MySQL (including Amazon RDS), MariaDB, Google Cloud SQL, PostgreSQL (including Amazon RDS and Heroku), Redshift, Vertica, H2, HSQL, Derby, SQLite, SAP HANA, solidDB, Sybase ASE, Phoenix.

SQL Script Naming Convention: V<version>__<description>.sql (e.g., V2017.9.30__Update.sql ).

Default Script Location: db/migration directory under the project source folder.

Basic Commands (6): migrate, clean, info, validate, baseline, repair.

Flyway Commands

Migrate: mvn flyway:migrate – migrates the database to the latest version, creating the schema history table if it does not exist. It scans the classpath or filesystem for available migrations and applies any pending ones. Typically run at application startup.

Example: Database at version 5, available migrations up to version 9 → Flyway applies versions 6, 7, 8, and 9 sequentially.

Clean: mvn flyway:clean – removes all objects (tables, views, procedures, etc.) giving a fresh start; should never be used on production databases.

Info: mvn flyway:info – prints detailed information about all migrations, showing which have been applied and which are pending.

Validate: mvn flyway:validate – checks for mismatched or modified migrations; validation failures abort migration.

Undo: mvn flyway:undo – reverts the most recently applied migration.

Baseline: mvn flyway:baseline – creates a baseline version for an existing database when no Flyway history table is present.

Repair: mvn flyway:repair – repairs the Flyway schema history table, removing failed migrations (where supported) and realigning checksums, descriptions, and types.

Using Flyway with Spring

pom.xml Dependency:

<!-- flyway -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>5.2.4</version>
</dependency>

Configuration Parameters (excerpt):

flyway.baseline-description   // description for baseline version
flyway.baseline-on-migrate    // true/false, auto‑baseline on migrate
flyway.baseline-version       // default 1
flyway.check-location         // true/false, verify script location
flyway.clean-on-validation-error // true/false, auto‑clean on validation error
flyway.enabled                // true/false, enable Flyway
flyway.encoding               // default UTF‑8
flyway.ignore-failed-future-migration // true/false
flyway.init-sqls              // SQL to run on init
flyway.locations              // default db/migration
flyway.out-of-order           // true/false, allow out‑of‑order migrations
flyway.password               // DB password
flyway.placeholder-prefix     // default ${
flyway.placeholder-replacement // true/false
flyway.placeholder-suffix      // default }
flyway.placeholders.[name]    // placeholder values
flyway.schemas                // target schemas
flyway.sql-migration-prefix   // default V
flyway.sql-migration-separator // default __
flyway.sql-migration-suffix   // default .sql
flyway.table                 // default schema_version
flyway.target                 // target version, default latest
flyway.url                    // JDBC URL (fallback to primary datasource)
flyway.user                   // DB username
flyway.validate-on-migrate   // true/false

Plugin Configuration (Maven):

<plugin>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-maven-plugin</artifactId>
    <configuration>
        <url>url</url>
        <user>account</user>
        <password>password</password>
        <driver>com.mysql.cj.jdbc.Driver</driver>
        <locations>
            <location>address</location>
        </locations>
    </configuration>
</plugin>

IDEA users can view Flyway configuration directly within the IDE (screenshot omitted).

Reference: Flyway Documentation