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. Policy 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 Report for your database.

Note: To view a list of available checks, run liquibase checks show.

In Liquibase 4.29.0 and later, you can use checks run to run Custom Policy Checks.

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

--license-key=<string>

Your Liquibase Pro license key

 Required

Command parameters

Parameter Description Requirement

--changelog-file=<string>

The changelog file against which you execute checks when running liquibase checks run.

 Required (either this or --url)

--url=<string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

 Required (either this or --changelog-file)

--auto-enable-new-checks=<true|false>

Automatically enable new policy checks in liquibase.checks.conf file when they are available. Default: false.

 Optional

--auto-update=<string>

Allows automatic backup and updating of the liquibase.checks-settings.conf file when new policy checks are available. Valid values are ON and OFF. Default: OFF.

 Optional

--cache-changelog-file-contents=<true|false>

If true, sqlFile Change Type contents are cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true

 Optional

--changeset-filter=<string>

Specifies whether policy checks run on ALL changesets or only PENDING (undeployed) changesets. Only applies to checks with the "changelog" scope. Liquibase 4.26.0+. Default: ALL.

 Optional

--check-name=<string>

The name of the check(s) you want to target. Comma-separated list of one or more enabled checks. Checks to exclude can be prefixed with the ! character. If no checks are specified, all enabled checks are targeted. For example: --check-name=shortname1,shortname2,!shortname3

 Optional

--check-rollbacks=<true|false>

Allow changeset's rollback code to be analyzed for compliance with currently enabled policy checks. Default: false

 Optional

--checks-output=<string>

Specify which parts of the checks run output should be shown. Options:

  • all: show all sections
  • issues: show the triggered checks
  • issues0: show the issues with severity 0
  • issues1: show the issues with severity 1
  • issues2: show the issues with severity 2
  • issues3: show the issues with severity 3
  • issues4: show the issues with severity 4
  • validated: show the section that starts with "Changesets Validated"
  • checksrun: show the section that starts with "Checks run against each changeset"
  • sqlparserfails: show the section that starts with "Changeset SQL not parsed in..."
  • skippedchecks: show the section that starts with "Changelogs Checks Skipped Due to unsupported changeset..." (such as checks skipped due to version incompatibility)
  • nonapplicablechecks: show chained checks which cannot be evaluated due to their configurations conflicting (such as a chained check that evaluates TableColumnLimit && ObjectNameMustMatch, where TableColumnLimit only evaluates tables and ObjectNameMustMatch is configured to only evaluate indexes).

Default: all

Optional

--checks-packages=<string>

If using a checks packages file, optionally specify which packages should be run from the file as a comma-separated list.

 Optional

--checks-scope=<string>

The Liquibase component to run checks against, which can be a comma-separated list. Valid values are changelog and database. Default: changelog. See checks-scope.

 Optional

--checks-scripts-enabled=<true|false>

Allow execution of custom script checks. For more information, see Custom Policy Checks. Default: false

 Optional

--checks-scripts-path=<string>

Only allow custom scripts found in the specified directories to execute. If not set, Liquibase allows custom scripts from any location to execute. For more information, see Custom Policy Checks.

 Optional

--checks-settings-file=<string>

Specifies the checks settings file to use with commands. 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

--context-filter=<string>

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 --contexts instead of --context-filter.

 Optional

--default-catalog-name=<string>

Name of the default catalog to use for the database connection

 Optional

--default-schema-name=<string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

 Optional

--driver=<string>

The JDBC driver class

 Optional

--driver-properties-file=<string>

The JDBC driver properties file

 Optional

--format=<string>

Sets the format of the check output to text or JSON. Valid values are TXT, JSON. Default: TXT. For more information, see Policy Checks JSON Object.

 Optional

--label-filter=<string>

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=<string>

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.

  

--property-substitution-enabled=<true|false>

If set to true, changesets are evaluated by checks run after property substitution. If set to false, changesets are evaluated by checks run before property substitution, meaning the names of the "property substitution tokens" are evaluated. Default: true. For more information, see property-substitution-enabled.

 Optional

--report-enabled=<true|false>

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

 Optional

--report-name=<string>

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

 Optional

--report-path=<string>

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

 Optional

--schemas=<string>

The schemas to check when --checks-scope contains database.

 Optional

--sql-parser-fail-severity=<string>

Specifies the severity value returned when a check fails due to a SQL parse error. Valid values are the following return codes:

  • 0 is INFO
  • 1 is MINOR
  • 2 is MAJOR
  • 3 is CRITICAL
  • 4 is BLOCKER

Default: severity of the executed check

Optional

--username=<string>

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

--verbose=<true|false>

