dbcl-history

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

dbcl-history is a command that displays the DATABASECHANGELOGHISTORY table. By default, the command displays the table in STDOUT. It is available in Liquibase 4.27.0 and later. It is only available to Liquibase Pro users.

Uses

The DATABASECHANGELOGHISTORY (DBCLH) table contains all changes ever made to your database with Liquibase, including rollbacks and other changes not included in the DATABASECHANGELOG table (DBCL). You can see the DBCLH table in your database by running a SQL query:

SELECT * FROM DATABASECHANGELOGHISTORY;

However, you may also want Liquibase to display the DBCLH in your command line or an output file without running a SQL query. You may also want to display it in a machine-readable format. The dbcl-history command lets you do all these things. If you have Structured Logging enabled, Liquibase also sends the output of dbcl-history to structured logs. This lets you automatically feed your data into third-party logging tools.

Easily accessing the DBCLH table enables you to identify patterns in your deployments that later have to be rolled back. By understanding these patterns, you can avoid these problems and speed up your development cycle.

Syntax

To display the DBCLH table in STDOUT, run the dbcl-history command in your command line or in a flow file. For example, to generate human-readable JSON output:

liquibase dbcl-history --format=JSON_PRETTY --verbose
stages:
  Default:
    actions:
      - type: liquibase
        command: dbcl-history
        cmdArgs: {format: JSON_PRETTY, verbose}

You can use the --output-file global parameter to send command output to a file instead of the console:

liquibase --output-file=dbclh_2024-03-15.json dbcl-history --format=JSON_PRETTY --verbose

Parameters

Global parameters

Parameter Definition Requirement

--license-key=<string>

Your Liquibase Pro license key

Required

--dbclhistory-capture-extensions=<true|false>

If true, installed extensions are captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-extensions.

Optional

--dbclhistory-capture-sql=<true|false>

If true, SQL generated by commands is captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-sql.

Optional

--dbclhistory-enabled=<true|false>

Enables the DATABASECHANGELOGHISTORY table. This table includes records of rollbacks, dropAlls, and repeated runOnChange type activity, which is not available in the standard DATABASECHANGELOG table. Liquibase 4.27.0+. Default: false. See --dbclhistory-enabled.

Optional

--dbclhistory-severity=<string>

The exit code for Liquibase to return if an exception is encountered while recording events to the DATABASECHANGELOGHISTORY table. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Liquibase 4.27.0+. Default: 1. See --dbclhistory-severity.

Optional

--output-file=<string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Parameter Definition Requirement

--url=<string>

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

Required

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

Specifies the format of the output. Valid values are JSON and JSON_PRETTY. Specifying JSON formats the output as machine-readable JSON without indentation or line breaks. Specifying JSON_PRETTY adds whitespace to be human-readable. Default: JSON.

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.

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

globalArgs: { dbclhistory-capture-extensions: "<true|false>" }

If true, installed extensions are captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-extensions.

Optional

globalArgs: { dbclhistory-capture-sql: "<true|false>" }

If true, SQL generated by commands is captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-sql.

Optional

globalArgs: { dbclhistory-enabled: "<true|false>" }

Enables the DATABASECHANGELOGHISTORY table. This table includes records of rollbacks, dropAlls, and repeated runOnChange type activity, which is not available in the standard DATABASECHANGELOG table. Liquibase 4.27.0+. Default: false. See --dbclhistory-enabled.

Optional

globalArgs: { dbclhistory-severity: "<string>" }

The exit code for Liquibase to return if an exception is encountered while recording events to the DATABASECHANGELOGHISTORY table. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Liquibase 4.27.0+. Default: 1. See --dbclhistory-severity.

Optional

globalArgs: { output-file: "<string>" }

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Parameter Definition Requirement

cmdArgs: { url: "<string>" }

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

Required

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>" }

Specifies the format of the output. Valid values are JSON and JSON_PRETTY. Specifying JSON formats the output as machine-readable JSON without indentation or line breaks. Specifying JSON_PRETTY adds whitespace to be human-readable. Default: JSON.

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.

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

liquibase.dbclhistory.captureExtensions: <true|false>

If true, installed extensions are captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-extensions.

Optional

liquibase.dbclhistory.captureSql: <true|false>

If true, SQL generated by commands is captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-sql.

Optional

liquibase.dbclhistory.enabled: <true|false>

Enables the DATABASECHANGELOGHISTORY table. This table includes records of rollbacks, dropAlls, and repeated runOnChange type activity, which is not available in the standard DATABASECHANGELOG table. Liquibase 4.27.0+. Default: false. See --dbclhistory-enabled.

Optional

liquibase.dbclhistory.severity: <string>

The exit code for Liquibase to return if an exception is encountered while recording events to the DATABASECHANGELOGHISTORY table. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Liquibase 4.27.0+. Default: 1. See --dbclhistory-severity.

Optional

liquibase.outputFile: <string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Parameter Definition Requirement

liquibase.command.url: <string>

liquibase.command.dbclHistory.url: <string>

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

Required

liquibase.command.defaultCatalogName: <string>

liquibase.command.dbclHistory.defaultCatalogName: <string>

Name of the default catalog to use for the database connection

Optional

liquibase.command.defaultSchemaName: <string>

