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.

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}
changelog-file: 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.

Related links