====== Maven LiquiBase Plugin ======

LiquiBase can be controlled via a Maven plug-in which can be obtained from the central Maven repository.

You can find the all the versions of the Liquibase-core and Maven plugins in the central repository by going [[http://www.mvnrepository.com/artifact/org.liquibase | here]].





===== Goals Available =====

^ Goal                                       ^ Description                          ^
| [[maven migrate|liquibase:migrate]]        | //**DEPRECATED** use update instead//    |
| [[maven migrateSQL|liquibase:migrateSQL]]  | //**DEPRECATED** use updateSQL instead// |
| [[maven update|liquibase:update]] | performs an update on the specified database to the current version specified in the [[DatabaseChangeLog]] |
| [[maven updateSQL|liquibase:updateSQL]] | generates SQL to update a database to the current version specified in the [[DatabaseChangeLog]] |
| [[maven tag|liquibase:tag]] | tags the current state of the database with the specified tag |
| [[maven rollback|liquibase:rollback]] | performs a rollback on the database to the specified tag, date, or number of [[ChangeSet]]s |






===== Configuration and Usage =====

Configuration of the plugin is done via the <plugins> section of the pom.xml, specifying the configuration and execution phase to bind the plugin to.

Each goal has its own configuration parameters, but some of which are common to other plugin goals, for more information on all the configuration parameters available for a specific goal click on the link to goal above.


=== 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 [[DatabaseChangeLog]]s to be present in other Maven artifacts (on the classpath) and able to be used to invoke liquibase on a database. 


=== Using Configuration Property Files ===
Configuration settings for the Maven Liquibase plugin can be specified in standard Java Property files. If a configuration property file is specified it will be used to setup the properties for the invocation of the Maven Liquibase plugin. 

For each property defined in the file that matches a property in the goal being invoked that property of the goal will be set. If the property does not match any of the properties for the goal, then a warning will be displayed to the user, but execution will continue.

The reason for only printing a warning is to allow a user to define a single master configuration property file that can be resused for multiple Maven Liquibase goals like [[maven update|liquibase:update]] and [[maven tag|liquibase:tag]].

== Using both 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 Liquibase plugin. 

If this is done the properties specified in the <configuration> section will be used in preference over those defined in the properties file. 

If this behaviour is not desirable, then the properties file can be setup to override the specified properties in the <configuration> section by adding the following to the <configuration> section; 
<code xml><propertyFileWillOverride>true</propertyFileWillOverride></code>

=== Example of Maven Liquibase Update ===

The following is a sample configuration for the Liquibase Maven plugin, version 1.6.1.0, showing an example of the [[maven update|liquibase:update]] goal;

<code xml>
  <project>
    [...]
    <build>
      <plugins>
        <plugin>
          <groupId>org.liquibase</groupId>
          <artifactId>liquibase-plugin</artifactId>
          <version>1.6.1.0</version>
          <executions>
            <execution>
              <phase>process-resources</phase>
              <configuration>
                <propertyFile>src/main/resources/liquibase.properties</propertyFile>
              </configuration>
              <goals>
                <goal>update</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
    [...]
  </project>
</code>

This example configuration will execute the [[maven update|liquibase:update]] goal as part of the process-resources phase of the build. The parameters (database url, password, etc...) for running Liquibase are specified in the src/main/resources/liquibase.properties. 

Note that the path to the file src/main/resources/liquibase.properties could be shortened to liquibase.properties if there was only on on the classpath.

All the parameters for executing the Maven Liquibase plugin can also be specified in <configuration> section of the plugin. Below is an example of this:

<code xml>
  [...]
    <plugin>
      <groupId>org.liquibase</groupId>
      <artifactId>liquibase-plugin</artifactId>
      <version>1.6.1.0</version>
      <executions>
        <execution>
          <phase>process-resources</phase>
          <configuration>
            <changeLogFile>src/main/resources/org/liquiabse/business_table.xml</changeLogFile>
            <driver>oracle.jdbc.OracleDriver</driver>
            <url>jdbc:oracle:thin:@tf-appserv-linux:1521:xe</url>
            <username>liquibaseTest</username>
            <password>pass</password>
          </configuration>
          <goals>
            <goal>update</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  [...]
</code>

=== Further configuration properties ===
Add <code xml><promptOnNonLocalDatabase>false</promptOnNonLocalDatabase></code> as configuration parameter to disable the dialog popping up which confirms migrations on non-local databases. 

The maven command <code>mvn help:describe -DgroupId=org.liquibase -DartifactId=liquibase-plugin -Dversion=1.7.0.0 -Dfull=true</code> will give you hints about all available configuration parameters within the Liquibase maven plugin.