liquibase.command.dbclHistory.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.dbclHistory.driver: <string>

The JDBC driver class

Optional

liquibase.command.driverPropertiesFile: <string>

liquibase.command.dbclHistory.driverPropertiesFile: <string>

The JDBC driver properties file

Optional

liquibase.command.format: <string>

liquibase.command.dbclHistory.format: <string>

Specifies the format of the output. Valid values are JSON and JSON_PRETTY. Specifying JSON formats the output as machine-readable JSON without indentation or line breaks. Specifying JSON_PRETTY adds whitespace to be human-readable. Default: JSON.

Optional

liquibase.command.password: <string>

liquibase.command.dbclHistory.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.

Optional

liquibase.command.username: <string>

liquibase.command.dbclHistory.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.dbclHistory.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

JAVA_OPTS=-Dliquibase.dbclhistory.captureExtensions=<true|false>

If true, installed extensions are captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-extensions.

Optional

JAVA_OPTS=-Dliquibase.dbclhistory.captureSql=<true|false>

If true, SQL generated by commands is captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-sql.

Optional

JAVA_OPTS=-Dliquibase.dbclhistory.enabled=<true|false>

Enables the DATABASECHANGELOGHISTORY table. This table includes records of rollbacks, dropAlls, and repeated runOnChange type activity, which is not available in the standard DATABASECHANGELOG table. Liquibase 4.27.0+. Default: false. See --dbclhistory-enabled.

Optional

JAVA_OPTS=-Dliquibase.dbclhistory.severity=<string>

The exit code for Liquibase to return if an exception is encountered while recording events to the DATABASECHANGELOGHISTORY table. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Liquibase 4.27.0+. Default: 1. See --dbclhistory-severity.

Optional

JAVA_OPTS=-Dliquibase.outputFile=<string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Parameter Definition Requirement

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

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

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

Required

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

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

Name of the default catalog to use for the database connection

Optional

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

JAVA_OPTS=-Dliquibase.command.dbclHistory.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.dbclHistory.driver=<string>

The JDBC driver class

Optional

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

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

The JDBC driver properties file

Optional

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

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

Specifies the format of the output. Valid values are JSON and JSON_PRETTY. Specifying JSON formats the output as machine-readable JSON without indentation or line breaks. Specifying JSON_PRETTY adds whitespace to be human-readable. Default: JSON.

Optional

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

JAVA_OPTS=-Dliquibase.command.dbclHistory.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.

Optional

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

JAVA_OPTS=-Dliquibase.command.dbclHistory.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.dbclHistory.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

LIQUIBASE_DBCLHISTORY_CAPTURE_EXTENSIONS=<true|false>

If true, installed extensions are captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-extensions.

Optional

LIQUIBASE_DBCLHISTORY_CAPTURE_SQL=<true|false>

If true, SQL generated by commands is captured in the DATABASECHANGELOGHISTORY table. Liquibase 4.27.0+. Default: true. See --dbclhistory-capture-sql.

Optional

LIQUIBASE_DBCLHISTORY_ENABLED=<true|false>

Enables the DATABASECHANGELOGHISTORY table. This table includes records of rollbacks, dropAlls, and repeated runOnChange type activity, which is not available in the standard DATABASECHANGELOG table. Liquibase 4.27.0+. Default: false. See --dbclhistory-enabled.

Optional

LIQUIBASE_DBCLHISTORY_SEVERITY=<string>

The exit code for Liquibase to return if an exception is encountered while recording events to the DATABASECHANGELOGHISTORY table. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Liquibase 4.27.0+. Default: 1. See --dbclhistory-severity.

Optional

LIQUIBASE_OUTPUT_FILE=<string>

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command parameters

Parameter Definition Requirement

LIQUIBASE_COMMAND_URL=<string>

LIQUIBASE_COMMAND_DBCL_HISTORY_URL=<string>

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

Required

LIQUIBASE_COMMAND_DEFAULT_CATALOG_NAME=<string>

LIQUIBASE_COMMAND_DBCL_HISTORY_DEFAULT_CATALOG_NAME=<string>

Name of the default catalog to use for the database connection

Optional

LIQUIBASE_COMMAND_DEFAULT_SCHEMA_NAME=<string>

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

The JDBC driver class

Optional

LIQUIBASE_COMMAND_DRIVER_PROPERTIES_FILE=<string>

LIQUIBASE_COMMAND_DBCL_HISTORY_DRIVER_PROPERTIES_FILE=<string>

The JDBC driver properties file

Optional

LIQUIBASE_COMMAND_FORMAT=<string>

LIQUIBASE_COMMAND_DBCL_HISTORY_FORMAT=<string>

Specifies the format of the output. Valid values are JSON and JSON_PRETTY. Specifying JSON formats the output as machine-readable JSON without indentation or line breaks. Specifying JSON_PRETTY adds whitespace to be human-readable. Default: JSON.

Optional

LIQUIBASE_COMMAND_PASSWORD=<string>

LIQUIBASE_COMMAND_DBCL_HISTORY_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.

Optional

LIQUIBASE_COMMAND_USERNAME=<string>

LIQUIBASE_COMMAND_DBCL_HISTORY_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_DBCL_HISTORY_VERBOSE=<true|false>

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

Optional

Output