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.

Command arguments

The following table identifies parameters that are accepted or required by the run subcommand. If the Default column states "Required," it is required to run the command successfully. If it states "Null," it is an optional command argument. Each command argument helps you narrow down the liquibase checks run command to ensure that only very specific content is affected by the command.

Tip: For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Name Default Syntax Description
--auto-update (Enumeration) Null

CLI: --auto-update=[on|off]

Property: liquibase.command.checks.run.autoUpdate: [on|off]

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_AUTO_UPDATE=[ON|OFF]

Allows automatic backup and updating of the liquibase.checks-settings.conf file when new quality checks are available.

Default: off

--cache-changelog-file-contents (Boolean) true

CLI: --cache-changelog-file-contents=[true|false]

Property: liquibase.command.checks.run.cacheChangelogFileContents: [true|false]

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CACHE_CHANGELOG_FILE_CONTENTS=[TRUE|FALSE]

 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.
--changelog-file (String) Null

CLI: --changelog-file

Property: liquibase.command.checks.run.changelogFile

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHANGELOG_FILE

The changelog file against which you execute checks when running liquibase checks run.
--changeset-filter (String) ALL

CLI: --changeset-filter

Property: liquibase.command.checks.run.changesetFilter

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHANGESET_FILTER

Specifies whether quality checks run on ALL changesets or only PENDING (undeployed) changesets. Only applies to checks with the "changelog" scope. Liquibase 4.26.0+. Default: ALL.
--check-name (String) Null

CLI: --check-name

Property: liquibase.command.checks.run.checkName

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHECK_NAME

Use this to specify the short name of the check you want to target with one of the following subcommands:

  • bulk-set
  • copy
  • customize
  • delete
  • disable
  • enable
  • reset
  • run
  • show
--check-rollbacks (Boolean) false

CLI: --check-rollbacks=[true|false]

Property: liquibase.command.checks.run.checkRollbacks: [true|false]

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHECK_ROLLBACKS=[TRUE|FALSE]

 Allow changeset's rollback code to be analyzed for compliance with currently enabled quality checks.
--checks-output (Enumeration) all

CLI: --checks-output=<quoted comma-separated list of options>

Property: liquibase.command.checks.run.checksOutput: <comma-separated list of options>

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_OUTPUT=<quoted comma-separated list of options>

 

Examples:

liquibase checks run --checks-output="issues4, checksrun"

export LIQUIBASE_CHECKS_CHECKS_OUTPUT="issues,skippedchecks"; liquibase checks run

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

Options:

  • all show everything/all sections (DEFAULT)
  • 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..."

Default: all
--checks-scope (String) Null

CLI: --checks-scope

Property: liquibase.command.checks.run.checksScope

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCOPE

 The Liquibase component to run checks against, which can be a comma separated list

Dual-scoped: Can run against changelogs and databases separately or simultaneously.
--checks-settings-file (String) Null

CLI: --checks-settings-file

Property: liquibase.command.checks.run.checksSettingsFile

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SETTINGS_FILE

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.
--format (Enumeration) text

CLI: --format=[text|json]

Property: liquibase.command.checks.run.format: [text|json]

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_FORMAT=[TEXT|JSON]

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.
--labels (String) Null

CLI: --labels

Property: liquibase.command.checks.run.labels

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_LABELS

 Changeset labels to match
--package-file (String) Null CLI: liquibase checks run --packages-file=securuity-checks.pkg

Property: liquibase.command.checks.package.file

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_PACKAGE_FILE

 The file name of the yaml file to be created. defaults to liquibase.checks-package.yaml if not set.. For more information see Quality Checks Packages
--package-name (String) Null CLI: liquibase checks run --packages-name=security-checks.pkg

Property: liquibase.command.checks.package.name

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_PACKAGE_NAME

The name of the checks-package object inside the file to be created. For more information see Quality Checks Packages
--package-contents (String) Null CLI: liquibase checks run --packages-contents=security-checks.pkg

Property: liquibase.command.checks.package.contents

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_PACKAGE_CONTENTS

The file, files, or dir of files to be included in the checks-package object. For more information see Quality Checks Packages

--property-substitution-enabled (Boolean)

Alias:

--property-sub

true CLI: liquibase checks run --property-substitution-enabled=true|false

Property: liquibase.command.checks.property.substitution

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_PROPERTY_SUBSTITUTION

 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.
--schemas (String) Null

CLI: --schemas

Property: liquibase.command.checks.run.schemas

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_SCHEMAS

 The schemas to check when checks-scope contains database
--sql-parser-fail-severity (Enumeration) severity of the check

CLI: --sql-parser-fail-severity=[0|1|2|3|4]

Property: liquibase.command.checks.run.sqlParserFailSeverity: [0|1|2|3|4]

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_SQL_PARSER_FAIL_SEVERITY=[0|1|2|3|4]

Allows specification of the severity value returned when a check fails due to a SQL parse error.

Return Codes:
0 is INFO
1 is MINOR
2 is MAJOR
3 is CRITICAL
4 is BLOCKER

Default: severity of the check
If not set, the software will return the severity of the executed check.

--verbose (Boolean) false

CLI: --verbose=[true|false]

Property: liquibase.command.checks.run.verbose: [true|false]

Environment Variable: LIQUIBASE_COMMAND_CHECKS_RUN_VERBOSE=[TRUE|FALSE]

 Verbose flag with optional values of 'True' or 'False'. The default is 'False'.

Note: The --snapshot-format attribute is not supported by checks run.

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.

Related links