Specifies the detail level of the command's output. Default: false.

 Optional

Global parameters

Parameter Definition Requirement

globalArgs: { license-key: "<string>" }

Your Liquibase Pro license key

 Required

Command parameters

Parameter Description Requirement

cmdArgs: { changelog-file: "<string>" }

The changelog file against which you execute checks when running liquibase checks run.

 Required (either this or --url)

cmdArgs: { url: "<string>" }

The JDBC database connection URL. See Using JDBC URL in Liquibase.

 Required (either this or --changelog-file)

cmdArgs: { auto-enable-new-checks: "<true|false>" }

Automatically enable new policy checks in liquibase.checks.conf file when they are available. Default: false.

 Optional

cmdArgs: { auto-update: "<string>" }

Allows automatic backup and updating of the liquibase.checks-settings.conf file when new policy checks are available. Valid values are ON and OFF. Default: OFF.

 Optional

cmdArgs: { cache-changelog-file-contents: "<true|false>" }

If true, sqlFile Change Type contents are cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true

 Optional

cmdArgs: { changeset-filter: "<string>" }

Specifies whether policy checks run on ALL changesets or only PENDING (undeployed) changesets. Only applies to checks with the "changelog" scope. Liquibase 4.26.0+. Default: ALL.

 Optional

cmdArgs: { check-name: "<string>" }

The name of the check(s) you want to target. Comma-separated list of one or more enabled checks. Checks to exclude can be prefixed with the ! character. If no checks are specified, all enabled checks are targeted. For example: --check-name=shortname1,shortname2,!shortname3

 Optional

cmdArgs: { check-rollbacks: "<true|false>" }

Allow changeset's rollback code to be analyzed for compliance with currently enabled policy checks. Default: false

 Optional

cmdArgs: { checks-output: "<string>" }

Specify which parts of the checks run output should be shown. Options:

  • all: show all sections
  • issues: show the triggered checks
  • issues0: show the issues with severity 0
  • issues1: show the issues with severity 1
  • issues2: show the issues with severity 2
  • issues3: show the issues with severity 3
  • issues4: show the issues with severity 4
  • validated: show the section that starts with "Changesets Validated"
  • checksrun: show the section that starts with "Checks run against each changeset"
  • sqlparserfails: show the section that starts with "Changeset SQL not parsed in..."
  • skippedchecks: show the section that starts with "Changelogs Checks Skipped Due to unsupported changeset..." (such as checks skipped due to version incompatibility)
  • nonapplicablechecks: show chained checks which cannot be evaluated due to their configurations conflicting (such as a chained check that evaluates TableColumnLimit && ObjectNameMustMatch, where TableColumnLimit only evaluates tables and ObjectNameMustMatch is configured to only evaluate indexes).

Default: all

Optional

cmdArgs: { checks-packages: "<string>" }

If using a checks packages file, optionally specify which packages should be run from the file as a comma-separated list.

 Optional

cmdArgs: { checks-scope: "<string>" }

The Liquibase component to run checks against, which can be a comma-separated list. Valid values are changelog and database. Default: changelog. See checks-scope.

 Optional

cmdArgs: { checks-scripts-enabled: "<true|false>" }

Allow execution of custom script checks. For more information, see Custom Policy Checks. Default: false

 Optional

cmdArgs: { checks-scripts-path: "<string>" }

Only allow custom scripts found in the specified directories to execute. If not set, Liquibase allows custom scripts from any location to execute. For more information, see Custom Policy Checks.

 Optional

cmdArgs: { checks-settings-file: "<string>" }

Specifies the checks settings file to use with commands. 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

cmdArgs: { context-filter: "<string>" }

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 --contexts instead of --context-filter.

 Optional

cmdArgs: { default-catalog-name: "<string>" }

Name of the default catalog to use for the database connection

 Optional

cmdArgs: { default-schema-name: "<string>" }

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

 Optional

cmdArgs: { driver: "<string>" }

The JDBC driver class

 Optional

cmdArgs: { driver-properties-file: "<string>" }

The JDBC driver properties file

 Optional

cmdArgs: { format: "<string>" }

Sets the format of the check output to text or JSON. Valid values are TXT, JSON. Default: TXT. For more information, see Policy Checks JSON Object.

 Optional

cmdArgs: { label-filter: "<string>" }

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

cmdArgs: { password: "<string>" }

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.

  

cmdArgs: { property-substitution-enabled: "<true|false>" }

If set to true, changesets are evaluated by checks run after property substitution. If set to false, changesets are evaluated by checks run before property substitution, meaning the names of the "property substitution tokens" are evaluated. Default: true. For more information, see property-substitution-enabled.

 Optional

