grails-mongeez / src / docs / guide / gettingStarted.gdoc

h4. Installation

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

repositories {
    mavenRepo ''
plugins {
    compile ':mongeez:VERSION'

The repository is currently needed because the plugin currently depends on a snapshot version of [Mongeez|].  It is expected that the need to configure a snapshot repository will be eliminated in a future release.

h4. 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|guide:configuration] for instructions on how to
override the defaults.

h4. 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

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|Update Scripts] script to update the database
grails mongeez-update