run
Note: This is a Liquibase Pro feature, so you need a Liquibase Pro License Key to use it.
The run
subcommand executes checks using the checks settings file against a changelog, database, or both. Quality checks support XML, SQL, YAML, and JSON changelog formats, and all the Liquibase Pro-certified databases.
Uses
The checks run
executes enabled checks based on the --checks-scope
property. To specify the scope, set checks-scope
to changelog
, database
, or changelog,database
to run both scopes.
The checks run
command by default executes the enabled changelog checks against the specified changelog using the checks settings files, which can have default and/or non-default locations. When you run a database-scoped check, Liquibase takes a snapshot of your database to run the checks against.
If your files are not stored in the Liquibase working directory, specify the relative path to them. Check How Liquibase Finds Files: Liquibase Search Path for more details.
In Liquibase Pro 4.26.0 and later, you can use checks run
to seamlessly generate a Checks Run Report for your database.
Note: To view a list of available checks, run liquibase checks show
.
Syntax
Run the command specifying your values:
liquibase checks run --changelog-file=basicRule.postgres.sql
Note: If you have a checks settings file customized for a specific environment or project, you need to pass that using the --checks-settings-file
parameter. If you do not include this parameter, Liquibase uses the default settings file: liquibase.checks-settings.conf
. See Use the Checks Settings Configuration File.
To execute checks that require a database connection, you must also include connection attributes such as the database url
.
Parameters
Global parameters
Parameter | Definition | Requirement |
---|---|---|
|
Your Liquibase Pro license key |
Required |
Command parameters
Parameter | Description | Requirement |
---|---|---|
|
The changelog file against which you execute checks when running |
Required (either this or --url ) |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required (either this or --changelog-file ) |
|
Optional | |
|
Allows automatic backup and updating of the Default: off |
Optional |
|
If true, sqlFile change type contents will be cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true | Optional |
|
Specifies whether quality checks run on |
Optional |
|
Use this to specify the short name of the check you want to target with one of the following subcommands:
|
Optional |
|
Allow changeset's rollback code to be analyzed for compliance with currently enabled quality checks. Default: false | Optional |
|
Specify which parts of the checks run output should be shown. Options:
Default: all |
Optional |
|
Optional | |
|
The Liquibase component to run checks against, which can be a comma separated list See checks-scope. |
Optional |
|
Specifies the checks settings file to use with subcommands. Write the relative path of the settings file that you want to read from or modify. For more information, see Use the Checks Settings Configuration File. |
Optional |
|
Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Note: If you use Liquibase 4.23.0 or earlier, use the syntax |
Optional |
|
Optional | |
|
Optional | |
|
Optional | |
|
Optional | |
|
Only Available in Liquibase Pro Sets the format of the check output to text or JSON. Default: text For more information, see Quality Checks JSON Object. |
Optional |
|
Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run. |
Optional |
|
Password to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
|
|
Allows you to check to see if changeset text is evaluated pre or post property substitution. This argument is for the whole of checks run , not a specific quality check. Default: true |
Optional |
|
Enables a report at the command level. Overrides the global argument |
Optional |
|
Specifies the name of the report file at the command level. Overrides the global argument |
Optional |
|
Specifies the file path to the report file at the command level. Overrides the global argument |
Optional |
|
The schemas to check when checks-scope contains database |
Optional |
|
Allows specification of the severity value returned when a check fails due to a SQL parse error. Return Codes: Default: severity of the check
|
Optional |
|
Username to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Specifies the detail level of the command's output. Default: |
Optional |
Global parameters
Parameter | Definition | Requirement |
---|---|---|
|
Your Liquibase Pro license key |
Required |
Command parameters
Parameter | Description | Requirement |
---|---|---|
|
The changelog file against which you execute checks when running |
Required (either this or --url ) |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required (either this or --changelog-file ) |
|
Optional | |
|
Allows automatic backup and updating of the Default: off |
Optional |
|
If true, sqlFile change type contents will be cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true | Optional |
|
Specifies whether quality checks run on |
Optional |
|
Use this to specify the short name of the check you want to target with one of the following subcommands:
|
Optional |
|
Allow changeset's rollback code to be analyzed for compliance with currently enabled quality checks. Default: false | Optional |
|
Specify which parts of the checks run output should be shown. Options:
Default: all |
Optional |
|
Optional | |
|
The Liquibase component to run checks against, which can be a comma separated list See checks-scope. |
Optional |
|
Specifies the checks settings file to use with subcommands. Write the relative path of the settings file that you want to read from or modify. For more information, see Use the Checks Settings Configuration File. |
Optional |
|
Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Note: If you use Liquibase 4.23.0 or earlier, use the syntax |
Optional |
|
Optional | |
|
Optional | |
|
Optional | |
|
Optional | |
|
Only Available in Liquibase Pro Sets the format of the check output to text or JSON. Default: text For more information, see Quality Checks JSON Object. |
Optional |
|
Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run. |
Optional |
|
Password to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
|
|
Allows you to check to see if changeset text is evaluated pre or post property substitution. This argument is for the whole of checks run , not a specific quality check. Default: true |
Optional |
|
Enables a report at the command level. Overrides the global argument |
Optional |
|
Specifies the name of the report file at the command level. Overrides the global argument |
Optional |
|
Specifies the file path to the report file at the command level. Overrides the global argument |
Optional |
|
The schemas to check when checks-scope contains database |
Optional |
|
Allows specification of the severity value returned when a check fails due to a SQL parse error. Return Codes: Default: severity of the check
|
Optional |
|
Username to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Specifies the detail level of the command's output. Default: |
Optional |
Global parameters
Parameter | Definition | Requirement |
---|---|---|
|
Your Liquibase Pro license key |
Required |
Command parameters
Parameter | Description | Requirement |
---|---|---|
|
The changelog file against which you execute checks when running |
Required (either this or --url ) |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required (either this or --changelog-file ) |
|
Optional | |
|
Allows automatic backup and updating of the Default: off |
Optional |
|
If true, sqlFile change type contents will be cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true | Optional |
|
Specifies whether quality checks run on |
Optional |
|
Use this to specify the short name of the check you want to target with one of the following subcommands:
|
Optional |
|
Allow changeset's rollback code to be analyzed for compliance with currently enabled quality checks. Default: false | Optional |
|
Specify which parts of the checks run output should be shown. Options:
Default: all |
Optional |
|
Optional | |
|
The Liquibase component to run checks against, which can be a comma separated list See checks-scope. |
Optional |
|
Specifies the checks settings file to use with subcommands. Write the relative path of the settings file that you want to read from or modify. For more information, see Use the Checks Settings Configuration File. |
Optional |
|
Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Note: If you use Liquibase 4.23.0 or earlier, use the syntax |
Optional |
|
Optional | |
|
Optional | |
|
Optional | |
|
Optional | |
|
Only Available in Liquibase Pro Sets the format of the check output to text or JSON. Default: text For more information, see Quality Checks JSON Object. |
Optional |
|
Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run. |
Optional |
|
Password to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
|
|
Allows you to check to see if changeset text is evaluated pre or post property substitution. This argument is for the whole of checks run , not a specific quality check. Default: true |
Optional |
|
Enables a report at the command level. Overrides the global argument |
Optional |
|
Specifies the name of the report file at the command level. Overrides the global argument |
Optional |
|
Specifies the file path to the report file at the command level. Overrides the global argument |
Optional |
|
The schemas to check when checks-scope contains database |
Optional |
|
Allows specification of the severity value returned when a check fails due to a SQL parse error. Return Codes: Default: severity of the check
|
Optional |
|
Username to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Specifies the detail level of the command's output. Default: |
Optional |
Global parameters
Parameter | Definition | Requirement |
---|---|---|
|
Your Liquibase Pro license key |
Required |
Command parameters
Parameter | Description | Requirement |
---|---|---|
|
The changelog file against which you execute checks when running |
Required (either this or --url ) |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required (either this or --changelog-file ) |
|
Optional | |
|
Allows automatic backup and updating of the Default: off |
Optional |
|
If true, sqlFile change type contents will be cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true | Optional |
|
Specifies whether quality checks run on |
Optional |
|
Use this to specify the short name of the check you want to target with one of the following subcommands:
|
Optional |
|
Allow changeset's rollback code to be analyzed for compliance with currently enabled quality checks. Default: false | Optional |
|
Specify which parts of the checks run output should be shown. Options:
Default: all |
Optional |
|
Optional | |
|
The Liquibase component to run checks against, which can be a comma separated list See checks-scope. |
Optional |
|
Specifies the checks settings file to use with subcommands. Write the relative path of the settings file that you want to read from or modify. For more information, see Use the Checks Settings Configuration File. |
Optional |
|
Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Note: If you use Liquibase 4.23.0 or earlier, use the syntax |
Optional |
|
Optional | |
|
Optional | |
|
Optional | |
|
Optional | |
|
Only Available in Liquibase Pro Sets the format of the check output to text or JSON. Default: text For more information, see Quality Checks JSON Object. |
Optional |
|
Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run. |
Optional |
|
Password to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
|
|
Allows you to check to see if changeset text is evaluated pre or post property substitution. This argument is for the whole of checks run , not a specific quality check. Default: true |
Optional |
|
Enables a report at the command level. Overrides the global argument |
Optional |
|
Specifies the name of the report file at the command level. Overrides the global argument |
Optional |
|
Specifies the file path to the report file at the command level. Overrides the global argument |
Optional |
|
The schemas to check when checks-scope contains database |
Optional |
|
Allows specification of the severity value returned when a check fails due to a SQL parse error. Return Codes: Default: severity of the check
|
Optional |
|
Username to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Specifies the detail level of the command's output. Default: |
Optional |
Global parameters
Parameter | Definition | Requirement |
---|---|---|
|
Your Liquibase Pro license key |
Required |
Command parameters
Parameter | Description | Requirement |
---|---|---|
|
The changelog file against which you execute checks when running |
Required (either this or --url ) |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required (either this or --changelog-file ) |
|
Optional | |
|
Allows automatic backup and updating of the Default: off |
Optional |
|
If true, sqlFile change type contents will be cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true | Optional |
|
Specifies whether quality checks run on |
Optional |
|
Use this to specify the short name of the check you want to target with one of the following subcommands:
|
Optional |
|
Allow changeset's rollback code to be analyzed for compliance with currently enabled quality checks. Default: false | Optional |
|
Specify which parts of the checks run output should be shown. Options:
Default: all |
Optional |
|
Optional | |
|
The Liquibase component to run checks against, which can be a comma separated list See checks-scope. |
Optional |
|
Specifies the checks settings file to use with subcommands. Write the relative path of the settings file that you want to read from or modify. For more information, see Use the Checks Settings Configuration File. |
Optional |
|
Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Note: If you use Liquibase 4.23.0 or earlier, use the syntax |
Optional |
|
Optional | |
|
Optional | |
|
Optional | |
|
Optional | |
|
Only Available in Liquibase Pro Sets the format of the check output to text or JSON. Default: text For more information, see Quality Checks JSON Object. |
Optional |
|
Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run. |
Optional |
|
Password to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
|
|
Allows you to check to see if changeset text is evaluated pre or post property substitution. This argument is for the whole of checks run , not a specific quality check. Default: true |
Optional |
|
Enables a report at the command level. Overrides the global argument |
Optional |
|
Specifies the name of the report file at the command level. Overrides the global argument |
Optional |
|
Specifies the file path to the report file at the command level. Overrides the global argument |
Optional |
|
The schemas to check when checks-scope contains database |
Optional |
|
Allows specification of the severity value returned when a check fails due to a SQL parse error. Return Codes: Default: severity of the check
|
Optional |
|
Username to connect to the target database. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Specifies the detail level of the command's output. Default: |
Optional |
run
example output
Starting Liquibase at 13:53:58 (version 4.9.1 #1978 built at 2022-03-28 19:39+0000)
Liquibase Version: 4.9.1
Executing Quality Checks against example-changelog.sql
Executing all checks because a valid Liquibase Pro license was found!
Changesets Validated:
ID: 1; Author: Amber.Williams; File path: example-changelog.sql
ID: 2; Author: Amber.Williams; File path: example-changelog.sql
ID: 3; Author: other.dev; File path: example-changelog.sql
Checks run against each changeset:
Warn on Detection of 'GRANT' Statements
Warn on Detection of 'REVOKE' Statements
Warn when 'DROP TABLE' detected
Warn when 'DROP COLUMN' detected
Warn when 'MODIFY column' detected
Check Table Column Count (Short Name: 1234)
Check Table Column Count
Warn when 'TRUNCATE TABLE' detected
Warn on Detection of grant that contains 'WITH GRANT OPTION'
Warn on Detection of grant that contains 'WITH ADMIN OPTION'
Rollback Required for Changeset
Changesets Must Have a Label Assigned
Changesets Must Have a Context Assigned
Changesets Must Have a Comment Assigned
Liquibase command 'checks run' was executed successfully.