Using Liquibase and your Maven POM File

It is recommended to use Apache Maven 3.1 or later to make it easier to configure the log-level of Liquibase Maven plugin with MAVEN_OPTs or by passing the following command: -Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG. You can also edit the properties in the ${maven.home}/conf/logging/simplelogger.properties file.

Paths to files

As of version 1.6.1.0 of the Maven plugin, all files are resolved from the Maven test classpath for the Maven project or an absolute path. This allows your changelog to be present in other Maven artifacts (on the classpath) and to be used to invoke Liquibase on a database.

Setup

To get Liquibase working in a Maven pom.xml file, place the following tags with your information in the <plugin> section of your pom.xml file:

• <groupId>
• <artifactId>
• <version>

To specify other project dependencies, including database drivers, add a <dependency> section. Including the database driver dependency ensures Liquibase has the appropriate driver available to communicate with your database. Since Maven allows multiple dependencies, specify the <dependencies> tag and put each of your configurations inside them – even if you only have one dependency:

<dependencies>
        <dependency>
        …
        </depdendency>
</dependencies>

Moreover, the Liquibase Maven integration let you specify the Liquibase extension in the <dependency> section of your POM file by adding the org.liquibase.ext dependency for the Liquibase plugin. Make sure that the Liquibase plugin and the extension have the same version.

<plugin>
     <!--start with basic information to get Liquibase plugin:
     include <groupId>, <artifactID>, and <version> elements-->
     <groupId>org.liquibase</groupId>
     <artifactId>liquibase-maven-plugin</artifactId>
     <version>4.30.0</version>
     <configuration>
        <!--set values for Liquibase properties and settings
        for example, the location of a properties file to use-->
        <propertyFile>liquibase.properties</propertyFile>
     </configuration>
     <dependencies>
         <!--set up any dependencies for Liquibase to function in your
         environment for example, a database-specific plugin-->
         <dependency>
             <groupId>org.liquibase.ext</groupId>
             <artifactId>liquibase-<dbname></artifactId>
             <version>4.30.0</version>
        </dependency>
     </dependencies>
</plugin>

If you download the dependency extension JAR file from GitHub, reference that file locally:

<dependency>
    <groupId>com.sample</groupId>
    <artifactId>sample</artifactId>
    <version>1.0</version>
    <scope>system</scope>
    <systemPath>/path/to/liquibase-<dbname>.jar</systemPath>
</dependency>

Configuration property files

You can specify configuration settings for the Maven Liquibase plugin in standard Java Property files. If you specify a configuration property file, it will be used to set up the properties for the invocation of the Maven Liquibase plugin.

Each property defined in the file that matches a property in the goal you want to invoke will be set. If the property does not match any of the properties for the goal, then a warning message will be displayed, but execution will continue.

Note: The reason for only printing a warning message is to allow you to define a single main configuration property file that can be re-used for multiple Maven Liquibase goals like Maven update and Maven tag.

Using a configuration property file and specifying configuration values

It is possible to specify a configuration property file and individual properties in the <configuration> section of the Maven pom.xml file.

If this is done, the properties specified in the <configuration> section are granted preference over the properties defined in the properties file. To prevent the properties specified in the <configuration> from overriding the properties file, add the following to the <configuration> section:

<propertyFileWillOverride>true</propertyFileWillOverride>

Additional Maven Liquibase properties

To disable the pop-up dialog that confirms migrations on non-local databases, add the following code snippet to your pom.xml file:

<promptOnNonLocalDatabase>false</promptOnNonLocalDatabase>

To get hints about all available configuration parameters within the Liquibase Maven plugin, use the following Maven command:

mvn help:describe -DgroupId=org.liquibase -DartifactId=liquibase-maven-plugin -Dversion=2.0.1 -Dfull=true

Maven multiple projects

Through the usage of a parent-POM (super-POM), it is possible to have a centralized Liquibase plugin configuration that applies to all your Maven child projects.

