Fork me on GitHub

Dropwizard Migrations

The dropwizard-migrations module provides you with a wrapper for Liquibase database refactoring.


Like Dropwizard JDBI, your configuration class needs a DataSourceFactory instance:

public class ExampleConfiguration extends Configuration {
    private DataSourceFactory database = new DataSourceFactory();

    public DataSourceFactory getDataSourceFactory() {
        return database;

Adding The Bundle

Then, in your application’s initialize method, add a new MigrationsBundle subclass:

public void initialize(Bootstrap<ExampleConfiguration> bootstrap) {
    bootstrap.addBundle(new MigrationsBundle<ExampleConfiguration>() {
        public DataSourceFactory getDataSourceFactory(ExampleConfiguration configuration) {
            return configuration.getDataSourceFactory();

Defining Migrations

Your database migrations are stored in your Dropwizard project, in src/main/resources/migrations.xml. This file will be packaged with your application, allowing you to run migrations using your application’s command-line interface.

For example, to create a new people table, you might create an initial migrations.xml like this:

<?xml version="1.0" encoding="UTF-8"?>


    <changeSet id="1" author="codahale">
        <createTable tableName="people">
            <column name="id" type="bigint" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            <column name="fullName" type="varchar(255)">
                <constraints nullable="false"/>
            <column name="jobTitle" type="varchar(255)"/>

For more information on available database refactorings, check the Liquibase documentation.

Checking Your Database’s State

To check the state of your database, use the db status command:

java -jar hello-world.jar db status helloworld.yml

Dumping Your Schema

If your database already has an existing schema and you’d like to pre-seed your migrations.xml document, you can run the db dump command:

java -jar hello-world.jar db dump helloworld.yml

This will output a Liquibase change log with a changeset capable of recreating your database.

Tagging Your Schema

To tag your schema at a particular point in time (e.g., to make rolling back easier), use the db tag command:

java -jar hello-world.jar db tag helloworld.yml 2012-10-08-pre-user-move

Migrating Your Schema

To apply pending changesets to your database schema, run the db migrate command:

java -jar hello-world.jar db migrate helloworld.yml


This will potentially make irreversible changes to your database. Always check the pending DDL scripts by using the --dry-run flag first. This will output the SQL to be run to stdout.


To apply only a specific number of pending changesets, use the --count flag.

Rolling Back Your Schema

To roll back changesets which have already been applied, run the db rollback command. You will need to specify either a tag, a date, or a number of changesets to roll back to:

java -jar hello-world.jar db rollback helloworld.yml --tag 2012-10-08-pre-user-move


This will potentially make irreversible changes to your database. Always check the pending DDL scripts by using the --dry-run flag first. This will output the SQL to be run to stdout.

Testing Migrations

To verify that a set of pending changesets can be fully rolled back, use the db test command, which will migrate forward, roll back to the original state, then migrate forward again:

java -jar hello-world.jar db test helloworld.yml


Do not run this in production, for obvious reasons.

Preparing A Rollback Script

To prepare a rollback script for pending changesets before they have been applied, use the db prepare-rollback command:

java -jar hello-world.jar db prepare-rollback helloworld.yml

This will output a DDL script to stdout capable of rolling back all unapplied changesets.

Generating Documentation

To generate HTML documentation on the current status of the database, use the db generate-docs command:

java -jar hello-world.jar db generate-docs helloworld.yml ~/db-docs/

Dropping All Objects

To drop all objects in the database, use the db drop-all command:

java -jar hello-world.jar db drop-all --confirm-delete-everything helloworld.yml


You need to specify the --confirm-delete-everything flag because this command deletes everything in the database. Be sure you want to do that first.

Fast-Forwarding Through A Changeset

To mark a pending changeset as applied (e.g., after having backfilled your migrations.xml with db dump), use the db fast-forward command:

java -jar hello-world.jar db fast-forward helloworld.yml

This will mark the next pending changeset as applied. You can also use the --all flag to mark all pending changesets as applied.

More Information

If you are using databases supporting multiple schemas like PostgreSQL, Oracle, or H2, you can use the optional --catalog and --schema arguments to specify the database catalog and schema used for the Liquibase commands.

For more information on available commands, either use the db --help command, or for more detailed help on a specific command, use db <cmd> --help.