Redgate Flyway

Migrations-Based Approach – Flyway CLI

Page last updated 24 December 2025

Want to skip ahead and use ready-made scripts? Clone the full repo here: Flyway Helper Files GitHub Repo.

Why choose Migrations-Based?

Migrations-based deployments manage database changes through versioned scripts, giving you full visibility and control over how changes are applied. This approach is:

  • Ideal for teams who want explicit control over the evolution of their schema.
  • Great for auditability—every change is tracked and versioned.
  • Flexible for automation—works seamlessly with CI/CD pipelines.

Just like state-based, migrations-based workflows can auto-generate scripts, but at different points in the process. Think of it like driving a car:

  • State-Based is like an automatic car—it handles a lot for you, but you still steer and decide where to go.
  • Migrations-Based is like a manual car—you feel every gear change and have more control, but both approaches get you to the same destination.

Migrations-Based workflows typically involve two stages:

1. Developer Workflow Simulation

Commands like diff, model, and generate mimic what developers do in Flyway Desktop:

diff: Compares two sources (e.g., Development DB vs schema model) and shows the differences.

model: Analyzes the diff output and updates your Flyway Schema Model.

generate: Creates migration scripts based on differences for review and inclusion in your project.

2. DevOps Workflow Simulation

Commands like snapshot, check, migrate, and undo are used in CI/CD pipelines:

snapshot: Captures the state of a database for drift detection and auditability.

check: Validates that the migration scripts are safe and highlights any risks.

migrate: Applies pending migrations to the target database.

undo: Rolls back the most recent migration (Teams/Enterprise feature).

Not every customer needs both stages—if your goal is simply to apply migrations, you can start at migrate.

Using the Chinook Sample Database

For the fastest start, use the Chinook schema for SQL Server, PostgreSQL, Oracle, or MySQL. It’s included in our Flyway Helper Files repo here.
Run the setup script for your database engine, then proceed with the steps below.
(Prefer your own schema? That works too—just adjust the connection details accordingly.)

Next Steps

Below, you’ll find expandable sections for each command in the workflow. Each section includes:

Purpose – Why the command matters.

When to use – Where it fits in the workflow.

Helper script links – Quick access to ready-made scripts.

How to configure – Variables explained for easy setup.

Diff Command

Purpose

Generate an artifact that details the differences between two sources—these can be databases, a schema model, or a snapshot. In a migrations-based workflow, this is the first step toward creating migration scripts. The artifact produced by diff is then used by generate to create versioned migration scripts for review and inclusion in your project.

When to use diff

To compare environments (e.g., development vs schema model) and capture differences.

To generate a differences artifact for review or automation.

To feed into Model or Generate

You want a human‑readable differences report to review in PRs or as part of code review (This requires the use of diffText after first running diff)

If your goal is simply to apply existing migrations, you can skip diff and start at Snapshot.

Windows

Linux

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
ARTIFACT_FILENAMEPath and filename for the differences artifact (ZIP containing results).
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project.
SOURCE_ENVIRONMENTName of the source environment (e.g., development).
SOURCE_ENVIRONMENT_USERNAMEUsername for the source environment (leave empty for Windows Authentication).
SOURCE_ENVIRONMENT_PASSWORDPassword for the source environment (leave empty for Windows Authentication).
TARGET_ENVIRONMENTName of the target environment (e.g., schemaModel for state-based).

Important:

For real deployments, do not store sensitive values in plaintext. Use environment variables or secure credential stores.

If using Windows Authentication, USERNAME and PASSWORD can be left empty.

For additional parameters and options (like comparing snapshots or customizing output), see the Flyway Diff command reference.

Model Command

Purpose

Capture changes from a differences artifact (created by diff) and apply them to your schema model. This updates the model so it reflects the latest state of your source environment. In a migrations-based workflow, maintaining an accurate schema model is essential because it drives the generation of migration scripts in the next step (generate).

When to use model

After running diff to identify changes between environments.

When you want to keep your schema model in sync with your development database.

Typically part of the developer workflow (simulating Flyway Desktop behavior).

If you’re only wanting to deploy changes and not automating the maintenance of the schema model, you can skip model and go straight to snapshot.

Helper Script Links

Windows

Linux

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
ARTIFACT_FILENAMEPath to the differences artifact created by diff (ZIP file).
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project..

For additional parameters and options (like customizing schema model location), see the Flyway Model command reference.

Generate Command

Purpose