cmdArgs: { report-enabled: "<true|false>" }

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

 Optional

cmdArgs: { report-name: "<string>" }

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

 Optional

cmdArgs: { report-path: "<string>" }

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

 Optional

cmdArgs: { schemas: "<string>" }

The schemas to check when --checks-scope contains database.

 Optional

cmdArgs: { sql-parser-fail-severity: "<string>" }

Specifies the severity value returned when a check fails due to a SQL parse error. Valid values are the following return codes:

  • 0 is INFO
  • 1 is MINOR
  • 2 is MAJOR
  • 3 is CRITICAL
  • 4 is BLOCKER

Default: severity of the executed check

Optional

cmdArgs: { username: "<string>" }

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

cmdArgs: { verbose: "<true|false>" }

Specifies the detail level of the command's output. Default: false.

 Optional

Global parameters

Parameter Definition Requirement

liquibase.licenseKey: <string>

Your Liquibase Pro license key

 Required

Command parameters

Parameter Description Requirement

liquibase.command.changelogFile: <string>

liquibase.command.checks.run.changelogFile: <string>

The changelog file against which you execute checks when running liquibase checks run.

 Required (either this or --url)

liquibase.command.url: <string>

liquibase.command.checks.run.url: <string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

 Required (either this or --changelog-file)

liquibase.command.autoEnableNewChecks: <true|false>

liquibase.command.checks.run.autoEnableNewChecks: <true|false>

Automatically enable new policy checks in liquibase.checks.conf file when they are available. Default: false.

 Optional

liquibase.command.autoUpdate: <string>

liquibase.command.checks.run.autoUpdate: <string>

Allows automatic backup and updating of the liquibase.checks-settings.conf file when new policy checks are available. Valid values are ON and OFF. Default: OFF.

 Optional

liquibase.command.cacheChangelogFileContents: <true|false>

liquibase.command.checks.run.cacheChangelogFileContents: <true|false>

If true, sqlFile Change Type contents are cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true

 Optional

liquibase.command.changesetFilter: <string>

liquibase.command.checks.run.changesetFilter: <string>

Specifies whether policy checks run on ALL changesets or only PENDING (undeployed) changesets. Only applies to checks with the "changelog" scope. Liquibase 4.26.0+. Default: ALL.

 Optional

liquibase.command.checkName: <string>

liquibase.command.checks.run.checkName: <string>

The name of the check(s) you want to target. Comma-separated list of one or more enabled checks. Checks to exclude can be prefixed with the ! character. If no checks are specified, all enabled checks are targeted. For example: --check-name=shortname1,shortname2,!shortname3

 Optional

liquibase.command.checkRollbacks: <true|false>

liquibase.command.checks.run.checkRollbacks: <true|false>

Allow changeset's rollback code to be analyzed for compliance with currently enabled policy checks. Default: false

 Optional

liquibase.command.checksOutput: <string>

liquibase.command.checks.run.checksOutput: <string>

Specify which parts of the checks run output should be shown. Options:

  • all: show all sections
  • issues: show the triggered checks
  • issues0: show the issues with severity 0
  • issues1: show the issues with severity 1
  • issues2: show the issues with severity 2
  • issues3: show the issues with severity 3
  • issues4: show the issues with severity 4
  • validated: show the section that starts with "Changesets Validated"
  • checksrun: show the section that starts with "Checks run against each changeset"
  • sqlparserfails: show the section that starts with "Changeset SQL not parsed in..."
  • skippedchecks: show the section that starts with "Changelogs Checks Skipped Due to unsupported changeset..." (such as checks skipped due to version incompatibility)
  • nonapplicablechecks: show chained checks which cannot be evaluated due to their configurations conflicting (such as a chained check that evaluates TableColumnLimit && ObjectNameMustMatch, where TableColumnLimit only evaluates tables and ObjectNameMustMatch is configured to only evaluate indexes).

Default: all

Optional

liquibase.command.checksPackages: <string>

liquibase.command.checks.run.checksPackages: <string>

If using a checks packages file, optionally specify which packages should be run from the file as a comma-separated list.

 Optional

liquibase.command.checksScope: <string>

liquibase.command.checks.run.checksScope: <string>

The Liquibase component to run checks against, which can be a comma-separated list. Valid values are changelog and database. Default: changelog. See checks-scope.

 Optional

liquibase.command.checksScriptsEnabled: <true|false>

liquibase.command.checks.run.checksScriptsEnabled: <true|false>

Allow execution of custom script checks. For more information, see Custom Policy Checks. Default: false

 Optional

liquibase.command.checksScriptsPath: <string>

liquibase.command.checks.run.checksScriptsPath: <string>

