Maven diff

diff allows you to compare two databases of the same type, or different types, to one another.

Uses

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

Maven configuration

You can configure Liquibase Maven in multiple ways. You can pass arguments like <changeLogFile> in Maven directly in your pom.xml file, in a liquibase.properties file referenced in your POM, as environment variables, or as JVM system properties.

Tip: For more information about the Maven configuration, see Configuring Maven.

Running the diff Maven goal

Running the diff goal requires two URLs:

  • referenceURL – the source for the comparison. The referenceURL attribute represents your source 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 database. You typically perform actions and run the commands against this database.

To compare two databases, choose one of the following options:

  • The first option is to specify all attributes for the diff goal in your pom.xml file under the <configuration></configuration> section:
<changeLogFile>specify your changelog file</changeLogFile>
<driver>specify the name of the driver class to use to connect to the target  database</driver>
<url>specify your JDBC connection for the target database</url>
<username>specify your username for the target database</username>
<password>specify your password for the target database</password>
<referenceDriver>specify the name of the driver class to use to connect to the reference database</referenceDriver>
<referenceUrl>specify your JDBC connection for the source database</referenceUrl>
<referenceUsername> specify your username for the source database </referenceUsername>
<referencePassword> specify your password for the source database </referencePassword>
<goal>diff</goal>
  • The second option is to run the diff command and pass the attributes needed for your source database and target database. You can do this by running the following:
mvn liquibase:diff
-Dliquibase.changeLogFile=myChangeLog.xml
-Dliquibase.driver=oracle.jdbc.OracleDriver
-Dliquibase.url="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
-Dliquibase.username=<USERNAME>
-Dliquibase.password=<PASSWORD>
-Dliquibase.referenceUrl="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
-Dliquibase.referenceUsername=<USERNAME>
-Dliquibase.referencePassword=<PASSWORD>
  • The third option is to configure the Liquibase properties file to include your user authentication information for both databases. After you include the necessary information in the properties file, add <propertyFile>properties-file-name</propertyFile> to your pom.xml file under the plugin <configuration></configuration> section, where properties-file-name represents the name of the Liquibase properties file, like liquibase.properties. Next, run the following command:
mvn liquibase:diff -Dliquibase.outputFile=mydiff.txt

Note: Running the diff goal requires a Maven project to be implemented. The --outputFile=mydiff.txt attribute will save the output to a file. If you do not specify this, you will see the output in your command line.

To generate a changelog that applies changes after the comparison of databases to the target database, run the diff goal with the diffChangeLogFile attribute, as follows:

mvn liquibase:diff -Dliquibase.diffChangeLogFile=mydiff.xml

Note: Enter the name and the extension format you want to use in place of mydiff.xml. Alternatively, you can add <diffChangeLogFile>specify the changelog file name here</diffChangeLogFile> to your pom.xml file.

Note: Liquibase does not currently check datatype length.

Filtering diff types

Liquibase allows you to use diffTypes 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: mvn liquibase:diff -Dliquibase.diffTypes=tables,indexes,views

diff optional Maven configuration attributes

Attribute Definition
liquibase.changeLogDirectory

Specifies the path to the directory where Liquibase can find your changelog file.

liquibase.changeLogFile

The changelog file for Liquibase to use.

liquibase.changelogCatalogName

Specifies the catalog Liquibase will use to create your changelog tables.

liquibase.changelogSchemaName

Specifies the schema Liquibase will use to create your changelog tables.

liquibase.clearCheckSums

Boolean. Forces checksums to be cleared from the DATABASECHANGELOG table. Default value is: false.

liquibase.contexts

Specifies which contexts Liquibase will execute, which can be separated by a comma if multiple contexts are required. If a context is not specified, then all contexts will be executed.

liquibase.databaseChangeLogLockTableName

Specifies the table name to use for the DATABASECHANGELOGLOCK table.

liquibase.databaseChangeLogTableName

Specifies the table name to use for the DATABASECHANGELOG table.

liquibase.databaseClass

Specifies the database object class.

liquibase.defaultCatalogName

Specifies the default catalog name to use for the database connection.

liquibase.defaultSchemaName

Specifies the default schema name to use for the database connection.

liquibase.diffChangeLogFile Defines whether the created changelog needs to fix differences between the two databases. If the file exists, changes are appended to that file. If this is null, a comparison report is sent to STDOUT.
liquibase.diffExcludeObjects

