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:
Property:
Environment Variable:
|
Specifies the changelog subset of checks to run. |
database
|
CLI:
Property:
Environment Variable:
|
Specifies the database subset of checks to run. |
Checks that can run against databases, changelogs, or both are listed in the table below.

Name | Description | Scope |
---|---|---|
TableColumnLimit
|
Ensures that no table has more than a threshold number of columns. |
Database and changelog |
ObjectNameMustMatch
|
This check confirms the listed object names conform to the supplied pattern. | Database and changelog |
ObjectNameMustNotMatch
|
This check confirms the listed object names do not match the supplied pattern. | Database and changelog |
TableCommentPatternCheck
|
This check triggers when specific user-supplied patterns are found in Table Comments | Database and changelog |

Name | Description | Scope |
---|---|---|
TableCommentCheck
|
This database check flags any table which does not have a comment. (Note: This is not a check for a Liquibase changelog comment.) | Database |
ConstraintMustExist
|
Check for and alert when specified table does not contain the required constraint(s). | Database |

Name | Description | Scope |
---|---|---|
RequireChangesetIDisUUID
|
This check confirms the listed object names do not match the supplied pattern. | changelog |
PrimaryKeyOnCreateTable
|
This check warns when a create table action doesnt also include a primary key. | changelog |
ChangesetCommentCheck
|
The check enforces the Liquibase recommendation that comments be added to each changeset to document the purpose of a changeset for other consumers of that changelog. | changelog |
ChangesetContextCheck
|
The checks enforce the Liquibase recommendation that contexts are assigned to each changeset to provide better deployment control and to enhance traceability of efforts across changesets. | changelog |
ChangesetLabelCheck
|
The checks enforce the Liquibase recommendation that labels are assigned to each changeset to provide better deployment control and to enhance traceability of efforts across changesets. | changelog |
RollbackRequired
|
The check detects when a changeset does not have a rollback defined so that you can deploy and revert schema changes when needed. | changelog |
SqlGrantAdminWarn
|
The checks warn when generated or raw SQL contains the GRANT statements that include the WITH ADMIN OPTION clause or the WITH GRANT OPTION class. This ensures that the privilege being granted will not lead to security issues. | changelog |
PostgresNonReservedKeywords
|
Disallow Postgres non-reserved keywords from being used in database object names. | changelog |
PostgresReservedKeywords
|
Disallow POSTGRES reserved keywords from being used in database object names. | changelog |
SQLServerReservedKeywords
|
Disallow SQL Server reserved keywords from being used in database object names. | changelog |
SQLServerFutureReservedKeywords
|
Disallow SQL Server’s Future reserved keywords from being used in database object names. | changelog |
SQLServerODBCReservedKeywords
|
Disallow SQL Server’s ODBC reserved keywords from being used in database object names. | changelog |
OracleReservedKeywords
|
Disallow Oracle reserved keywords from being used in database object names. | changelog |
SqlGrantOptionWarn
|
This check warns a user when SQL contains 'GRANT' statements that include the 'WITH GRANT OPTION' clause so that they can ensure that the privilege being granted won't lead to security issues. | changelog |
ChangeTruncateTableWarn
|
The ChangeTruncateTableWarn check warns when a table is truncated with TRUNCATE TABLE statements. This ensures that dropping the column will not lead to an unintentional loss of data. | changelog |
SqlGrantSpecificPrivsWarn
|
The check warns when a changeset contains SQL that grants specific privileges to a user or role. | changelog |
SqlUserDefinedPatternCheck
|
The check scans generated or raw SQL for the presence of specific patterns so that you can prevent security and velocity issues as early as possible. | changelog |
ModifyDataTypeWarn
|
The check warns when a change will result in modification of a data type so that you can ensure that modifying the data type will not lead to unintentional loss of data. | changelog |
ChangeDropColumnWarn
|
The check warns when a table is being dropped. This ensures that dropping the table will not lead to unintentional loss of data. | changelog |
ChangeDropTableWarn
|
The check warns when a table is being dropped. This ensures that dropping the table will not lead to unintentional loss of data. | changelog |
SqlRevokeWarn
|
The check warns when generated or raw SQL contains REVOKE statements so that you can ensure that the privilege being revoked will not lead to data access and dependency issues. | changelog |
SqlGrantWarn
|
The check warns when generated or raw SQL contains GRANT statements so that you can ensure that the privilege being granted will not lead to security issues. | changelog |
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 theTableColumnLimit
check in your command line:
liquibase checks enable --check-name=TableColumnLimit
liquibase checks run --checks-scope=changelog
command.liquibase checks bulk-set --disable
to disable any enabled checks. Liquibase will ask if you are sure you want to disable all checks.Y
to confirm you want to disable all checks.liquibase checks customize --check-name=TableColumnLimit
.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:
- Establish the
url
andreferenceUrl
in theliquibase.properties
file: - Run the
liquibase checks run --checks-scope database
command.
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.
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.
- Run
liquibase --output-file=mySnapshot.json snapshot --snapshotFormat=json
to create a snapshot. ReplacemySnapshot.json
and=json
with the desired snapshot file title and format. - Add the offline snapshot URL to the
liquibase.properties
file: - Run the
checks-scope
command:
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.
liquibase checks run --checks-scope=database --url offline:oracle?snapshot=mySnapshot.json

checks-scope changelog
example
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.
checks-scope database
example
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.
checks-scope
with offline snapshot URL
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.