2 Getting Started

Installation

Install the plugin by adding the following to your BuildConfig.groovy (replace VERSION with the desired version):

plugins {
    …
    compile ':mongeez:VERSION'
}

Configuration

At a minimum, the plugin needs to know how to connect to your database. If you use the MongoDB GORM plugin, it should use the same database configuration. Otherwise, it will attempt to use intelligent defaults. See Configuration for instructions on how to override the defaults.

Changelog Creation

Next, you'll need to create some changelogs. Currently two formats are supported; JavaScript or XML. The Javascript format is recommended, as it's closer to writing plain MongoDB migration scripts. Documentation of the XML format can be found here. By default, changelog files go in grails-app/migrations.

When using the JavaScript format, start each file with a comment "//mongeez formatted javascript". Then add one or more changeset sections, with a "//changeset AUTHOR:ID" comment at the start of each changeset. Replace AUTHOR with some way to identify the creator of the changeset and replace ID with an identifier for the changeset. If you want a changeset to be run every update (rather than only once), include "runAlways:true" in the changeset comment.

For example:

//mongeez formatted javascript
//changeset bob:1
db.TestCollection.insert({"someField1": "firstChangeSetData"});
//changeset bob:2
db.TestCollection.update({}, {$set: {"someField2": "secondChangeSetData"}}, false, true);
//changeset alice:3 runAlways:true
db.TestCollection.update({"someField1": {$exists: 1}}, {$set: {"someField1": "thirdChangeSetData"}}, false, true);

Some people like to use sequential integers as the IDs for theier changesets within a file. Others prefer a descriptive string. Either is fine; all that matters is that the combination of the author, ID, and file path uniquely identifies the changeset. It isn't truly mandatory to track the author; if desired, you can use a placeholder value like "UNASCRIBED"; just be aware that there's more potential for ID conflict in this case.

Once you have some changesets, you can run the mongeez-update script to update the database

grails mongeez-update