In this post, I want to share with you some experience you might find useful for your projects when working with the Grails Database Migration plugin.

Brief information of the plugin:

Name: Grails Database Migration Plugin
Version: 1.4.0
Grails version: 2.5.x
User guide website: https://grails.github.io/grails-database-migration/1.4.0/guide/introduction.html
For getting more details about the plugin: https://grails.github.io/grails-database-migration/

A quick guide of using the plugin

Installation or declaration

With regard to the earlier versions of 2.3, we install it directly by hitting the following command from the project directory:

grails install-plugin database-migration

However, since Grails 2.3, we have to declare all dependencies and plugins in the grails-app/conf/BuildConfig.groovy file.

So, the declaration of using dependencies and plugins can be done in the BuidConfig.groovy as below:

...
    dependencies {
        // specify dependencies here under either 'build', 'compile', 'runtime', 'test' or 'provided' scopes e.g.
        // runtime 'mysql:mysql-connector-java:5.1.29'
        // runtime 'org.postgresql:postgresql:9.3-1101-jdbc41'
        test "org.grails:grails-datastore-test-support:1.0.2-grails-2.4"
    }

    plugins {
        // plugins for the build system only
        build ":tomcat:7.0.70" // or ":tomcat:8.0.22"

        // plugins for the compile step
        compile ":scaffolding:2.1.2"
        compile ':cache:1.1.8'
        // asset-pipeline 2.0+ requires Java 7, use version 1.9.x with Java 6
        compile ":asset-pipeline:2.5.7"

        // plugins needed at runtime but not for compilation
        runtime ":hibernate4:4.3.10" // or ":hibernate:3.6.10.18"
        runtime ":database-migration:1.4.0"
        runtime ":jquery:1.11.1"

        // Uncomment these to enable additional asset-pipeline capabilities
        //compile ":sass-asset-pipeline:1.9.0"
        //compile ":less-asset-pipeline:1.10.0"
        runtime 'org.grails.plugins:i18n-asset-pipeline:1.0.6'
    }
...

In this post, we can see the snippet above shows the plugin declaration in the plugins block. It is a runtime plugin and has version 1.4.0 as the latest one being compatible with Grail 2.x. Once the application is started first after adding that line in BuildConfig.groovy file, the plugin will be downloaded and installed into the target directory.

Basic usages

We need to start any command from the Grails console prompt. The commands start with the prefix dbm- and are followed by the keywords revealing its functionality.

grails> dbm-

dbm-changelog-sync            dbm-changelog-sync-sql        dbm-changelog-to-groovy       dbm-clear-checksums           dbm-create-changelog
dbm-db-doc                    dbm-diff                      dbm-drop-all                  dbm-future-rollback-sql       dbm-generate-changelog
dbm-generate-gorm-changelog   dbm-gorm-diff                 dbm-list-locks                dbm-list-tags                 dbm-mark-next-changeset-ran
dbm-previous-changeset-sql    dbm-register-changelog        dbm-release-locks             dbm-rollback                  dbm-rollback-count
dbm-rollback-count-sql        dbm-rollback-sql              dbm-rollback-to-date          dbm-rollback-to-date-sql      dbm-status
dbm-tag                       dbm-update                    dbm-update-count              dbm-update-count-sql          dbm-update-sql
dbm-validate

For example:

To update the database with the latest migration scripts, the command is dbm-update while the command dbm-update-sql shows us all the SQL updates applied for this run.

To mark all database migration scripts already applied  dbm-changelog-sync is the best command we should use. The command tells the plugin that the database is up-to-date.

Advanced usages

Re-generating checksums

What will you do when running into an invalid checksum exception? If you end up editing some of your changesets with the database migration plugin and try to apply them against the database, you will be greeted by an exception telling you that the changesets don’t match. To overcome this problem, the plugin provides a convenient method to reset all your checksums. Simply invoke:

grails dbm-clear-checksums

This clears the checksum column of the DATABASECHANGELOG table. On the next run, checksums will be recalculated. Read more about this command from the documentation.

Synchronising the database structure

If your database has been updated, it means that you don’t need to run against the latest migration scripts. Therefore, you want to update the DATABASECHANGELOG table to capture the fact that the contents of the changelog.groovy represent the existing schema of your database. To do this, run the following command:

grails dbm-changelog-sync

It will insert some rows corresponding to the latest changesets into the DATABASECHANGELOG table and mark them as EXCUTED.

In conclusion

I hope this post is useful. The database migration plugin is definitively a groovier and more elegant plugin than previous liquibase or autobase offerings. Feel free to give your comments.