checks-scope

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

Note: This command is only available with Liquibase Lab.

Uses

When --checks-scope changelog is ran, Liquibase checks each changeset in a changelog to see if any of those changesets trigger any enabled checks. When --checks-scope database is ran, 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.

An example of running the checks-scope parameter

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

Running the checks-scope command

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

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

checks-scope Parameter Attributes

The following table identifies attributes that can be used with the checks-scope parameter. Please be aware that checks-scope works on all changelog types such as sql, xml, yaml, and json. Simultaneously, not all Quality Checks work on all changelog types. It is best practice to review which Quality Checks work on the changelog type being used.

Name Syntax Description
changelog

CLI:

--checks-scope=changelog

Property:

liquibase.command.checksscope=changelog

Environment Variable:

LIQUIBASE_COMMAND_CHECKS_SCOPE="changelog"

The attribute which 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"

The parameter which specifies the database subset of checks to run.

Note: One attribute is required to run checks-scope successfully. Both can be used at the same time like so: changelog, database or database, changelog

Changelog checks-scope 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.

1. With a changelog that has a createTable changeset with two columns, enable the TableColumnLimit check in the command line like so:
liquibase checks enable --check-name=TableColumnLimit

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

3. Run liquibase checks bulk-set --disable to disable any enabled checks.

Liquibase will ask if you are sure you want to disable all checks.

4. Type Y to confirm you want to disable all checks.

5. Run liquibase checks customize --check-name TableColumnLimit.

6. Set the severity as desired.

7. Set the Max Columns to 2.

8. Enable the check.

9. Run liquibase checks run --checks-scope changelog --changelog-file yourName-createTable-changelog.xml.

Liquibase has successfully run checks against it's new changelog.

Database checks-scope 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 can be a, and typically will be, 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

A snapshot of the database is created automatically if a live database url is being used and if a db-scoped check is enabled. Learn how to navigate this process below.

1. Establish the url and reference url in the liquibase.properties file like so:

#### Enter the Target database 'url' information ####

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

#### Enter URL for the source database ####

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.

Liquibase has successfully run checks against the database snapshot.

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. Learn how to navigate this process below.

Note: It is important to note that this snapshot is not retained.

1. Run liquibase --output-file=mySnapshot.json snapshot --snapshotFormat=jsonto create a snapshot.

Note: Replace mySnapshot.json and =json with the desired snapshot file title and format.

2. Add the offline snapshot url to the liquibase.properties file:

offline:DB_SHORTNAME?snapshot=mySnapshot.json

Note: Replace DB_SHORTNAME with the database type being used. Such as: 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, an sql with H2 is generated automatically to be checked against.

3. Then run the checks-scope command:

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

Checks are run successfully against the database snapshot.

When running the checks-scope command with the changelogattribute, the output can be as follows:


Starting Liquibase at 16:35:11 (version [Core: //DAT-9298/2516/e42617/2022-05-11 19:02+0000, Pro: DAT-9298/1208/56ac6a/2022-05-11T18:56:15Z] #2516 built at 2022-05-11 19:02+0000)

Liquibase Version: [Core: //DAT-9298/2516/e42617/2022-05-11 19:02+0000, Pro: DAT-9298/1208/56ac6a/2022-05-11T18:56:15Z]
				
Liquibase Empire [Core: //DAT-9298/2516/e42617/2022-05-11 19:02+0000, Pro: DAT-9298/1208/56ac6a/2022-05-11T18:56:15Z] by Liquibase licensed to Dev until Sat Dec 30 21:59:59 MST 2023

Executing Quality Checks against amber-createTable-changelog.xml


Executing all changelog checks because a valid license key was found!


CHANGELOG CHECKS

				----------------
				
Checks completed validation of the changelog and found the following issues:

				
Changeset ID:       1::createTableforSynonym-PROSCHEMA

Changeset Filepath: amber-createTable-changelog.xml
				
Check Name:         Check Table Column Count (TableColumnLimit)

Check Severity:     MINOR (Return code: 1)

Message:            Table must not have more than 2 columns.

 


Changesets Validated:

ID: 1::createTableforSynonym-PROSCHEMA; Author: Liquibase Pro User; File path: amber-createTable-changelog.xml

Checks run against each changeset:

Check Table Column Count

Liquibase command 'checks run' was executed successfully.


						

When running the checks-scope command with the automatically created database snapshot, you receive the following output:


				C:\Users\Amber Williams\Documents\Empire-project>liquibase checks run --checks-scope database
				####################################################
				##   _     _             _ _                      ##
				##  | |   (_)           (_) |                     ##
				##  | |    _  __ _ _   _ _| |__   __ _ ___  ___   ##
				##  | |   | |/ _` | | | | | '_ \ / _` / __|/ _ \  ##
				##  | |___| | (_| | |_| | | |_) | (_| \__ \  __/  ##
				##  \_____/_|\__, |\__,_|_|_.__/ \__,_|___/\___|  ##
				##              | |                               ##
				##              |_|                               ##
				##                                                ##
				##  Get documentation at docs.liquibase.com       ##
				##  Get certified courses at learn.liquibase.com  ##
				##  Free schema change activity reports at        ##
				##      https://hub.liquibase.com                 ##
				##                                                ##
				####################################################
				Starting Liquibase at 12:18:24 (version [Core: //DAT-9298/2516/e42617/2022-05-11 19:02+0000, Pro: DAT-9298/1208/56ac6a/2022-05-11T18:56:15Z] #2516 built at 2022-05-11 19:02+0000)
				Liquibase Version: [Core: //DAT-9298/2516/e42617/2022-05-11 19:02+0000, Pro: DAT-9298/1208/56ac6a/2022-05-11T18:56:15Z]
				Liquibase Empire [Core: //DAT-9298/2516/e42617/2022-05-11 19:02+0000, Pro: DAT-9298/1208/56ac6a/2022-05-11T18:56:15Z] by Liquibase licensed to Dev until Sat Dec 30 21:59:59 MST 2023
				Executing Quality Checks against database jdbc:h2:tcp://localhost:9090/mem:dev

				Executing all database checks because a valid license key was found!

				INFO This command might not yet capture Liquibase Pro additional object types on h2
				Database objects Validated:
				Catalog             : 1
				Schema              : 1

				Checks run against database jdbc:h2:tcp://localhost:9090/mem:dev:
				Check Table Column Count

				Liquibase command 'checks run' was executed successfully.

				C:\Users\Amber Williams\Documents\Empire-project>

When running the checks-scope command with the specified offline snapshot url attribute, you receive the following output:


						Liquibase Community 4.9.1 by Liquibase
						Database snapshot for jdbc:h2:tcp://localhost:9090/mem:integration
						-----------------------------------------------------------------
						Database type: H2
						Database version: 2.1.210 (2022-01-17)
						Database user: DBUSER
						Included types:
						liquibase.structure.core.Catalog
						liquibase.structure.core.Column
						liquibase.structure.core.ForeignKey
						liquibase.structure.core.Index
						liquibase.structure.core.PrimaryKey
						liquibase.structure.core.Schema
						liquibase.structure.core.Sequence
						liquibase.structure.core.Table
						liquibase.structure.core.UniqueConstraint
						liquibase.structure.core.View
						Liquibase command 'snapshot-reference' was executed successfully.

Related Topics: