2 Getting Started

The first step is to add a dependency for the plugin in BuildConfig.groovy:

plugins {
   …
   runtime ':database-migration:1.3.6'
}

Typical initial workflow

Next you'll need to create an initial changelog. You can use Liquibase XML or the plugin's Groovy DSL for individual files. You can even mix and match; Groovy files can include other Groovy files and Liquibase XML files (but XML files can't include Groovy files).

Depending on the state of your database and code, you have two options; either create a changelog from the database or create it from your domain classes. The decision tends to be based on whether you prefer to design the database and adjust the domain classes to work with it, or to design your domain classes and use Hibernate to create the corresponding database structure.

To create a changelog from the database, use the dbm-generate-changelog script:

grails dbm-generate-changelog changelog.groovy

or

grails dbm-generate-changelog changelog.xml

depending on whether you prefer the Groovy DSL or XML. The filename is relative to the changelog base folder, which defaults to grails-app/migrations.

If you use the XML format (or use a non-default Groovy filename), be sure to change the name of the file in Config.groovy so dbm-update and other scripts find the file:

grails.plugin.databasemigration.changelogFileName = 'changelog.xml'

Since the database is already correct, run the dbm-changelog-sync script to record that the changes have already been applied:

grails dbm-changelog-sync

Running this script is primarily a no-op except that it records the execution(s) in the Liquibase DATABASECHANGELOG table.

To create a changelog from your domain classes, use the dbm-generate-gorm-changelog script:

grails dbm-generate-gorm-changelog changelog.groovy

or

grails dbm-generate-gorm-changelog changelog.xml

If you haven't created the database yet, run the dbm-update script to create the corresponding tables:

grails dbm-update

or the dbm-changelog-sync script if the database is already in sync with your code:

grails dbm-changelog-sync

If you use the searchable plugin you need to configure it to run after the database migrations have run. Either in Searchable.groovy or in Config.groovy (if that's where you configure Searchable):

// disable the plugin's operations here.  we'll re-enable them in the Bootstrap to avoid conflicts with database-migration
mirrorChanges = false
bulkIndexOnStartup = false

In Bootstrap.groovy:

class BootStrap {
   def searchableService
   def init = { servletContext ->
      // do any data loading you would normally do
      // Manually start the mirroring process to ensure that it comes after the automated migrations.
      println "Performing bulk index"
      searchableService.reindex()
      println "Starting mirror service"
      searchableService.startMirroring()
   }
}

Source control

Now you can commit the changelog and the corresponding application code to source control. Other developers can then update and synchronize their databases, and start doing migrations themselves.

2.1 Migration from Autobase

Location of migration scripts

Autobase defaulted to putting its migration scripts into a ./migrations directory, whereas the Database Migration plugin uses ./grails-app/migrations as the default. So, you can either move your scripts or add this setting to your grails-app/conf/Config.groovy file:

grails.plugin.databasemigration.changelogLocation = "migrations"

New syntax for all scripts

Autobase allowed you to write changelog files that just included the change sets one after the other. This isn't supported by the Database Migration plugin, so all changelogs must put their change set definitions inside a block like so:

databaseChangeLog = {
   changeSet(...) { … }
   changeSet(...) { … }
   …
}

In addition, if your main Autobase changelog specifies a logical file path (see next section), you will have to use the syntax:

databaseChangeLog = {
   logicalFilePath "app-autobase"
   …
}

in all the changelog files. If you don't do this, the plugin won't recognise that existing migrations have already been applied to a database and all of them will be reapplied.

These changes also apply to the main changelog, but there are some other differences to cover for that.

Parent changelog differences

The syntax for the main (or parent) Autobase changelog file looks like:

databaseChangeLog(logicalFilePath: "appName-autobase") {
   include "./migrations/batch/SomeBigChanges.groovy"
   include "./migrations/changelog-1.0.1.groovy"
   include "./migrations/changelog-1.0.5.groovy"
}

The new format is noticeably different:

databaseChangeLog = {
   logicalFilePath "site-autobase"
   include file: "batch/SomeBigChanges.groovy"
   include file: "changelog-1.0.1.groovy"
   include file: "changelog-1.0.5.groovy"
}

In particular, note that:

• The databaseChangeLog line is different
• The logical file path must be defined inside the block
• include takes a named file argument
• The file paths passed to include are relative to the configured migrations directory

Fortunately, these changes are highly localised and pretty trivial to implement.

modifyColumn refactoring no longer available

The modifyColumn refactoring has been removed in the version of Liquibase that comes with the Database Migration plugin. Instead you should use the new modifyDataType refactoring like so:

…
changeSet(id:'IncreaseCommentBodySize', author:'someone') {
   modifyDataType tableName: 'comment', columnName: 'body', newDataType: 'TEXT'
}

The parameters are the same as for modifyColumn, but the syntax is somewhat different.