Only allow custom scripts found in the specified directories to execute. If not set, Liquibase allows custom scripts from any location to execute. For more information, see Custom Policy Checks.

 Optional

liquibase.command.checksSettingsFile: <string>

liquibase.command.checks.run.checksSettingsFile: <string>

Specifies the checks settings file to use with commands. 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

liquibase.command.contextFilter: <string>

liquibase.command.checks.run.contextFilter: <string>

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 --contexts instead of --context-filter.

 Optional

liquibase.command.defaultCatalogName: <string>

liquibase.command.checks.run.defaultCatalogName: <string>

Name of the default catalog to use for the database connection

 Optional

liquibase.command.defaultSchemaName: <string>

liquibase.command.checks.run.defaultSchemaName: <string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

 Optional

liquibase.command.driver: <string>

liquibase.command.checks.run.driver: <string>

The JDBC driver class

 Optional

liquibase.command.driverPropertiesFile: <string>

liquibase.command.checks.run.driverPropertiesFile: <string>

The JDBC driver properties file

 Optional

liquibase.command.format: <string>

liquibase.command.checks.run.format: <string>

Sets the format of the check output to text or JSON. Valid values are TXT, JSON. Default: TXT. For more information, see Policy Checks JSON Object.

 Optional

liquibase.command.labelFilter: <string>

liquibase.command.checks.run.labelFilter: <string>

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

liquibase.command.password: <string>

liquibase.command.checks.run.password: <string>

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.

  

liquibase.command.propertySubstitutionEnabled: <true|false>

liquibase.command.checks.run.propertySubstitutionEnabled: <true|false>

If set to true, changesets are evaluated by checks run after property substitution. If set to false, changesets are evaluated by checks run before property substitution, meaning the names of the "property substitution tokens" are evaluated. Default: true. For more information, see property-substitution-enabled.

 Optional

liquibase.command.reportEnabled: <true|false>

liquibase.command.checks.run.reportEnabled: <true|false>

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

 Optional

liquibase.command.reportName: <string>

liquibase.command.checks.run.reportName: <string>

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

 Optional

liquibase.command.reportPath: <string>

liquibase.command.checks.run.reportPath: <string>

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

 Optional

liquibase.command.schemas: <string>

liquibase.command.checks.run.schemas: <string>

The schemas to check when --checks-scope contains database.

 Optional

liquibase.command.sqlParserFailSeverity: <string>

liquibase.command.checks.run.sqlParserFailSeverity: <string>

Specifies the severity value returned when a check fails due to a SQL parse error. Valid values are the following return codes:

  • 0 is INFO
  • 1 is MINOR
  • 2 is MAJOR
  • 3 is CRITICAL
  • 4 is BLOCKER

Default: severity of the executed check

Optional

liquibase.command.username: <string>

liquibase.command.checks.run.username: <string>

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

liquibase.command.verbose: <true|false>

liquibase.command.checks.run.verbose: <true|false>

Specifies the detail level of the command's output. Default: false.

 Optional

Global parameters

Parameter Definition Requirement

JAVA_OPTS=-Dliquibase.licenseKey=<string>

Your Liquibase Pro license key

 Required

Command parameters

Parameter Description Requirement

JAVA_OPTS=-Dliquibase.command.changelogFile=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.changelogFile=<string>

The changelog file against which you execute checks when running liquibase checks run.

 Required (either this or --url)

JAVA_OPTS=-Dliquibase.command.url=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.url=<string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

 Required (either this or --changelog-file)

JAVA_OPTS=-Dliquibase.command.autoEnableNewChecks=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.autoEnableNewChecks=<true|false>

Automatically enable new policy checks in liquibase.checks.conf file when they are available. Default: false.

 Optional

JAVA_OPTS=-Dliquibase.command.autoUpdate=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.autoUpdate=<string>

Allows automatic backup and updating of the liquibase.checks-settings.conf file when new policy checks are available. Valid values are ON and OFF. Default: OFF.

 Optional

JAVA_OPTS=-Dliquibase.command.cacheChangelogFileContents=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.cacheChangelogFileContents=<true|false>

If true, sqlFile Change Type contents are cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true

 Optional

JAVA_OPTS=-Dliquibase.command.changesetFilter=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.changesetFilter=<string>

Specifies whether policy checks run on ALL changesets or only PENDING (undeployed) changesets. Only applies to checks with the "changelog" scope. Liquibase 4.26.0+. Default: ALL.

 Optional

JAVA_OPTS=-Dliquibase.command.checkName=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.checkName=<string>

The name of the check(s) you want to target. Comma-separated list of one or more enabled checks. Checks to exclude can be prefixed with the ! character. If no checks are specified, all enabled checks are targeted. For example: --check-name=shortname1,shortname2,!shortname3

 Optional