Specifies objects to be excluded from the changelog. Example filters: "table_name", "table:main_.*", "column:*._lock, table:primary.*".

liquibase.diffIncludeCatalog Boolean. Includes the catalog in the diff output. If this is null, then the catalog will not be included.
liquibase.diffIncludeObjects

Specifies objects to be included in the changelog. Example filters: "table_name", "table:main_.*", "column:*._lock, table:primary.*".

liquibase.diffIncludeSchema Boolean. Includes the schema in the diff output. If this is null, then the schema will not be included.
liquibase.diffIncludeTablespace Boolean. Includes the tablespace in the diff output. If this is null, then the tablespace will not be included.
liquibase.diffTypes

Specifies the list of diff types to include in the changelog expressed as a comma-separated list from:

  • tables
  • views
  • columns
  • indexes
  • foreignkeys
  • primarykeys
  • uniqueconstraints
  • data

If this is null, then the default types will be:

  • tables
  • views
  • columns
  • indexes
  • foreignkeys
  • primarykeys
  • uniqueconstraints
liquibase.driver

Specifies the driver class name to use for the database connection.

driverPropertiesFile

Specifies the location of a JDBC connection properties file which contains properties the driver will use.

liquibase.emptyPassword

Deprecated. Boolean. Use an empty or null value for the password instead. Default value is: false.

expressionVariables

Specifies a map-based collection of changelog properties to apply.

expressionVars

Specifies a property-based collection of changelog properties to apply.

liquibase.format Specifies the format in which to display the diff output. This format can be TXT or JSON.
liquibase.includeArtifact

Boolean. Includes a Maven project artifact in the class loader, which obtains the Liquibase properties file and changelog files. Default value is true.

liquibase.includeTestOutputDirectory

Boolean. Includes the Maven test output directory in the class loader which obtains the Liquibase properties file and changelog files. Default value is true.

liquibase.labels

Specifies which labels Liquibase runs, and which can be separated by a comma if multiple labels are required or you need to designate a more complex expression. If no label is specified, then all labels are run.

liquibase.licenseKey

Specifies your Liquibase Pro license key.

liquibase.outputDefaultCatalog

Boolean. Specifies whether to ignore the catalog or database name. Default value is: false.

liquibase.outputDefaultSchema

Boolean. Specifies whether to ignore the schema name. Default value is: false.

liquibase.outputFile Writes the diff output to a file.
liquibase.outputFileEncoding

Indicates that you want to set the character encoding of the output file during the updateSQL phase.

liquibase.outputSchemas Outputs schema names. This is a CSV list.
liquibase.password

Specifies the database password for the database connection.

liquibase.promptOnNonLocalDatabase

Deprecated. Boolean. Controls whether users are prompted before executing changesets to a non-local database. Default value is: true.

liquibase.propertyFile

Specifies the Liquibase properties file to use for configuration, like liquibase.properties.

liquibase.propertyFileWillOverride

Boolean. Indicates that you want the liquibase.properties file to override any settings provided in the Maven plugin configuration. By default, if a property is explicitly specified, it is not overridden if it also appears in the properties file. Default value is: false.

liquibase.propertyProviderClass

Specifies the property provider, which must be a java.util.Properties implementation.

liquibase.referenceDefaultCatalogName Specifies the reference database catalog.
liquibase.referenceDriver Specifies the fully qualified name of the driver class to use to connect to the reference database. If this is not specified, then the driver will be used instead.
liquibase.referencePassword Specifies the reference database password to use to connect to the specified database. If this is null, then an empty password will be used.
liquibase.referenceSchemas Specifies schemas names on a reference database to use in diff. This is a CSV list.
liquibase.referenceServer Specifies the server id in settings.xml to use when authenticating.
liquibase.referenceUrl Specifies the reference database URL to connect to for executing Liquibase.
liquibase.referenceUsername Specifies the reference database username to use to connect to the specified database.
liquibase.schemas Specifies schemas on a target database to use in diff. This is a CSV list.
liquibase.server

Specifies the server ID in the Maven settings.xml to use when authenticating.

liquibase.skip

Boolean. Specifies whether to skip running Liquibase. The use of this attribute is not recommended but can be used when needed. Default value is: false.

systemProperties

Specifies a list of system properties you want to pass to the database.

liquibase.url

Specifies the database URL you want to use to execute Liquibase.

liquibase.username

Specifies the database username for the database connection.

liquibase.verbose

Boolean. Controls the amount of output detail when you call the plugin. Default value is: false.