(Quick Reference)

1 Introduction to the Database Migration Plugin - Reference Documentation

Authors: Burt Beckwith

Version: 1.4.0

Table of Contents

1 Introduction to the Database Migration Plugin

The Database Migration plugin helps you manage database changes while developing Grails applications. The plugin uses the Liquibase library.

Using this plugin (and Liquibase in general) adds some structure and process to managing database changes. It will help avoid inconsistencies, communication issues, and other problems with ad-hoc approaches.

Database migrations are represented in text form, either using a Groovy DSL or native Liquibase XML, in one or more changelog files. This approach makes it natural to maintain the changelog files in source control and also works well with branches. Changelog files can include other changelog files, so often developers create hierarchical files organized with various schemes. One popular approach is to have a root changelog named changlog.groovy (or changelog.xml) and to include a changelog per feature/branch that includes multiple smaller changelogs. Once the feature is finished and merged into the main development tree/trunk the changelog files can either stay as they are or be merged into one large file. Use whatever approach makes sense for your applications, but keep in mind that there are many options available for changelog management.

Individual changes have an ID that should be globally unique, although they also include the username of the user making the change, making the combination of ID and username unique (although technically the ID, username, and changelog location are the "unique key").

As you make changes in your code (typically domain classes) that require changes in the database, you add a new change set to the changelog. Commit the code changes along with the changelog additions, and the other developers on your team will get both when they update from source control. Once they apply the new changes their code and development database will be in sync with your changes. Likewise when you deploy to a QA, a staging server, or production, you'll run the un-run changes that correspond to the code updates to being that environment's database in sync. Liquibase keeps track of previously executed changes so there's no need to think about what has and hasn't been run yet.


Your primary interaction with the plugin will be using the provided scripts. For the most part these correspond to the many Liquibase commands that are typically executed directly from the commandline or with its Ant targets, but there are also a few Grails-specific scripts that take advantage of the information available from the GORM mappings.

All of the scripts start with dbm- to ensure that they're unique and don't clash with scripts from Grails or other plugins.

1.1 History


  • April 22, 2014
  • October 28, 2013
  • October 27, 2013
  • September 2, 2013
  • July 1, 2013
  • April 17, 2013
  • January 4, 2013
  • January 4, 2013
  • January 3, 2013
  • December 6, 2012
    • 1.2.2 release
  • December 1, 2012
  • October 28, 2012
  • May 11, 2012
  • August 17, 2011
  • April 19, 2011
    • 0.2.1 release
  • February 13, 2011
    • 0.2 release
      • One breaking change: the default migrations folder changed from grails-app/conf/migrations to grails-app/migrations
  • May 22, 2010
    • initial 0.1 release