JAVA_OPTS=-Dliquibase.command.checkRollbacks=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.checkRollbacks=<true|false>

Allow changeset's rollback code to be analyzed for compliance with currently enabled policy checks. Default: false

 Optional

JAVA_OPTS=-Dliquibase.command.checksOutput=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.checksOutput=<string>

Specify which parts of the checks run output should be shown. Options:

  • all: show all sections
  • issues: show the triggered checks
  • issues0: show the issues with severity 0
  • issues1: show the issues with severity 1
  • issues2: show the issues with severity 2
  • issues3: show the issues with severity 3
  • issues4: show the issues with severity 4
  • validated: show the section that starts with "Changesets Validated"
  • checksrun: show the section that starts with "Checks run against each changeset"
  • sqlparserfails: show the section that starts with "Changeset SQL not parsed in..."
  • skippedchecks: show the section that starts with "Changelogs Checks Skipped Due to unsupported changeset..." (such as checks skipped due to version incompatibility)
  • nonapplicablechecks: show chained checks which cannot be evaluated due to their configurations conflicting (such as a chained check that evaluates TableColumnLimit && ObjectNameMustMatch, where TableColumnLimit only evaluates tables and ObjectNameMustMatch is configured to only evaluate indexes).

Default: all

Optional

JAVA_OPTS=-Dliquibase.command.checksPackages=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.checksPackages=<string>

If using a checks packages file, optionally specify which packages should be run from the file as a comma-separated list.

 Optional

JAVA_OPTS=-Dliquibase.command.checksScope=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.checksScope=<string>

The Liquibase component to run checks against, which can be a comma-separated list. Valid values are changelog and database. Default: changelog. See checks-scope.

 Optional

JAVA_OPTS=-Dliquibase.command.checksScriptsEnabled=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.checksScriptsEnabled=<true|false>

Allow execution of custom script checks. For more information, see Custom Policy Checks. Default: false

 Optional

JAVA_OPTS=-Dliquibase.command.checksScriptsPath=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.checksScriptsPath=<string>

Only allow custom scripts found in the specified directories to execute. If not set, Liquibase allows custom scripts from any location to execute. For more information, see Custom Policy Checks.

 Optional

JAVA_OPTS=-Dliquibase.command.checksSettingsFile=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.checksSettingsFile=<string>

Specifies the checks settings file to use with commands. 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

JAVA_OPTS=-Dliquibase.command.contextFilter=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.contextFilter=<string>

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 --contexts instead of --context-filter.

 Optional

JAVA_OPTS=-Dliquibase.command.defaultCatalogName=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.defaultCatalogName=<string>

Name of the default catalog to use for the database connection

 Optional

JAVA_OPTS=-Dliquibase.command.defaultSchemaName=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.defaultSchemaName=<string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

 Optional

JAVA_OPTS=-Dliquibase.command.driver=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.driver=<string>

The JDBC driver class

 Optional

JAVA_OPTS=-Dliquibase.command.driverPropertiesFile=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.driverPropertiesFile=<string>

The JDBC driver properties file

 Optional

JAVA_OPTS=-Dliquibase.command.format=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.format=<string>

Sets the format of the check output to text or JSON. Valid values are TXT, JSON. Default: TXT. For more information, see Policy Checks JSON Object.

 Optional

JAVA_OPTS=-Dliquibase.command.labelFilter=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.labelFilter=<string>

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

JAVA_OPTS=-Dliquibase.command.password=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.password=<string>

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.

  

JAVA_OPTS=-Dliquibase.command.propertySubstitutionEnabled=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.propertySubstitutionEnabled=<true|false>

If set to true, changesets are evaluated by checks run after property substitution. If set to false, changesets are evaluated by checks run before property substitution, meaning the names of the "property substitution tokens" are evaluated. Default: true. For more information, see property-substitution-enabled.

 Optional

JAVA_OPTS=-Dliquibase.command.reportEnabled=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.reportEnabled=<true|false>

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

 Optional

JAVA_OPTS=-Dliquibase.command.reportName=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.reportName=<string>

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

 Optional

JAVA_OPTS=-Dliquibase.command.reportPath=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.reportPath=<string>

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

 Optional

JAVA_OPTS=-Dliquibase.command.schemas=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.schemas=<string>

The schemas to check when --checks-scope contains database.

 Optional

JAVA_OPTS=-Dliquibase.command.sqlParserFailSeverity=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.sqlParserFailSeverity=<string>

Specifies the severity value returned when a check fails due to a SQL parse error. Valid values are the following return codes:

  • 0 is INFO
  • 1 is MINOR
  • 2 is MAJOR
  • 3 is CRITICAL
  • 4 is BLOCKER

