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 for your changelog to be present in other Maven artifacts (on the classpath) and to be used to invoke Liquibase on a database.

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 master 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 will be used in preference over those defined in the properties file. If you don't want the properties specified in the <configuration> to override your properties file, you can 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. Since several configurations may be inside the project, you can filter the liquibase.properties using the Maven resource filtering system.

So, the main advantages of this setup are:

  • No Liquibase plugin configuration in your projects. Only the liquibase.properties file is required.
  • A unique place where you can update the plugin version as you don't need to manual edit all your 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 may want to add an <executions> section or put more configuration properties in the <configuration> section. Any modification will be applied to all child projects. In most cases, you can override this global configuration in your local liquibase.properties file by setting <propertyFileWillOverride> to true. If you have a few exceptions among your projects but want to keep a global configuration for all the others, you can add the <plugin> section to your child pom.xml. This will override the global configurations.

When using Liquibase and Maven, put your liquibase.properties and changelog files in the src/main/resources folder. The liquibase.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 have the liquibase.properties placeholders filtered, 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 don't need the filtering capabilities, you can replace the following in the super-POM plugin configuration:

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

In this case, you can only run: mvn liquibase:update.

Related links