Running Database Migrations for Java Apps

Last updated 29 March 2017

Most database-backed applications will need to change their database schema during the course of their lifetime. These changes are often controlled by a process called migrations or evolutions.

In this article, you’ll learn how to use two tools, Liquibase and Flyway, to run database migrations for a Java application on Heroku.

Using Liquibase

There are many ways to run Liquibase. It provides a Maven plugin, a standalone command-line tool, a Hibernate plugin, and a Spring Bean. The Maven plugin is the least preferable of these because it requires the Maven runtime and .m2 cache to be available at execution. But on Heroku, these are excluded from the slug file by default to reduce its size and improve startup time.

In this article, we’ll discuss the best mechanism for use on Heroku.

Running Liquibase automatically with Spring

Liquibase provides a very convenient SpringLiquibase bean that automatically runs your migrations on startup if they are in the correct location.

If you are using Spring Boot, you only need to include the liquibase-core dependency and put your change log in src/resources/db/changelog/db.changelog-master.yaml, as demonstrated in this Spring and Liquibase sample application.

Upon startup, you will see something like this in your logs:

2015-10-20T02:00:51.937179+00:00 app[web.1]: 2015-10-20 02:00:51.936  INFO 3 --- [main] liquibase : Successfully acquired change log lock
2015-10-20T02:00:55.419669+00:00 app[web.1]: 2015-10-20 02:00:55.419  INFO 3 --- [main] liquibase : Reading from public.databasechangelog
2015-10-20T02:00:55.571104+00:00 app[web.1]: 2015-10-20 02:00:55.555  INFO 3 --- [main] liquibase : Successfully released change log lock

However, running migrations at startup does add to your app’s boot time and may cause you to exceed the boot-timeout limit imposed by Heroku. If this the case, you may find that running the migrations in the Heroku release phase is preferable.

Running Liquibase in release phase

The Liquibase migrations can be run in Heroku release phase using the Liquibase command-line tool. To use this tool, you’ll need to include the Liquibase JAR file in your slug. You can do this with Maven by adding the following plugin configuration to your pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>2.4</version>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>package</phase>
      <goals><goal>copy</goal></goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>org.liquibase</groupId>
            <artifactId>liquibase-core</artifactId>
            <version>3.4.1</version>
            <destFileName>liquibase.jar</destFileName>
          </artifactItem>
          <artifactItem>
            <groupId>org.yaml</groupId>
            <artifactId>snakeyaml</artifactId>
            <version>1.13</version>
            <outputDirectory>${project.build.directory}/dependency/lib</outputDirectory>
          </artifactItem>
          <artifactItem>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>9.4-1204-jdbc41</version>
            <destFileName>postgres.jar</destFileName>
          </artifactItem>
        </artifactItems>
      </configuration>
    </execution>
  </executions>
</plugin>

This will copy the JAR file to target/dependency/liquibase.jar during the Maven package goal. With this in place, you can add a process entry to your Procfile that will run the migrations in the release phase of deployment:

release: java -jar target/dependency/liquibase.jar --changeLogFile=src/main/resources/db/changelog/db.changelog-master.yaml --url=$JDBC_DATABASE_URL --classpath=target/dependency/postgres.jar update

However, be aware that the existing version of your app will need to run with the migrations until the new version of the app has been deployed. Thus, this method only works if the migrations are additive.

Using Flyway

Flyway provides several mechanisms for running migrations including a command-line tool, Maven plugin, Gradle plugin and an SBT plugin. The Maven, Gradle and SBT plugins are the least preferable of these because they require the build tool’s runtime and .m2 cache to be available at execution. But on Heroku, these are excluded from the slug file by default to reduce its size and improve startup time.

In this article, we’ll discuss the best mechanism for use on Heroku.

Running Flyway automatically with Spring

You can run Flyway automatically by including the flyway-core dependency in your app and putting your migration scripts in src/main/resources/db/migration/, as demonstrated in this Spring and Flyway sample application.

However, running migrations at startup does add to your app’s boot time and may cause you to exceed the boot-timeout limit imposed by Heroku. If this the case, you may find that running the migrations with the Java API is preferable.

Running Flyway with the Java API

To use the Flyway Java API, create a simple class with a main method, such as this:

package sample.flyway;

import org.flywaydb.core.Flyway;

public class Migrations {
    public static void main(String[] args) throws Exception {
        Flyway flyway = new Flyway();
        flyway.setDataSource(System.getenv("JDBC_DATABASE_URL"),
                             System.getenv("JDBC_DATABASE_USERNAME"),
                             System.getenv("JDBC_DATABASE_PASSWORD"));
        flyway.migrate();
    }
}

Then copy the flyway JAR file into your slug file by adding this plugin configuration to your pom.xml file:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>2.4</version>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>package</phase>
      <goals><goal>copy</goal></goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>org.flywaydb</groupId>
            <artifactId>flyway-core</artifactId>
            <version>3.2.1</version>
            <destFileName>flyway.jar</destFileName>
          </artifactItem>
          <artifactItem>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>9.4-1204-jdbc41</version>
            <destFileName>postgres.jar</destFileName>
          </artifactItem>
        </artifactItems>
      </configuration>
    </execution>
  </executions>
</plugin>

This will copy the JAR file to target/dependency/flyway.jar during the Maven package goal. With this in place, you can add a process entry to your Procfile that will run the migrations:

release: java -cp target/spring-boot-sample-flyway-1.0.0.jar:target/dependency/* sample.flyway.Migrations

This will run the migrations during the Heroku release phase. You can also run the migrations manually with this command:

$ heroku run release

Further Reading

For more information, see the official documentation pages for each of these open source projects:

And you can read more about Connecting to Relational Databases on Heroku with Java in the Dev Center.

Feedback

Log in to submit feedback.