Default: severity of the executed check

Optional

JAVA_OPTS=-Dliquibase.command.username=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.username=<string>

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

JAVA_OPTS=-Dliquibase.command.verbose=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.verbose=<true|false>

Specifies the detail level of the command's output. Default: false.

 Optional

Global parameters

Parameter Definition Requirement

LIQUIBASE_LICENSE_KEY=<string>

Your Liquibase Pro license key

 Required

Command parameters

Parameter Description Requirement

LIQUIBASE_COMMAND_CHANGELOG_FILE=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHANGELOG_FILE=<string>

The changelog file against which you execute checks when running liquibase checks run.

 Required (either this or --url)

LIQUIBASE_COMMAND_URL=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_URL=<string>

The JDBC database connection URL. See Using JDBC URL in Liquibase.

 Required (either this or --changelog-file)

LIQUIBASE_COMMAND_AUTO_ENABLE_NEW_CHECKS=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_AUTO_ENABLE_NEW_CHECKS=<true|false>

Automatically enable new policy checks in liquibase.checks.conf file when they are available. Default: false.

 Optional

LIQUIBASE_COMMAND_AUTO_UPDATE=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_AUTO_UPDATE=<string>

Allows automatic backup and updating of the liquibase.checks-settings.conf file when new policy checks are available. Valid values are ON and OFF. Default: OFF.

 Optional

LIQUIBASE_COMMAND_CACHE_CHANGELOG_FILE_CONTENTS=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_CACHE_CHANGELOG_FILE_CONTENTS=<true|false>

If true, sqlFile Change Type contents are cached in memory to improve performance, at the cost of higher memory usage. To reduce memory usage, set this to false. Default: true

 Optional

LIQUIBASE_COMMAND_CHANGESET_FILTER=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHANGESET_FILTER=<string>

Specifies whether policy checks run on ALL changesets or only PENDING (undeployed) changesets. Only applies to checks with the "changelog" scope. Liquibase 4.26.0+. Default: ALL.

 Optional

LIQUIBASE_COMMAND_CHECK_NAME=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECK_NAME=<string>

The name of the check(s) you want to target. Comma-separated list of one or more enabled checks. Checks to exclude can be prefixed with the ! character. If no checks are specified, all enabled checks are targeted. For example: --check-name=shortname1,shortname2,!shortname3

 Optional

LIQUIBASE_COMMAND_CHECK_ROLLBACKS=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECK_ROLLBACKS=<true|false>

Allow changeset's rollback code to be analyzed for compliance with currently enabled policy checks. Default: false

 Optional

LIQUIBASE_COMMAND_CHECKS_OUTPUT=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_OUTPUT=<string>

Specify which parts of the checks run output should be shown. Options:

  • all: show all sections
  • issues: show the triggered checks
  • issues0: show the issues with severity 0
  • issues1: show the issues with severity 1
  • issues2: show the issues with severity 2
  • issues3: show the issues with severity 3
  • issues4: show the issues with severity 4
  • validated: show the section that starts with "Changesets Validated"
  • checksrun: show the section that starts with "Checks run against each changeset"
  • sqlparserfails: show the section that starts with "Changeset SQL not parsed in..."
  • skippedchecks: show the section that starts with "Changelogs Checks Skipped Due to unsupported changeset..." (such as checks skipped due to version incompatibility)
  • nonapplicablechecks: show chained checks which cannot be evaluated due to their configurations conflicting (such as a chained check that evaluates TableColumnLimit && ObjectNameMustMatch, where TableColumnLimit only evaluates tables and ObjectNameMustMatch is configured to only evaluate indexes).

Default: all

Optional

LIQUIBASE_COMMAND_CHECKS_PACKAGES=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_PACKAGES=<string>

If using a checks packages file, optionally specify which packages should be run from the file as a comma-separated list.

 Optional

LIQUIBASE_COMMAND_CHECKS_SCOPE=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCOPE=<string>

The Liquibase component to run checks against, which can be a comma-separated list. Valid values are changelog and database. Default: changelog. See checks-scope.

 Optional

LIQUIBASE_COMMAND_CHECKS_SCRIPTS_ENABLED=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCRIPTS_ENABLED=<true|false>

Allow execution of custom script checks. For more information, see Custom Policy Checks. Default: false

 Optional

LIQUIBASE_COMMAND_CHECKS_SCRIPTS_PATH=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCRIPTS_PATH=<string>

Only allow custom scripts found in the specified directories to execute. If not set, Liquibase allows custom scripts from any location to execute. For more information, see Custom Policy Checks.

 Optional

