diff
Last updated: February 18, 2026
The diff command in Liquibase allows you to compare two databases of the same type, or different types, to one another.
Uses
The diff command is typically used at the completion of a project to verify all expected changes are in the changelog or to detect drift between a model schema and a database's actual schema. The diff command is also helpful for the following tasks:
Finding missing objects between one database and another
Seeing that a change was made to your database
Finding unexpected items in your database
In Liquibase Secure 4.25.0 and later, you can use diff to seamlessly generate a Drift Report for your databases.
Syntax
Running the diff command requires two URLs:
reference-url– the source for the comparison. The
--reference-urlattribute represents your source (reference) database, which is the basis for the database you want to compare.url– the target of the comparison. The
--urlattribute 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:
Option 1
Run the diff command with all necessary attributes in the CLI:
liquibase diff
--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".
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.
Liquibase recommends that you place your database's JDBC driver JAR file in the $LIQUIBASE_HOME/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. When you run the diff command against two databases, either the drivers for both must be in the $LIQUIBASE_HOME/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.
$LIQUIBASE_HOME is an environment variable that points to the location of the directory where Liquibase is installed on your machine. You can set environment variables using your operating system's shell. The location of $LIQUIBASE_HOME will depend on where Liquibase was installed on your machine.
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
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 --output-file=myfile.json diff
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.
Example output
The diff command produces a list of diff types, 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 Open Source diff types:
Catalog
Column
Foreign Key
Index
Primary Key
Schema
Sequence
Unique Constraints
View
Liquibase Secure diff types:
Check Constraint
Package
Package Body
Procedure
Function
Trigger
Synonyms
Note: Liquibase does not currently check datatype length.
Filtering diff types
Liquibase allows you to use 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 --diff-types=tables,indexes,views
Example of a filtered output
Command parameters
Attribute | Definition | Requirement |
| The JDBC reference database connection URL | Required |
| The JDBC database connection URL. | 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 Note: In the properties file and Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set | 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 Liquibase Secure 5.1.0+. Snowflake accepted values are: Note: For Snowflake, unique constraints are not snapshotted as standalone objects. Instead, uniqueness is captured as the | 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 |
| Controls behavior when snapshots reference objects from schemas not included in the snapshot (like cross-schema triggers or foreign keys)
Default: | 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. | 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. | Optional |
| Schemas names on reference database to use in diff. This is a CSV list. | Optional |
| The reference database username. | Optional |
| Enables a report at the command level. Overrides the global parameter | Optional |
| Specifies the name of the report file at the command level. Overrides the global parameter | Optional |
| Specifies the file path to the report file at the command level. Overrides the global parameter | Optional |
| 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 If If | Optional |
| Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the command level. Overridden by the global parameter | Optional |
| Schemas to include in diff. | Optional |
| Username to connect to the target database. | Optional |
Attribute | Definition | Requirement |
| The JDBC reference database connection URL | Required |
| The JDBC database connection URL. | 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 Note: In the properties file and Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set | 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 Liquibase Secure 5.1.0+. Snowflake accepted values are: Note: For Snowflake, unique constraints are not snapshotted as standalone objects. Instead, uniqueness is captured as the 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 |
| Controls behavior when snapshots reference objects from schemas not included in the snapshot (like cross-schema triggers or foreign keys)
Default: | 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. | 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. | Optional |
| Schemas names on reference database to use in diff. This is a CSV list. | Optional |
| The reference database username. | Optional |
| Enables a report at the command level. Overrides the global parameter | Optional |
| Specifies the name of the report file at the command level. Overrides the global parameter | Optional |
| Specifies the file path to the report file at the command level. Overrides the global parameter | Optional |
| 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 |
| Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the command level. Overridden by the global parameter | Optional |
| Schemas to include in diff. | Optional |
| Username to connect to the target database. | Optional |
Attribute | Definition | Requirement |
| The JDBC reference database connection URL | Required |
| The JDBC database connection URL. | 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 Note: In the properties file and Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set | 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 Liquibase Secure 5.1.0+. Snowflake accepted values are: Note: For Snowflake, unique constraints are not snapshotted as standalone objects. Instead, uniqueness is captured as the | 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 |
| Controls behavior when snapshots reference objects from schemas not included in the snapshot (like cross-schema triggers or foreign keys)
Default: | 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. | 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. | Optional |
| Schemas names on reference database to use in diff. This is a CSV list. | Optional |
| The reference database username. | Optional |
| Enables a report at the command level. Overrides the global parameter | Optional |
| Specifies the name of the report file at the command level. Overrides the global parameter | Optional |
| Specifies the file path to the report file at the command level. Overrides the global parameter | Optional |
| 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 |
| Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the command level. Overridden by the global parameter | Optional |
| Schemas to include in diff | Optional |
| Username to connect to the target database. | Optional |
Attribute | Definition | Requirement |
| The JDBC reference database connection URL | Required |
| The JDBC database connection URL. | 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 Note: In the properties file and Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set | 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 Liquibase Secure 5.1.0+. Snowflake accepted values are: Note: For Snowflake, unique constraints are not snapshotted as standalone objects. Instead, uniqueness is captured as the 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 |
Unix
| Controls behavior when snapshots reference objects from schemas not included in the snapshot (like cross-schema triggers or foreign keys)
Default: | 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. | 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. | Optional |
| Schemas names on reference database to use in diff. This is a CSV list. | Optional |
| The reference database username. | Optional |
| Enables a report at the command level. Overrides the global parameter | Optional |
| Specifies the name of the report file at the command level. Overrides the global parameter | Optional |
| Specifies the file path to the report file at the command level. Overrides the global parameter | Optional |
| 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 |
| Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the command level. Overridden by the global parameter | Optional |
| Schemas to include in diff | Optional |
Unix:
Windows:
| Liquibase Secure 5.1+
This is a JVM system property that controls how the Oracle JDBC driver handles fetch sizes when querying tables containing LONG or LONG RAW columns. It is available in Liquibase 5.1.0 and later. The default value is You might want to set this property to | Optional |
| Username to connect to the target database. | Optional |
Attribute | Definition | Requirement |
| The JDBC reference database connection URL | Required |
| The JDBC database connection URL. | 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 Note: In the properties file and Note: In Liquibase 4.12.0 and later, you can use mixed-case schema names if you set | 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 Liquibase Secure 5.1.0+. Snowflake accepted values are: Note: For Snowflake, unique constraints are not snapshotted as standalone objects. Instead, uniqueness is captured as the | 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 |
| Controls behavior when snapshots reference objects from schemas not included in the snapshot (like cross-schema triggers or foreign keys)
Default: | 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. | 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. | Optional |
| Schemas names on reference database to use in diff. This is a CSV list. | Optional |
| The reference database username. | Optional |
| Enables a report at the command level. Overrides the global parameter | Optional |
| Specifies the name of the report file at the command level. Overrides the global parameter | Optional |
| Specifies the file path to the report file at the command level. Overrides the global parameter | Optional |
| 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 |
| Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the command level. Overridden by the global parameter | Optional |
| Schemas to include in diff | Optional |
| Username to connect to the target database. | Optional |
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 Secure license key.
Drift reports are available for MongoDB with the MongoDB Secure extension starting in version 4.32.