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

Liquibase Maven can be configured in multiple ways. One way is to define your Liquibase configuration properties in your pom.xml file. To configure your pom.xml file, refer to Configuring Liquibase Attributes in your Maven POM File.

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 needed information in your liquibase.properties file, add <propertyFile>liquibase.properties file name</propertyFile> to your pom.xml file under the plugin <configuration></configuration> section. Next, you can run the following:
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.

If you want to generate a changelog that will apply changes after the comparison of databases to the target database, run the diff goal with the diffChangeLogFile attribute:

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 directory where Liquibase can find your changelog file.
liquibase.changeLogFile Specifies 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 [boolean] Deprecated. 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 will execute, which can be separated by a comma if multiple labels are required or you need to designate a more complex expression. If a label is not specified, then all labels will be executed.
liquibase.liquibaseProLicenseKey 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 [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 you want to use to configure Liquibase.
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.