LIQUIBASE_COMMAND_CHECKS_SETTINGS_FILE=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SETTINGS_FILE=<string>

Specifies the checks settings file to use with commands. 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

LIQUIBASE_COMMAND_CONTEXT_FILTER=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_CONTEXT_FILTER=<string>

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 --contexts instead of --context-filter.

 Optional

LIQUIBASE_COMMAND_DEFAULT_CATALOG_NAME=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_DEFAULT_CATALOG_NAME=<string>

Name of the default catalog to use for the database connection

 Optional

LIQUIBASE_COMMAND_DEFAULT_SCHEMA_NAME=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_DEFAULT_SCHEMA_NAME=<string>

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

 Optional

LIQUIBASE_COMMAND_DRIVER=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_DRIVER=<string>

The JDBC driver class

 Optional

LIQUIBASE_COMMAND_DRIVER_PROPERTIES_FILE=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_DRIVER_PROPERTIES_FILE=<string>

The JDBC driver properties file

 Optional

LIQUIBASE_COMMAND_FORMAT=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_FORMAT=<string>

Sets the format of the check output to text or JSON. Valid values are TXT, JSON. Default: TXT. For more information, see Policy Checks JSON Object.

 Optional

LIQUIBASE_COMMAND_LABEL_FILTER=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_LABEL_FILTER=<string>

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

LIQUIBASE_COMMAND_PASSWORD=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_PASSWORD=<string>

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.

  

LIQUIBASE_COMMAND_PROPERTY_SUBSTITUTION_ENABLED=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_PROPERTY_SUBSTITUTION_ENABLED=<true|false>

If set to true, changesets are evaluated by checks run after property substitution. If set to false, changesets are evaluated by checks run before property substitution, meaning the names of the "property substitution tokens" are evaluated. Default: true. For more information, see property-substitution-enabled.

 Optional

LIQUIBASE_COMMAND_REPORT_ENABLED=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_ENABLED=<true|false>

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

 Optional

LIQUIBASE_COMMAND_REPORT_NAME=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_NAME=<string>

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

 Optional

LIQUIBASE_COMMAND_REPORT_PATH=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_PATH=<string>

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

 Optional

LIQUIBASE_COMMAND_SCHEMAS=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_SCHEMAS=<string>

The schemas to check when --checks-scope contains database.

 Optional

LIQUIBASE_COMMAND_SQL_PARSER_FAIL_SEVERITY=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_SQL_PARSER_FAIL_SEVERITY=<string>

Specifies the severity value returned when a check fails due to a SQL parse error. Valid values are the following return codes:

  • 0 is INFO
  • 1 is MINOR
  • 2 is MAJOR
  • 3 is CRITICAL
  • 4 is BLOCKER

Default: severity of the executed check

Optional

LIQUIBASE_COMMAND_USERNAME=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_USERNAME=<string>

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

LIQUIBASE_COMMAND_VERBOSE=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_VERBOSE=<true|false>

Specifies the detail level of the command's output. Default: false.

 Optional 
Liquibase Version: 4.28.0
Liquibase Pro 4.28.0 by Liquibase licensed to Liquibase_QA until Tue Dec 02 01:59:59 UYT 2025
Executing Policy Checks against changelog.xml

WARNING: Additional checks have been added to 'liquibase.checks-settings.conf' and are disabled. To auto-enable new checks on upgrades, set '--auto-enable-new-checks=true'. Learn more at https://docs.liquibase.com/policy-checks
Executing all changelog checks because a valid license key was found!

WARNING: No database checks were run. Make sure the checks-scope property includes "database" to run database checks. In the CLI set --checks-scope="changelog,database" or set an environment variable LIQUIBASE_COMMAND_CHECKS_SCOPE=database. Learn more at https://docs.liquibase.com/policy-checks

INFO: No database specified. Checks executed against H2 generated SQL, which may not contain certain objects.
Checks-settings File:      liquibase.checks-settings.conf
=====================================================================================
CHANGELOG CHECKS
----------------
Checks completed validation of the changelog and found the following issues:

Check Name:         Table must have a comment (TableCommentCheck)
Changeset ID:       1
Changeset Filepath: changelog.xml
Check Severity:     MINOR (Return code: 1)
Message:            Table 'person' found without comment. Liquibase recommends tables have a comment to prevent siloed knowledge and to
                    ensure table's purpose is easily understood by others. (Note: This is not a check for a Liquibase
                    changelog comment.)

Check Name:         Require Changeset ID is valid UUID (RequireChangesetIDisUUID)
Changeset ID:       1
Changeset Filepath: changelog.xml
Check Severity:     MINOR (Return code: 1)
Message:            The changeset ID "1" does not follow the required 8-4-4-4-12 pattern UUID or GUID pattern. Please review and update the
                    changeset ID.

