checks run

Note: This is a Liquibase Pro feature, so you need a Liquibase Pro License Key to use it.

The checks run command 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 Liquibase Pro 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 Liquibase Pro 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 Liquibase Pro Custom Policy Checks.

Optional

--checks-settings-file=<string>

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

Note: In the properties file and JAVA_OPTS only: in 4.18.0 and earlier, specify this parameter using the syntax defaultSchemaName. In 4.19.0 and later, use the syntax liquibase.command.defaultSchemaName.

Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set --preserve-schema-case to true. However, in Liquibase 4.12.0–4.22.0, the Liquibase validator still throws a DatabaseException error if you specify a mixed-case value of defaultSchemaName. In 4.23.0 and later, the Liquibase validator accepts any casing.

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 parameter --reports-enabled. Default: true.

Optional

--report-name=<string>

Specifies the name of the report file at the command level. Overrides the global parameter --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 parameter --reports-path. Default: ./.

Optional

--report-suppress-exception=<true|false>

Liquibase 4.31.0+. Specifies whether to hide exceptions (which may contain SQL) from the operation report at the command level. Overrides the global parameter --reports-suppress-exception. Default: false. However:

  • If --report-suppress-exception is not set and --report-suppress-sql=true, Liquibase suppresses all SQL, including exception SQL.
  • If --report-suppress-exception=false and --report-suppress-sql=true, Liquibase suppresses most SQL but shows exception SQL.
Optional

--report-suppress-sql=<true|false>

Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the command level. Overridden by the global parameter --reports-suppress-sql. Default: false.

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

Related links