checks-scope

checks-scope is a parameter that can be applied to the checks run subcommand. It allows the user to check either the changelog or database against any enabled checks.

Uses

When you run checks-scope=changelog, Liquibase checks each changeset in the changelog to see if any of those changesets trigger any enabled checks.

When you run checks-scope=database, Liquibase checks each database object to see if any of those objects trigger any enabled checks.

Both the changelog and database can be checked by themselves or at the same time. Users may choose between changelog, database, or database, changelog to run the enabled checks against. If checks-scope is not specified, Liquibase defaults to running changelog checks.

Syntax

A check can be one scope or dual-scoped. When executed, the command can be used in any of the following ways:

--checks-scope=changelog
--checks-scope=database
--checks-scope=changelog, database
--checks-scope=database, changelog

For example:

liquibase checks run --checks-scope=changelog --changelog-file=<example-changelog.xml>

checks-scope attributes

The following table identifies attributes that can be used with the checks-scope parameter. Note that checks-scope works on all changelog types (SQL, XML, YAML, and JSON), but not all quality checks work on all changelog types. It is best practice to review which quality checks work on the changelog type you are using.

Name	Syntax	Description
changelog	CLI: --checks-scope=changelog Property: liquibase.command.checksscope=changelog Environment Variable: LIQUIBASE_COMMAND_CHECKS_SCOPE="changelog"	Specifies the changelog subset of checks to run.
database	CLI: --checks-scope=database Property: liquibase.command.checksscope=database Environment Variable: LIQUIBASE_COMMAND_CHECKS_SCOPE="database"	Specifies the database subset of checks to run.

Checks that can run against databases, changelogs, or both are listed in the table below.

checks-scope changelog procedure

This example covers how to run checks-scope against a changelog. It begins with a changelog that contains a createTable changeset and no checks enabled. Once the process is complete, the resulting checks will display successfully.

• With a changelog that has a createTable changeset with two columns, enable the TableColumnLimit check in your command line:

liquibase checks enable --check-name=TableColumnLimit

• Run the liquibase checks run --checks-scope=changelog command.
• Run liquibase checks bulk-set --disable to disable any enabled checks. Liquibase will ask if you are sure you want to disable all checks.
• Type Y to confirm you want to disable all checks.
• Run liquibase checks customize --check-name=TableColumnLimit.
• Set the severity as desired.
• Set the Max Columns to 2.
• Enable the check.
• Run liquibase checks run --checks-scope=changelog --changelog-file=yourName-createTable-changelog.xml.

checks-scope database procedure

Users can establish which database the checks will be run against by specifying the desired database in the url parameter within the liquibase.properties file or the environment variable equivalent. The database is typically a JDBC connection string. A snapshot, which is a reference to a Liquibase-created file describing the database, is automatically created if a live JDBC URL is used and any database-scoped checks are enabled. A snapshot can also be created manually by establishing an offline database URL.

Users should be aware that some data types and settings change when checks-scope database is performed. Some examples are listed below.

• Integers may become Numeric
• Varchar(max setting can become a clob setting)

Automatically create a snapshot and run checks

Users can automatically create a snapshot of the database if they use a live database URL and enable a database-scoped check:

1. Establish the url and referenceUrl in the liquibase.properties file:

liquibase.command.url: jdbc:h2:tcp://localhost:9090/mem:dev
liquibase.command.referenceUrl: jdbc:h2:tcp://localhost:9090/mem:integration

This establishes the automatic snapshot.

2. Run the liquibase checks run --checks-scope database command.

Manually create a snapshot and run checks

Users can take a snapshot of their database manually and run checks against it if they prefer using an offline database URL. They must first establish a snapshot and then enter the offline location in their liquibase.properties file to run the command successfully:

Note: This snapshot is not permanently retained.

1. Run liquibase --output-file=mySnapshot.json snapshot --snapshotFormat=json to create a snapshot. Replace mySnapshot.json and =json with the desired snapshot file title and format.
2. Add the offline snapshot URL to the liquibase.properties file:

liquibase.command.url: offline:DB_SHORTNAME?snapshot=mySnapshot.json

Note: Replace DB_SHORTNAME with the database type being used (SQL, XML, YAML, or JSON). Also replace mySnapshot.json with the desired snapshot file title and format.

The type of database is determined from the url property if at least one database scope check is enabled. If the database cannot be determined, Liquibase automatically generates SQL to check against using H2.

3. Run the checks-scope command:

liquibase checks run --checks-scope=database --url offline:oracle?snapshot=mySnapshot.json