diff-changelog

The diff-changelog command displays the differences between two databases you are comparing. It also generates a changelog file containing deployable changesets to resolve most of these differences.

Uses

The diff-changelog command is typically used when you want to create a deployable changelog to synchronize multiple databases. The diff-changelog command also provides more information about:

  • Missing objects in your database
  • Changes made to your database
  • Unexpected items in your database

Running the diff-changelog command

Running the diff-changelog  command requires two URLs:

  • 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 create a diff changelog:

  • Option 1: Run the diff-changelog command with all necessary attributes in the CLI:
  • liquibase diff-changelog --changelog-file=example-changelog.xml 
    --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>

    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-changelog --changelog-file=example-changelog.xml 

    Note: If you specify a changelog file name that already exists, Liquibase will append your changes to the existing file.

    For information, see Create and Configure a liquibase.properties File.

Output

The diff-changelog command produces a list of all objects and creates a changelog with a list of changesets.

Liquibase Open Source diff-changelog categories:

  • Catalog
  • Column
  • Foreign Key
  • Index
  • Primary Key
  • Schema
  • Sequence
  • Unique Constraints
  • View

Filtering diff-changelog types

You can filter what objects diff-changelog generates with the --diff-types attribute:

--diff-types=<catalogs,tables,functions,views,columns,indexes,foreignkeys,primarykeys,uniqueconstraints,storedprocedures,triggers,sequences,databasepackage,databasepackagebody>

You can also filter specific objects by name with the --include-objects and --exclude-objects attributes. For example:

--include-objects=table:tableName,column:columnName,view:viewName,index:indexName
--exclude-objects=table:tableName,column:columnName,view:viewName,index:indexName

This way, you can prevent any undesired objects from ending up in the resulting changelog.

Additional Functionality with Liquibase Pro

While Liquibase Open Source stores all changesets in a changelog, Liquibase Pro creates a directory called Objects and places the directory at the same level as your changelog. The Objects directory contains a subdirectory for each of the following stored logic types:

  • checkconstraint
  • package
  • packagebody
  • procedure
  • function
  • trigger
  • synonyms

Note: Not all database platforms support all stored logic types that are listed.

The diff-changelog command structures stored logic files into timestamped directories every time you run the command.

Note: Liquibase does not currently check data type length.

Command arguments

Attribute Definition Requirement
--changelog-file

The root changelog

Required
--reference-url

The JDBC reference database connection URL

Required
--url

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

Required
--author

Specifies the author for changesets in the generated changelog.

Optional
--context-filter

Specifies the context filter to generate and apply to all changesets in your changelog. Useful to set many contexts quickly. Similar to the set-contexts command. Available in Liquibase 4.24.0 and later.

Contexts are tags you can add to changesets to control which changesets will be executed in any particular migration run.

After generating changesets with contexts, to deploy specific changes according to these contexts, you must run a command that specifies a context filter. For example, update --context-filter=<xyz>.

Optional
--default-catalog-name

Name of the default catalog to use for the database connection

Optional
--default-schema-name

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

Specifies the types of objects to compare. Specify multiple values as a comma-separated list (without spaces). Valid values are: catalogs, checkconstraints, columns, data, databasepackage, databasepackagebody, foreignkeys, functions, indexes, primarykeys, sequences, storedprocedures, triggers, uniqueconstraints, views.

If null, default types are columns, foreignkeys, indexes, primarykeys, tables, uniqueconstraints, views.

Note: The diff types checkconstraints, databasepackage, databasepackagebody, functions, storedprocedures, and triggers require a valid Liquibase Pro license key to use.

Optional
--drift-severity

Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. If both --drift-severity and one of the individual error type arguments are set, the individual error type arguments take priority. Default: INFO.

Optional
--drift-severity-changed

Specifies the severity level of changed content in the drift report. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Overrides the value of --drift-severity for changed content only. Default: INFO.

Optional
--drift-severity-missing

Specifies the severity level of missing content in the drift report. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Overrides the value of --drift-severity for missing content only. Default: INFO.

Optional
--drift-severity-unexpected

Specifies the severity level of unexpected content in the drift report. Valid values are INFO (0), MINOR (1), MAJOR (2), CRITICAL (3), and BLOCKER (4), from least severe to most severe. Overrides the value of --drift-severity for unexpected content only. Default: INFO.

Optional
--driver

The JDBC driver class

Optional
--driver-properties-file

The JDBC driver properties file

Optional
--exclude-objects

Objects to exclude from diff

Optional
--include-catalog

If true, the catalog will be included in generated changesets. Default: false

Optional
--include-objects

Objects to include in diff

Optional
--include-schema

If true, the schema will be included in generated changesets. Default: false

Optional
--include-tablespace

Include the tablespace attribute in the changelog. Default: false

Optional
--label-filter

Specifies the label filter to generate and apply to all changesets in your changelog. Useful to set many labels quickly. Similar to the set-labels command. Available in Liquibase 4.24.0 and later.

Labels are tags you can add to changesets to control which changeset will be executed in any migration run.

After generating changesets with labels, to deploy specific changes according to these labels, you must run a command that specifies a label filter. For example, update --label-filter=<xyz>.

Optional
--open-report

If true, automatically opens the report in your default browser. Default: false.

Optional
--output-schemas

Lets you replace the schemas in the output changelog. This is a CSV list. The parameter size must match --schemas. If you have three items names in --schemas, you must also have three items in --output-schemas.

Example: liquibase generate-changelog --schemas=a,b,c --output-schemas=d,e,f

Optional
--password

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
--reference-default-catalog-name

The reference default catalog name to use for the database connection

Optional
--reference-default-schema-name

The reference default schema name to use for the database connection

Optional
--reference-driver

The JDBC driver class for the reference database

Optional
--reference-driver-properties-file

The JDBC driver properties file for the reference database

Optional
--reference-liquibase-catalog-name

Reference database catalog to use for Liquibase objects. Liquibase 4.24.0+.

Optional
--reference-liquibase-schema-name

Reference database schema to use for Liquibase objects. Liquibase 4.24.0+.

Optional
--reference-password

The reference database password.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional
--reference-schemas

Schemas names on reference database to use in diff. This is a CSV list.

Optional
--reference-username

The reference database username.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional
--replace-if-exists-types

Specify Change Types you want to target. Liquibase sets replaceIfExists="true" on these Change Types: createFunction, createPackage, createPackageBody, createProcedure, createTrigger, and createView. Liquibase 4.26.0+. Default: <none>.

Optional
--report-enabled

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

Optional
--report-name

Specifies the name of the report file at the command level. Overrides the global argument --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

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Optional
--run-on-change-types

Specify Change Types you want to target. Liquibase sets runOnChange="true" on changesets containing solely these Change Types: createFunction, createPackage, createPackageBody, createProcedure, createTrigger, and createView. Liquibase 4.26.0+. Default: <none>.

Optional
--schemas

Schemas to include in diff

Optional
--username

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.1 and later, you can automatically generate a Drift Report using the diff-changelog command. The drift report requires a Liquibase Pro license key.