New! – Try automated migration testing Learn more

Flyway Documentation

Poll

Check

The check command is currently in beta. This feature will be available in future products, but during the beta phase you can access it through your Flyway Teams or Redgate Deploy license.

Contact us

Overview

In Flyway, “Checks” is the collective term we use for the pre- or post-deployment analysis of some aspect of your database migration. Checks are instantiated using the top level check command.

Before performing a deployment to the target database (most notably, production), you might want to look over what you’re about to do and understand one or more of the following:

  • Does this set of changes affect the objects I expect it to, or will I be inadvertently having an impact on something else?
  • What database changes have been made recently, that coincide with the changes in database performance we are seeing? Are the two related?
  • Is the production database in the same state you were expecting when I began developing my changes? Has anything about the target database changed that would mean my changes no longer have the desired effect?
  • Does our approach to database change development meet our internal policies? Are our migration scripts adhering to our naming conventions, for example? Are we following the security best-practices required of us by our external regulatory requirements?

Each of these scenarios can be met with the check command, using the corresponding flag:

Scenario Command & Flag Output
In beta
Will these changes have the effect I am expecting?
check -changes ChangeReport.html,
ChangeReport.json
In beta
What database changes have been made recently?
check -changes ChangeReport.html,
ChangeReport.json
In beta
Is the production database in the state I am expecting it to be in?
check -drift ChangeReport.html,
ChangeReport.json
Coming soon
Are our changes following internal policies ?
   

Check –changes

Overview

The –changes flag produces a report indicating differences between applied migration scripts on your target database and pending migrations scripts (ie. the set of instructions you want to use to change your target database). You can use this capability pre- and post-deployment:

  • In pre-deployment scenarios to check the effect of your pending changes
  • In post-deployment scenarios to have captured a history of changes for retrospective auditing or reporting

In either scenario, using the -changes flag will help you infer which database objects will be/have been affected - and how – when you execute/have executed your migration script(s).

Requirements and behavior

The check –changes command and flag works by building a temporary database. This temporary database is first made to reflect the state of your target schema, and then made to reflect your target schema with the pending changes applied.

The difference between the two states of this temporary database (target now, and target with changes applied) represents the effect your pending migrations will have (or have had) when the scripts are (or were) executed. This difference is captured as an artefact called a “Change Report”. The change report is available as both HTML (human readable) and JSON (machine readable) formats.

The process works like this: Check_changes.png

  1. Specify your target database location
    1. This is the database you want to apply your changes to, where Flyway is already being used to manage migrations (ie. A Flyway migrations table exists)
  2. Specify a temporary database
    1. This is an existing temporary database (note: Flyway will “clean” this database, so if you specify a full database, you must ensure it is ok to for Flyway to erase its schema)
  3. Run flyway check –changes

Flyway’s check –changes will then:

  1. Clean your temporary database
  2. Query the target database for the list of applied migrations (for simplicity, let’s say it’s at V2)
  3. Apply these migrations to the temporary database
  4. Take a snapshot of the temporary database (now also at V2)
  5. Applying pending migrations to the temporary database (let’s say it’s now at V5)
  6. Take a snapshot of the temporary database
  7. Compare the V2 temporary database snapshot to the V5 temporary database snapshot
  8. Generate a HTML (human readable) and JSON (machine readable) Change Report, indicating the additions, deletions, and modifications of database objects between V2 and V5

Good things to know

  • There is no requirement for the temporary database to be in your production system
  • Please note that the temporary database will be cleaned before the operation starts
  • The underlying comparison technology is dependent on .NET 6 which is why this is required