Create migration scripts (and optionally undo scripts) based on the differences identified by diff. This is the key step in a migrations-based workflow because it produces versioned scripts that you can review, commit to source control, and apply later using migrate. These scripts give you full control and auditability over how changes are applied.

When to use generate

  • After running diff and updating your schema model with model.
  • When you want Flyway to auto-generate migration scripts for changes between your desired state (schema model) and your existing migrations.
  • Typically part of the developer workflow before committing scripts to version control.

If you already have handcrafted migration scripts, or Flyway Desktop generate, you can skip generate and go straight to snapshot.

Helper Script Links

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
ARTIFACT_FILENAMEPath to the differences artifact created by diff (ZIP file).
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project.
SOURCE_ENVIRONMENTName of the source environment (usually schemaModel).
TARGET_ENVIRONMENTName of the target environment (usually migrations).
BUILD_ENVIRONMENTName of the environment used for validation (Typically an empty sandbox database or schema).
BUILD_ENVIRONMENT_USERNAMEUsername for the build environment (leave empty for Windows Authentication).
BUILD_ENVIRONMENT_PASSWORDPassword for the build environment (leave empty for Windows Authentication).
FLYWAY_VERSION_DESCRIPTIONDescription for the migration script filename (e.g., FlywayCLI_AutomatedMigrationScript).

Important

  • For real deployments, do not store sensitive values in plaintext. Use environment variables or secure credential stores.
  • If using Windows Authentication, username and password fields can be left empty.
  • Generated scripts will include versioned and undo scripts by default (-generate.types=versioned,undo).

Additional Options

For more parameters (like customizing script naming, adding timestamps, or limiting script types), see the Flyway Generate command reference. 

Snapshot Command

Purpose

Create a schema snapshot of the target database and store it for future comparison or drift detection.
Snapshots can now be saved directly into the flyway_snapshot_history table in the target database, which is extremely valuable for CI/CD workflows. This eliminates the need for shared storage between environments and makes it easier for commands like check to retrieve historical states for drift analysis.

When to use snapshot

  • To capture the current state of a database for auditing or drift detection.
  • Before or after deployments to maintain a history of schema states.
  • Especially useful in CI/CD pipelines, where storing snapshots in the database simplifies access for checks like drift detection.

Helper Script Links

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project.
TARGET_ENVIRONMENTName of the target environment (e.g., Test).
TARGET_ENVIRONMENT_USERNAMEUsername for the target environment (leave empty for Windows Authentication).
TARGET_ENVIRONMENT_PASSWORDPassword for the target environment (leave empty for Windows Authentication).

Important:

  • For real deployments, do not store sensitive values in plaintext. Use environment variables or secure credential stores.
  • If using Windows Authentication, username and password fields can be left empty.

This script uses -snapshot.filename=snapshotHistory:Snapshot-<date> to store the snapshot in the flyway_snapshot_history table.
The -snapshot.historyLimit=5 parameter ensures only the last 5 snapshots are retained for this environment.

For additional parameters and options (like customizing snapshot retention or exporting snapshots to files), see the Flyway Snapshot command reference.

Check Command

Purpose

Generate a comprehensive report that analyzes:

  • Pending changes between source and target environments.
  • Drift detection by comparing the target database against its last known snapshot.
  • Code analysis for potential issues in the migration scripts (e.g., destructive statements).

The report helps ensure deployments are safe and predictable, and it’s especially valuable in CI/CD workflows.

When to use check

  • Before applying migrations, to validate:
    • What changes will be applied.
    • Whether the target environment has drifted from its expected state.
    • If migration scripts pass code quality checks.
  • Typically part of DevOps workflows, right after generate and before migrate.

    If this is the first time running check against the target environment, you may see warnings about missing snapshots. Run Snapshot first or use Migrate, which can create snapshots automatically.

Helper Script Links

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
REPORT_FILENAMEName of the generated HTML report (e.g., Flyway-Check-All_Report.html).
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project.
REPORT_ENVIRONMENTName of the sandbox environment used for reporting.
REPORT_ENVIRONMENT_USERNAMEUsername for the reporting environment (leave empty for Windows Authentication).
REPORT_ENVIRONMENT_PASSWORDPassword for the reporting environment (leave empty for Windows Authentication).
TARGET_ENVIRONMENTName of the target environment (e.g., Test - as defined in the flyway.toml project file).
TARGET_ENVIRONMENT_USERNAMEUsername for the target environment (leave empty for Windows Authentication).
TARGET_ENVIRONMENT_PASSWORDPassword for the target environment (leave empty for Windows Authentication)).

