Getting Started with Liquibase and Maven

Apache Maven is a software project management and comprehension tool, which is based on the concept of a project object model (POM). The Liquibase Maven integration lets you manage the build process and your database schema scripts from a central file called pom.xml.

To use Liquibase and Maven:

  1. Create a Liquibase Maven project directory to store all Liquibase files.

    2. Tip: Maven includes the Standard Directory Layout. Having a common directory layout with the pom.xml file, text files, the src subfolder, and the target subfolder allows you to use the Maven project easier. For more details about the Maven project structure, see Maven Getting Started Guide or Introduction to the Standard Directory Layout.

  2. In your Liquibase Maven project directory, create a pom.xml file. Alternatively, use your existing pom.xml file.
  3. Add the following section to the pom.xml file: 
    4. <plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <version>4.30.0</version>
</plugin>

    The pom.xml file presents an option to store attribute instead of passing them at runtime as Liquibase Maven goals require database connection information. For more information, see Maven Properties and Using Liquibase and your Maven POM File.

    Tip: Use the Liquibase properties file to include only Liquibase attributes in your pom.xml file. The properties file must reside in the src/main/resources directory or another location in the search path. Additionally, the Liquibase properties must be specified in the configuration section of the pom.xml file, as follows: <propertyFile>liquibase.properties</propertyFile>. For more information, see Create and Configure a liquibase.properties File.

  4. Create a text file called changelog.sql in the src/main/resources directory. Liquibase also supports the .xml, .yaml, or .json changelog formats.
  5. Add changesets to your changelog file. Use the following examples depending on the format of the changelog you created: 
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
        http://www.liquibase.org/xml/ns/pro
        http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">
    <changeSet id="1" author="Liquibase">
    <createTable tableName="test_table">
           <column name="test_id" type="int">
                 <constraints primaryKey="true"/>
           </column>
           <column name="test_column" type="varchar"/>
    </createTable>
    </changeSet>
</databaseChangeLog>
--liquibase formatted sql

--changeset liquibase:1
CREATE TABLE test_table (test_id INT, test_column VARCHAR, PRIMARY KEY (test_id))
databaseChangeLog:
   - changeSet:
       id: 1
       author: Liquibase
       changes:
       - createTable:
           columns:
           - column:
               name: test_column
               type: INT
               constraints:  
                   primaryKey:  true  
                   nullable:  false  
                   tableName: test_table
{ 
  "databaseChangeLog": [
  {
	"changeSet": {
	  "id": "1",
      "author": "Liquibase",
	  "changes": [
	    {
		  "createTable": {
		    "columns": [
			{
			  "column": 
		      {
				"name": "test_column",
				"type": "INT",
				"constraints": 
			  {
				"primaryKey": true,
				"nullable": false
				}
				}
			  }]
			,
			"tableName": "test_table"
		  }
		}]
	  }
	}]
  }
  1. Specify your changelog file along with the database URL, username, and password in the pom.xml file to run Maven goals:
    2. <plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <version>4.30.0</version>
    <configuration>
        <changeLogFile>changelog.sql</changeLogFile>
        <url>YourJDBCConnection</url>
        <username>dbuser</username>
        <password>dbpassword</password>
    </configuration>
</plugin>
  2. Run the update-sql goal to inspect the SQL before applying changes to your database: 
    3. mvn liquibase:updateSQL
  3. Deploy your changes by using the update goal: 
    4. mvn liquibase:update

After your first update, you will see a new table along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table added to the database.

Upgrading from Liquibase Open Source to Liquibase Pro

If you currently use Liquibase Open Source and want to upgrade to Liquibase Pro, follow these steps:

  1. In your pom.xml file, ensure that you are using the latest Liquibase plugin for Maven:
    2. <plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <version>4.30.0</version>
</plugin>
  2. Ensure that you remove the any exclusion of the liquibase-commercial JAR you may have had in place:
    3. <!-- To ensure that Pro functionality is on the classpath, you can remove this entire dependency. -->
<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
    <version>4.30.0</version>
    <exclusions>
        <!-- Alternatively, you can remove this exclusion. -->
        <exclusion>
            <groupId>org.liquibase</groupId>
            <artifactId>liquibase-commercial</artifactId>
        </exclusion>
    </exclusions>
</dependency>
  3. Apply your Liquibase Pro license key. For more information, see How to Apply Your Liquibase Pro License Key.

Related links