2. Getting Started

To get started with GORM for Mongo you need to install the plugin into a Grails application:

grails install-plugin mongodb

With that done you need to set up a running Mongodb server. Refer to the Mongodb Quick Start guide for an explanation on how to startup a Mongo instance. Once installed starting Mongo is typically a matter of executing the following command:

MONGO_HOME/bin/mongod

With the above commands executed in a terminal window you should see output like the following appear:

Thu Nov 11 16:54:08 MongoDB starting : pid=4600 port=27017 dbpath=/data/db/ 64-bit
Thu Nov 11 16:54:08 db version v1.6.3, pdfile version 4.5
Thu Nov 11 16:54:08 git version: 278bd2ac2f2efbee556f32c13c1b6803224d1c01
Thu Nov 11 16:54:08 sys info: Darwin erh2.10gen.cc 9.6.0 Darwin Kernel Version 9.6.0: Mon Nov 24 17:37:00 PST 2008; root:xnu-1228.9.59~1/RELEASE_I386 i386 BOOST_LIB_VERSION=1_40
Thu Nov 11 16:54:08 [initandlisten] waiting for connections on port 27017
Thu Nov 11 16:54:08 [websvr] web admin interface listening on port 28017

As you can see the server is running on port 27017, but don't worry the Mongodb plugin for Grails will automatically configure itself to look for Mongodb on that port by default.

If you want to configure how Grails connects to Mongo then you can do so using the following settings in grails-app/conf/DataSource.groovy:

grails {
    mongo {
        host = "localhost"
        port = 27107
        username = "blah"
        password = "blah"
        databaseName = "foo"
    }
}

2.1 Using Mongo Standalone

If you plan to use Mongo as your primary datastore then you need to uninstall the Hibernate plugin:

grails uninstall-plugin hibernate

With this done all domain classes in grails-app/domain will be persisted via Mongo and not Hibernate. You can create a domain class by running the regular create-domain-class command:

grails create-domain-class Person

The Person domain class will automatically be a persistent entity that can be stored in Mongo.

2.2 Combining Mongo and Hibernate

If you have both the Hibernate and Mongo plugins installed then by default all classes in the grails-app/domain directory will be persisted by Hibernate and not Mongo. If you want to persist a particular domain class with Mongo then you must use the mapWith property in the domain class:

static mapWith = "mongo"

Alternatively you can persist Hibernate entities to Mongo using the special mongo scope added to all Hibernate entities:

def hibernatePerson = Person.get(1)
hibernatePerson.mongo.save()
def mongoPerson = Person.mongo.get(1)

2.3 Advanced Configuration

As mentioned the GORM for Mongo plugin will configure all the defaults for you, but if you wish to customize those defaults you can do so in the your grails-app/conf/DataSource.groovy file:

grails {
    mongo {
        host = "localhost"
        port = 27107
        username = "blah"
        password = "blah"
        databaseName = "foo"
    }
}

The databaseName setting configures the default database name. If not specified the databaseName will default to the name of your application.

You can also customize the Mongo connection settings using an options block:

grails {
    mongo {
        options {
            autoConnectRetry = true
            connectTimeout = 300
        }
    }
}

Available options and their descriptions are defined in the MongoOptions javadoc.

In production scenarios you will typically use more than one Mongo server in either master/slave or replication scenarios. The plugin allows you to configure replica pairs:

grails {
    mongo {
        replicaPair = [ "localhost:27017", "localhost:27018"]
    }
}

Or replica sets:

grails {
    mongo {
        replicaSet = [ "localhost:27017", "localhost:27018"]
    }
}

The replica sets are defined using a list of strings that conform to the Mongo DBAddress specification.