diff
JSON
Note: This is a Liquibase Pro feature, so you need a Liquibase Pro License Key to use it.
Starting with Liquibase 3.9.0, you can automate drift detection at scale in your database schemas with the Liquibase Pro machine-readable JSON diff output. The diff --format=json
command is a Liquibase Pro extension to the Liquibase Open Source diff command.
Uses
The diff
command in a JSON format is typically used to detect drift between a model schema and a database's actual schema. You can use the output of the diff
command in a JSON format as an input to automation processes. For example, the results in a JSON diff
can be parsed in your build system to trigger alerts, generate reports, or run the diff-changelog command.
After you run the command, a JSON-structured object lists the differences between the databases, as well as the values that are configured in your Liquibase properties or Maven POM file, or are passed as command-line arguments under the --url
and --reference-url
keys.
In Liquibase Pro 4.25.0 and later, you can use diff
to seamlessly generate a Drift Report for your databases.
Syntax
Running the diff
- reference-url – the source for the comparison. The
--reference-url
attribute represents your source (reference) database, which is the basis for the database you want to compare. - url – the target of the comparison. The
--url
attribute represents your target database, which you want to compare to the source (reference) database. You typically perform actions and run commands on this database.
To compare two databases or schemas:
- Option 1: Run the
diff
command with all necessary attributes in the CLI:
liquibase diff --format=json
--url="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
--username=<USERNAME>
--password=<PASSWORD>
--reference-url="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
--reference-username=<USERNAME>
--reference-password=<PASSWORD>
Note: To run this command with an offline database snapshot, use the following pattern for the reference URL: --reference-url="offline:mysql?snapshot=SNAPSHOT_DEV.json"
.
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.
See the snapshot command topic for an example of using a snapshot file as one of the databases being used in the command.
Tip: Liquibase recommends that you place your database's JDBC driver JAR file in the liquibase/lib
directory. If you place the driver file in a different directory, specify the path in the properties file: classpath:../<path-to-drivers>/ojdbc<version>.jar
. For more information, see Create and Configure a liquibase.properties File. When you run the diff
command against two databases, either the drivers for both must be in the liquibase/lib
directory or the classpath
property must reference both JAR files. Use the appropriate path separator for your operating system: for Windows, use a semicolon; for Mac or Linux, use a colon.
Example: classpath: ojdbc7.jar:postgresql-42.2.8.jar
- Option 2: Configure the Liquibase properties file to include the connection information for both databases. Then, run the following command in the CLI:
liquibase diff --format=json
For information, see Create and Configure a liquibase.properties File.
By default, the result is sent to STDOUT
, which provides flexibility to use the result in other tools or in a processing pipeline. You can also have your output in a file using the --output-file=<filename>
attribute.
liquibase diff --format=json --output-file=myfile.json
The diff
JSON command produces a list of categories along with one of the following descriptions:
- Missing: there are objects on your source database (referenceURL) that are not on your target database (URL).
- Unexpected: there are objects on your target database (URL) that are not on your source database (referenceURL).
- Changed: the object as it exists on the source database (referenceURL) is different than as it exists in the target database (URL).
Note: The changed description will not specify the type of change applied to your database. Run the diff-changelog command to generate a changelog that will apply the changes to the target database.
Liquibase Pro diff
JSON categories:
- Check Constraint
- Package
- Package Body
- Function
- Trigger
- Synonyms
Also, Liquibase Pro includes Liquibase Open Source diff
categories when running --format=json
:
- Catalog
- Column
- Foreign Key
- Index
- Primary Key
- Schema
- Sequence
- Procedure
- Unique Constraints
- View
Note: Liquibase does not currently check datatype
length.
Filtering diff
types
Liquibase allows you to use the diff-types
attribute to filter the types of objects you want to compare. Multiple filters can be added to the attribute as a comma-separated list. If no diff-types
are specified, all objects are considered.
Example: liquibase diff --format=json --diffTypes=tables,indexes,views
Command parameters
Attribute | Definition | Requirement |
---|---|---|
|
The JDBC reference database connection URL |
Required |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required |
|
Name of the default catalog to use for the database connection |
Optional |
|
Name of the default schema to use for the database connection. If Tip: In Liquibase v4.23.0+, camelCase for Note: The syntax |
Optional |
|
Specifies the types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: If null, default types are Note: The diff types |
Optional |
|
Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are |
Optional |
|
Specifies the severity level of changed content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of missing content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of unexpected content in the drift report. Valid values are |
Optional |
|
The JDBC driver class |
Optional |
|
The JDBC driver properties file |
Optional |
|
Objects to exclude from diff |
Optional |
|
Option to create JSON output. See diff JSON. |
Optional |
|
Objects to include in diff |
Optional |
|
If Note: Prior to Liquibase 4.29.0, this parameter was called |
Optional |
|
Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match Example: |
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. |
Optional |
|
The reference default catalog name to use for the database connection |
Optional |
|
The reference default schema name to use for the database connection |
Optional |
|
The JDBC driver class for the reference database |
Optional |
|
The JDBC driver properties file for the reference database |
Optional |
|
Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
Reference database schema to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
The reference database password. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Schemas names on reference database to use in diff. This is a CSV list. |
Optional |
|
The reference database username. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
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 |
|
Schemas to include in diff |
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 |
Attribute | Definition | Requirement |
---|---|---|
|
The JDBC reference database connection URL |
Required |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required |
|
Name of the default catalog to use for the database connection |
Optional |
|
Name of the default schema to use for the database connection. If Tip: In Liquibase v4.23.0+, camelCase for Note: The syntax |
Optional |
|
Specifies the types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: If null, default types are Note: The diff types |
Optional |
|
Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are |
Optional |
|
Specifies the severity level of changed content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of missing content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of unexpected content in the drift report. Valid values are |
Optional |
|
The JDBC driver class |
Optional |
|
The JDBC driver properties file |
Optional |
|
Objects to exclude from diff |
Optional |
|
Option to create JSON output. See diff JSON. |
Optional |
|
Objects to include in diff |
Optional |
|
If Note: Prior to Liquibase 4.29.0, this parameter was called |
Optional |
|
Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match Example: |
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. |
Optional |
|
The reference default catalog name to use for the database connection |
Optional |
|
The reference default schema name to use for the database connection |
Optional |
|
The JDBC driver class for the reference database |
Optional |
|
The JDBC driver properties file for the reference database |
Optional |
|
Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
Reference database schema to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
The reference database password. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Schemas names on reference database to use in diff. This is a CSV list. |
Optional |
|
The reference database username. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
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 |
|
Schemas to include in diff |
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 |
Attribute | Definition | Requirement |
---|---|---|
|
The JDBC reference database connection URL |
Required |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required |
|
Name of the default catalog to use for the database connection |
Optional |
|
Name of the default schema to use for the database connection. If Tip: In Liquibase v4.23.0+, camelCase for Note: The syntax |
Optional |
|
Specifies the types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: If null, default types are Note: The diff types |
Optional |
|
Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are |
Optional |
|
Specifies the severity level of changed content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of missing content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of unexpected content in the drift report. Valid values are |
Optional |
|
The JDBC driver class |
Optional |
|
The JDBC driver properties file |
Optional |
|
Objects to exclude from diff |
Optional |
|
Option to create JSON output. See diff JSON. |
Optional |
|
Objects to include in diff |
Optional |
|
If Note: Prior to Liquibase 4.29.0, this parameter was called |
Optional |
|
Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match Example: |
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. |
Optional |
|
The reference default catalog name to use for the database connection |
Optional |
|
The reference default schema name to use for the database connection |
Optional |
|
The JDBC driver class for the reference database |
Optional |
|
The JDBC driver properties file for the reference database |
Optional |
|
Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
Reference database schema to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
The reference database password. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Schemas names on reference database to use in diff. This is a CSV list. |
Optional |
|
The reference database username. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
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 |
|
Schemas to include in diff |
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 |
Attribute | Definition | Requirement |
---|---|---|
|
The JDBC reference database connection URL |
Required |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required |
|
Name of the default catalog to use for the database connection |
Optional |
|
Name of the default schema to use for the database connection. If Tip: In Liquibase v4.23.0+, camelCase for Note: The syntax |
Optional |
|
Specifies the types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: If null, default types are Note: The diff types |
Optional |
|
Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are |
Optional |
|
Specifies the severity level of changed content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of missing content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of unexpected content in the drift report. Valid values are |
Optional |
|
The JDBC driver class |
Optional |
|
The JDBC driver properties file |
Optional |
|
Objects to exclude from diff |
Optional |
|
Option to create JSON output. See diff JSON. |
Optional |
|
Objects to include in diff |
Optional |
|
If Note: Prior to Liquibase 4.29.0, this parameter was called |
Optional |
|
Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match Example: |
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. |
Optional |
|
The reference default catalog name to use for the database connection |
Optional |
|
The reference default schema name to use for the database connection |
Optional |
|
The JDBC driver class for the reference database |
Optional |
|
The JDBC driver properties file for the reference database |
Optional |
|
Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
Reference database schema to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
The reference database password. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Schemas names on reference database to use in diff. This is a CSV list. |
Optional |
|
The reference database username. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
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 |
|
Schemas to include in diff |
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 |
Attribute | Definition | Requirement |
---|---|---|
|
The JDBC reference database connection URL |
Required |
|
The JDBC database connection URL. See Using JDBC URL in Liquibase. |
Required |
|
Name of the default catalog to use for the database connection |
Optional |
|
Name of the default schema to use for the database connection. If Tip: In Liquibase v4.23.0+, camelCase for Note: The syntax |
Optional |
|
Specifies the types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: If null, default types are Note: The diff types |
Optional |
|
Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are |
Optional |
|
Specifies the severity level of changed content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of missing content in the drift report. Valid values are |
Optional |
|
Specifies the severity level of unexpected content in the drift report. Valid values are |
Optional |
|
The JDBC driver class |
Optional |
|
The JDBC driver properties file |
Optional |
|
Objects to exclude from diff |
Optional |
|
Option to create JSON output. See diff JSON. |
Optional |
|
Objects to include in diff |
Optional |
|
If Note: Prior to Liquibase 4.29.0, this parameter was called |
Optional |
|
Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match Example: |
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. |
Optional |
|
The reference default catalog name to use for the database connection |
Optional |
|
The reference default schema name to use for the database connection |
Optional |
|
The JDBC driver class for the reference database |
Optional |
|
The JDBC driver properties file for the reference database |
Optional |
|
Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
Reference database schema to use for Liquibase objects. Liquibase 4.24.0+. |
Optional |
|
The reference database password. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
Optional |
|
Schemas names on reference database to use in diff. This is a CSV list. |
Optional |
|
The reference database username. Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro. |
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 |
|
Schemas to include in diff |
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 |
Note: The username
and password
attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url
attribute.
Drift report
In Liquibase 4.25.0 and later, you can automatically generate a Drift Report using the diff
command. The drift report requires a Liquibase Pro license key.
diff
JSON example output
Starting Liquibase at 13:54:07 (version 4.4.0 #11 built at 2021-06-09 16:36+0000)
Liquibase Version: 4.4.0
Liquibase Pro 4.4.0 by DaticalDB licensed to support until Wed Sep 22 23:59:59 CDT 2021
{
"diff": {
"diffFormat": 1,
"created": "Mon Jul 19 13:54:08 CDT 2021",
"databases": {
"reference": {
"majorVersion": "13",
"minorVersion": "2 (Debian 13",
"name": "PostgreSQL",
"url": "jdbc:postgresql://example.net:5432/dev"
},
"target": {
"majorVersion": "13",
"minorVersion": "2 (Debian 13",
"name": "PostgreSQL",
"url": "jdbc:postgresql://example.net:5432/test"
}
},
"missingObjects": [
{
"missingObject": {
"name": "contract_bank_accounts",
"type": "table",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "firstname",
"type": "column",
"relationName": "contract_bank_accounts",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "pay_by_quarter",
"type": "column",
"relationName": "sal_emp",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "schedule",
"type": "column",
"relationName": "sal_emp",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "lastnames",
"type": "column",
"relationName": "contract_bank_accounts",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "id",
"type": "column",
"relationName": "contract_bank_accounts",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "name",
"type": "column",
"relationName": "sal_emp",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "contract_bank_accounts_pkey",
"type": "primaryKey",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "sal_emp",
"type": "table",
"schemaName": "public",
"catalogName": "dev"
}
},
{
"missingObject": {
"name": "contract_bank_accounts_pkey",
"type": "index",
"schemaName": "public",
"catalogName": "dev"
}
}]
,
"unexpectedObjects": [
{
"unexpectedObject": {
"name": "id",
"type": "column",
"relationName": "actor",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "firstname",
"type": "column",
"relationName": "actor",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "contacts",
"type": "table",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "bcolor",
"type": "column",
"relationName": "colors",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "bcolor",
"type": "column",
"relationName": "colors1",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "id",
"type": "column",
"relationName": "contacts",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "lastname",
"type": "column",
"relationName": "contacts",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "colors_pkey1",
"type": "index",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "twitter",
"type": "column",
"relationName": "actor",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "colors",
"type": "table",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "actor_pkey",
"type": "index",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "id",
"type": "column",
"relationName": "colors",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "colors1",
"type": "table",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "actor",
"type": "table",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "contacts_pkey",
"type": "primaryKey",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "firstname",
"type": "column",
"relationName": "contacts",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "colors_pkey",
"type": "index",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "lastname",
"type": "column",
"relationName": "actor",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "actor_pkey",
"type": "primaryKey",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "colors_pkey",
"type": "primaryKey",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "fcolor",
"type": "column",
"relationName": "colors",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "colors_pkey1",
"type": "primaryKey",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "contacts_pkey",
"type": "index",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "id",
"type": "column",
"relationName": "colors1",
"schemaName": "public",
"catalogName": "test"
}
},
{
"unexpectedObject": {
"name": "fcolor",
"type": "column",
"relationName": "colors1",
"schemaName": "public",
"catalogName": "test"
}
}]
,
"changedObjects": [
{
"changedObject": {
"name": "test",
"type": "catalog",
"differences": [
{
"difference": {
"comparedValue": "test",
"field": "name",
"message": "name changed from 'dev' to 'test'",
"referenceValue": "dev"
}
}]
}
}]
}
}
Liquibase command 'diff' was executed successfully.