The adaptation to each project needs (database driver, jdbc, url, and others) is made through a local Liquibase properties file. Because the project might contain several configurations, you can use the Maven resource filtering system to filter the properties file.

The main advantages of this setup include the following:

• No Liquibase plugin configuration in your projects. Only a Liquibase properties file is required.
• A unique place where you can update the plugin version, as you do not need to manually edit the pom.xml files and commit them.

Note: For a detailed explanation of the super-POM, see Introduction to the POM.

Parent pom.xml example:

<project>  
   <build>
      <plugins>
        <plugin>
          <groupId>org.liquibase</groupId>
          <artifactId>liquibase-maven-plugin</artifactId>
          <version>4.2.2</version>
          <configuration>
            <propertyFileWillOverride>true</propertyFileWillOverride>
            <propertyFile>target/classes/liquibase.properties</propertyFile>
          </configuration>
        </plugin>
      </plugins>
    </build>
 </project>

Note: Replace 4.2.2 by the most recent version of the plugin.

As shown in the example, you might want to add an <executions> section or add configuration properties to the <configuration> section. Modifications are applied to all child projects. In most cases, you can override the global configuration in your local Liquibase properties file by setting <propertyFileWillOverride> to true. To specify exceptions among your projects, add the <plugin> section to the child pom.xml. This step overrides the global configurations.

When using Liquibase and Maven, place the Liquibase properties file and changelog files in the src/main/resources folder. The properties file can include as many properties as you need:

contexts: ${liquibase.contexts}
changeLogFile: com/company/client/project/changelog.xml
driver: ${dataSource.project.driverClass}
url: ${dataSource.project.jdbcURL}   
verbose: true
dropFirst: false

The placeholders are filtered by the Maven resource filtering system and are replaced by values found in filter property files located in src/main/filters. The project jdbc url and database driver are used for Liquibase as well.

Note: You can have as many property file filters as you need. To specify the filter to use on Maven execution, you need to use Maven profiles.

To get your Maven standard resources/ folder filtered, you need to have this configuration in your pom.xml:

<build>
   <resources>
     <resource>
       <directory>src/main/resources</directory>
       <filtering>true</filtering>
     </resource>
   </resources>
</build>

Note: For more information, see How do I filter resource files.

To filter the placeholders for the Liquibase properties file, invoke the resources:

mvn resources:resources liquibase:update -P<profile_name>

Note: The -P option refers Maven to the profile to use and thus to the set of values (from the filter properties file) to use for filtering.

If you do not require filtering capabilities, replace the following in the super-POM plugin configuration:

<propertyFile>target/classes/liquibase.properties</propertyFile> by <propertyFile>src/main/resources/liquibase.properties</propertyFile>

where liquibase.properties represents the name of the Liquibase properties file. In this example, you can run only mvn liquibase:update.

Excluding Liquibase JARs from your POM

Liquibase comes with two JAR files in liquibase/internal/lib serving as primary libraries, liquibase-core and liquibase-commercial. If you don't want to use the liquibase-commercial JAR in your project, you can exclude it with the <exclusions> tag in your Maven POM file:

<dependency>
  <groupId>org.liquibase</groupId>
  <artifactId>liquibase-core</artifactId>
  <version>4.30.0</version>
  <exclusions>
    <exclusion>
      <groupId>org.liquibase</groupId>
      <artifactId>liquibase-commercial</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Installing proprietary JARs in your local repository

If you want to use Liquibase with a JAR that is not hosted on a public Maven repository, such as a JDBC JAR for a proprietary database, you must install the JAR in your local repository. From your command line, enter the following Maven command to install the JAR:

mvn install:install-file -Dfile=<path-to-jar-file> -DgroupId=<group-id> -DartifactId=<artifact-id> -Dversion=<version> -Dpackaging=<packaging>

Then add this dependency to your pom.xml file. For more information, see Apache: Guide to installing 3rd party JARs.

Related links

• Maven Properties