2 Getting Started

grails install-plugin mongodb

Or configure it as a dependency in BuildConfig.groovy:

plugins {
	compile ':mongodb:1.0.0.GA'
}

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 = 27017
        username = "blah"
        password = "blah"
        databaseName = "foo"
    }
}

2.1 Using Mongo Standalone

grails uninstall-plugin hibernate

Or if it has been defined in the grails-app/conf/BuildConfig.groovy file comment out the hibernate line in the plugins block

compile ':hibernate:2.0.0'

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

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

Mongo Database Connection 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.

Global Mapping Configuration

Using the grails.mongo.default.mapping setting in Config.groovy you can configure global mapping options across your domain classes. This is useful if, for example, you want to disable optimistic locking globally or you wish to use DBRefs in your association mappings. For example, the following configuration will disable optimistic locking globally and use DBRefs for all properties:

grails.mongo.default.mapping = {
    version false
    '*'(reference:true)
}

The * method is used to indicate that the setting applies to all properties.