Check Name:         Table must have a comment (TableCommentCheck)
Changeset ID:       2
Changeset Filepath: changelog.xml
Check Severity:     MINOR (Return code: 1)
Message:            Table 'company' found without comment. Liquibase recommends tables have a comment to prevent siloed knowledge and to
                    ensure table's purpose is easily understood by others. (Note: This is not a check for a Liquibase
                    changelog comment.)

Check Name:         Require Changeset ID is valid UUID (RequireChangesetIDisUUID)
Changeset ID:       2
Changeset Filepath: changelog.xml
Check Severity:     MINOR (Return code: 1)
Message:            The changeset ID "2" does not follow the required 8-4-4-4-12 pattern UUID or GUID pattern. Please review and update the
                    changeset ID.

Check Name:         Require Changeset ID is valid UUID (RequireChangesetIDisUUID)
Changeset ID:       3
Changeset Filepath: changelog.xml
Check Severity:     MINOR (Return code: 1)
Message:            The changeset ID "3" does not follow the required 8-4-4-4-12 pattern UUID or GUID pattern. Please review and update the
                    changeset ID.

Changesets Validated: in changelog.xml
  ID: 1; Author: your.name
  ID: 2; Author: your.name
  ID: 3; Author: other.dev

Checks run against each changeset:
  Changesets Must Have a Comment Assigned (Short names: ChangesetCommentCheck)
  Changesets Must Have a Context Assigned (Short names: ChangesetContextCheck)
  Changesets Must Have a Label Assigned (Short names: ChangesetLabelCheck)
  Check Affected Rows Count on Delete (Short names: MaxAffectedRowsAllowedDelete)
  Check Affected Rows Count on Insert (Short names: MaxAffectedRowsAllowedInsert)
  Check Affected Rows Count on Update (Short names: MaxAffectedRowsAllowedUpdate)
  Check Changeset runInTransaction value (Short names: CheckRunInTransactionValue)
  Check Table Column Count (Short names: TableColumnLimit)
  One Change Per Changeset (Short names: OneChangePerChangeset)
  Require Changeset ID is valid UUID (Short names: RequireChangesetIDisUUID)
  Require primary key when creating table (Short names: PrimaryKeyOnCreateTable)
  Rollback Required for Changeset (Short names: RollbackRequired)
  Table must have a comment (Short names: TableCommentCheck)
  Warn on Detection of 'SELECT *' (Short names: SqlSelectStarWarn)
  Warn on Detection of 'USE DATABASE' statements (Short names: WarnOnUseDatabase)
  Warn on Use of User Defined ChangeTypes (Short names: DetectChangeType)
  Warn when 'DROP COLUMN' detected (Short names: ChangeDropColumnWarn)
  Warn when 'DROP TABLE' detected (Short names: ChangeDropTableWarn)
  Warn when 'MODIFY <column>' detected (Short names: ModifyDataTypeWarn)

Changelog Checks Skipped Due to unsupported changeset type for this check:
  Warn on Detection of 'GRANT' Statements (Short names: SqlGrantWarn) skipped for:
    1:your.name,
    2:your.name,
    3:other.dev
  Warn on Detection of 'REVOKE' Statements (Short names: SqlRevokeWarn) skipped for:
    1:your.name,
    2:your.name,
    3:other.dev
  Warn on Detection of grant that contains 'WITH ADMIN OPTION' (Short names: SqlGrantAdminWarn) skipped for:
    1:your.name,
    2:your.name,
    3:other.dev
  Warn on Detection of grant that contains 'WITH GRANT OPTION' (Short names: SqlGrantOptionWarn) skipped for:
    1:your.name,
    2:your.name,
    3:other.dev
  Warn when 'TRUNCATE TABLE' detected (Short names: ChangeTruncateTableWarn) skipped for:
    1:your.name,
    2:your.name,
    3:other.dev

INFO: Customize this output with the 'checks-output' property. See list of options with 'liquibase checks run --help' or https://docs.liquibase.com/policy-checks
INFO: The return code of all SQL Parser failures can be customized by setting the --sql-parser-fail-severity/LIQUIBASE_COMMAND_CHECKS_RUN_SQL_PARSER_FAIL_SEVERITY property, including setting it to '0' to prevent job interruptions. Learn more at https://docs.liquibase.com/policy-checks
ERROR: Exception Details
ERROR: Exception Primary Class:  CommandFailedException
ERROR: Exception Primary Reason:  Checks run command exited with error code of 1
ERROR: Exception Primary Source:  4.28.0
Checks run command exited with error code of 1

Related links