Important

  • For real deployments, do not store sensitive values in plaintext. Use environment variables or secure credential stores.
  • If using Windows Authentication, username and password fields can be left empty.
  • Ensure a snapshot exists in the target environment (via Snapshot or by setting Migrate to save snapshots). Otherwise, drift evaluation may warn about missing history.

What the Check report includes

  • Changes analysis: Lists pending changes based on migrations folder vs target.
  • Drift detection: Compares the target database against its last snapshot in flyway_snapshot_history.
  • Code analysis: Reviews the deployment script for potential issues (e.g., destructive operations).

For additional parameters and options (including customizing scope and output), see the Flyway Check command reference and its sub-pages:

Migrate Command

Purpose

Apply all pending migration scripts to the target environment. This step brings the target database in line with the desired state defined by your migrations. Optionally, migrate can save a snapshot of the target environment after deployment, which is extremely useful for drift detection and auditing in CI/CD workflows.

When to use migrate

  • After validating migration scripts with check.
  • To apply changes to the target environment in a controlled, automated way.
  • Typically the final step in the migrations-based CI/CD workflow.

Helper Script Links

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project.
TARGET_ENVIRONMENTName of the target environment (e.g., Test).
TARGET_ENVIRONMENT_USERNAMEUsername for the target environment (leave empty for Windows Authentication).
TARGET_ENVIRONMENT_PASSWORDPassword for the target environment (leave empty for Windows Authentication).
SAVE_SNAPSHOTBoolean (true/false) to save a snapshot in the target environment after deployment.

Important

  • For real deployments, do not store sensitive values in plaintext. Use environment variables or secure credential stores.
  • If using Windows Authentication, username and password fields can be left empty.
  • Setting SAVE_SNAPSHOT=true ensures the target environment’s state is captured in the flyway_snapshot_history table immediately after deployment—ideal for drift detection and compliance.

For more parameters and options (like customizing snapshot behavior or deployment scope), see the Flyway Migrate command reference.

Undo Command

Purpose

Roll back the most recently applied migration on the target environment by executing its corresponding undo script. This is useful for quickly reverting a change during development or in controlled scenarios where you need to step back one version.

Note: undo is available with Flyway Enterprise and relies on the presence of a matching undo script for the last applied version.

When to use undo

  • Immediately after discovering an issue with the last migration and a matching undo script exists.
  • In a sandbox or test environment to validate rollback behavior.
  • As part of controlled remediation during a PoC or development cycle.

Helper Script Links

How to Configure

These variables are defined at the top of the helper scripts and are consistent across platforms:

VariablePurpose
WORKING_DIRECTORYRoot folder for your Flyway migrations-based project.
TARGET_ENVIRONMENTName of the target environment (e.g., Test).
TARGET_ENVIRONMENT_USERNAMEUsername for the target environment (leave empty for Windows Authentication).
TARGET_ENVIRONMENT_PASSWORDPassword for the target environment (leave empty for Windows Authentication).

Important

  • For real deployments, do not store sensitive values in plaintext. Use environment variables or secure credential stores.
  • If using Windows Authentication, username and password fields can be left empty.

For more parameters and options (including behavior nuances and limitations), see the Flyway Undo command reference.

What You’ve Achieved

Congratulations! You’ve now completed the Migrations-Based Flyway CLI workflow end-to-end:

  • Captured differences between environments with Diff.
  • Updated your schema model using Model.
  • Generated versioned migration and undo scripts with Generate.
  • Created snapshots for drift detection using Snapshot.
  • Validated pending changes and code quality with Check.
  • Applied migrations to your target environment using Migrate.
  • Rolled back the last migration using Undo (Teams/Enterprise feature).

By following these steps, you’ve proven the migrations-based workflow works and mastered the basics of Flyway CLI for controlled, versioned deployments. This foundation gives you the flexibility to integrate Flyway into almost any workflow—including CI/CD pipelines—at your own pace.

Next Steps










Didn't find what you were looking for?

Product Articles

Tips and how-to guides for Redgate products

University

Easy to follow video courses

Community Forums

Ask, discuss, and solve questions about Redgate's tools

Events & Friends

Meet us at an event, get sponsored, and join our Friends of Redgate

Simple Talk

In-depth articles and opinion from Redgate's technical journal