Check Changes - Flyway

Description

{% include enterprise.html %}

The check -changes command produces a report indicating differences between what is applied on your target database and pending changes (i.e. the set of instructions you want to use to change your target database).

The report is generated entirely using snapshots of the configured build environment which means that any drift to the production database will be ignored in this report.

Note:

There is no requirement for the build environment to be in your production system
Please note that the build environment may be cleaned before the operation starts
Your Flyway instance assumes that it is the only party changing the build environment so it shouldn't be used concurrently by different developers
If you get an ERROR: Invalid argument: -check, this is because some systems (for example, Powershell) do not like the period in the argument. You can wrap the arguments in a single or double quotes to work around this (e.g. flyway check -changes "-check.buildURL") or use namespace short-circuiting.

See Migrations - Migration validation for more information.

Usage examples

Generating report based upon environment

bash

flyway check -changes -buildEnvironment="build" -environment="production"

This approach captures snapshots of the build database before and after pending migrations are executed, and uses these as the basis for the comparison which underlies the report.

Generating report based upon applied migrations

bash

flyway info -infoOfState="success,out_of_order" -migrationIds > appliedMigrations.txt
flyway check -changes -buildEnvironment="build" -appliedMigrations="$(cat appliedMigrations.txt)

This approach captures snapshots of the build database before and after pending migrations are executed, and uses these as the basis for the comparison which underlies the report.

Generating report based upon snapshots

bash

flyway check -changes -deployedSnapshot="snapshotHistory:current" -nextSnapshot="C:\snapshot2.json"

The comparison which underlies the report is generated from the specified snapshots.

Generating report from a Schema model based upon environment

bash

flyway check -changes -changesSource="schemaModel" -environment="production"

The comparison which underlies the report is generated from the specified Schema model and environment.

Parameters

Conditionally required

When generating report based upon configured build environment

Parameter	Namespace	Description
`buildEnvironment`	check	Build environment id.

When generating report based upon build environment defined inline

Parameter	Namespace	Description
`buildUrl`	check	URL for the build database.

When generating report based upon snapshots

Parameter	Namespace	Description
`nextSnapshot`	check	A snapshot containing all migrations including those that are pending.

Optional

Parameter	Namespace	Description
`deployedSnapshot`	check	A snapshot matching the last known state of the target database.
`appliedMigrations`	check	Migration ids (migration versions or repeatable descriptions) to apply to create snapshots.
`buildUser`	check	Username for the build database.
`buildPassword`	check	Password for the build database.
`filterFile`	check	The path to a filter file, containing custom filtering rules for excluding objects from the comparisons.
`changesSource`	check	The deployment source to generate a change report from.
`environment`	(root)	The target environment id.
`reportFilename`	(root)	The output path of the generated report.
`schemaModelLocation`	(root)	The location of the schema model folder.
`workingDirectory`	(root)	The directory to consider the current working directory. All relative paths will be considered relative to this.
{environment parameters}	(root)	Environment configuration for the source and/or target environments.

Universal commandline parameters are listed here.

Settings from the following sections of the Flyway namespace can be specified in relation to database connections:

General settings
Settings in database-specific namespaces
Settings in secrets management namespaces

When a build environment is used, settings from the following sections of the Flyway namespace can also be set:

Migration location and naming settings
Migration reading settings
Migration execution settings
Flyway schema history settings
Placeholders

When a Schema model is used, settings from the following sections of the Flyway namespace can also be set:

Schema model settings

JSON output format

json

{
  "htmlReport": "report.html",
  "jsonReport": "report.json",
  "individualResults": [
    {
      message: null,
      stackTrace: null,
      onlyInSource: [],
      onlyInTarget: [],
      differences: [
        {
          name: "Table_1",
          schema: "dbo",
          objectType: "Table",
          definitionBefore: "CREATE TABLE Table_1 (id text)",
          definitionAfter: "CREATE TABLE Table_1 (different_id text)",
        },
      ],
      timestamp: "2022-07-22T08-08-33Z",
      database: "testdb",
      operation: "changes",
      flywayVersion: undefined,
      warnings: undefined,
    }
  ]
 }

Error codes

This command can produce the following error codes: