diff command

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

Running the diff command

Running the diff command requires two URLs:

  • referenceURL – the source for the comparison. The referenceURL attribute represents your source (reference) database which is the starting point and the basis for the database you want to compare.

  • url – the target of the comparison. The URL attribute stands for your target database which you want to compare to the source (reference) database. You typically perform actions and run the commands against this database

To compare two databases:

  • The first option is to run the diff command and pass the parameters needed for your source (reference) database and target database. You can do this by running the following:
  • liquibase diff
    --url="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
    --username=<USERNAME>
    --password=<PASSWORD>
    --referenceUrl="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
    --referenceUsername=<USERNAME>
    --referencePassword=<PASSWORD>

    See the snapshot command documentation for an example of using a snapshot file as one of the databases being used in the command.

    Tip: It is best practice to put your driver .jar file in the LIQUIBASE_HOME/lib directory. If you put the driver file in any other directory, specify the path to it in the liquibase.properties file: classpath:../path_to_drivers/ojdbc<version>.jar. For more information, see Creating and configuring a liquibase.properties file.
    When running diff against two different databases, both drivers should be in the LIQUIBASE_HOME/lib directory. Otherwise, the classpath property should reference both .jar files. Use the path separator that is correct for your operating system (a semicolon on Windows, a colon on Mac or Linux).

    Example: classpath: ojdbc7.jar:postgresql-42.2.8.jar

    Note: The username and password attributes are not required for connections and systems which use alternate means of authentication.

  • Alternatively, you can configure the liquibase.properties file to include your connection information for both databases. Run the following command:
  • liquibase diff

    Note: For information on how to configure your liquibase.properties file, see the Creating and configuring a liquibase.properties file topic.

The diff 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 diffChangeLog command to generate a changelog that will apply the changes to the target database.

Liquibase Community diff categories:

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

Liquibase Pro diff categories:

  • Check Constraint
  • Package
  • Package Body
  • Function
  • Trigger
  • Synonyms

Note: Liquibase does not currently check datatype length.

Filtering diff types

Liquibase allows you to use diffType 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 diffTypes are specified, all objects are considered.

Example: liquibase --diffTypes=tables,indexes,views diff

Related Links