Install

To install gorm-couchdb you just need to do

grails install-plugin gorm-couchdb

Changes in this release

• v0.6: Upgraded to work with Grails 1.3; fixed an error when querying a view that didn't return a map value; tested with CouchDB 0.11.

Trip-Planner Sample Application

We built a CouchDB version of the Grails Trip-Planner tutorial. The original tutorial is here http://www.ibm.com/developerworks/java/library/j-grails01158/index.html. The CouchDB project is available here http://github.com/downloads/coryhacking/gorm-couchdb/trip-planner.zip.

What works in this release

• tested to work on CouchDB versions 0.9.0 - 0.11.0
• domain objects for CouchDB-backed objects can be stored in the domain folder
• id and version are automatically injected to the domain class
• standard gorm get(), delete(), save() methods
• standard domain constraints, including errors, hasErrors, etc.
• transients
• "properties" setter for assigning a group of properties, e.g., "task.properties = params" inside of a controller
• document attachments
• version; however, versions in CouchDB are strings so don't try to convert it to a long
• custom "type" naming to differentiate your document types in your CouchDB database
• automatically converts common types (dates, numbers) back and forth from CouchDB
• dynamic finder support
• can load views by name
• can store .js views for automatic loading (and reloading during development) into CouchDB
• updating of timestamp fields createdDate, and lastUpdated if they exist

Configuration

To configure your application to use gorm-couchdb you can go into your Datasource.groovy file and add

couchdb {
    host = "localhost"
    port = 5984
    database = "mydb"
    username = ""
    password = ""
}

Host, port, username, and password are all optional at this point, only configure those if your db is somewhere else. You can override the database in the individual development, test, or production sections for specific databases you've setup for those environments.

If you're also using Hibernate, you should also set the configClass in your dataSource to look something like this

import grails.plugins.couchdb.cfg.CouchDomainConfiguration
dataSource {
    configClass = CouchDomainConfiguration.class
    …
}

use CouchAnnotationConfiguration.class if you're using Hibernate annotations.

Once you've finished configuring gorm-couchdb you are ready to go!

Domain Objects

First you will need to mark your objects as CouchDB objects. To do this you will need to include the following annotation at the top of your class:

grails.plugins.couchdb.CouchEntity

@CouchEntity(type="project-task")

Where "project-task" is the type you would like to use to differentiate this in your CouchDB database

To turn the "type" column off altogether simply declare an empty value for type.

@CouchEntity(type="")

By default gorm-couchdb injects the id and version properties into your class, but if you should want to use a custom mapping for these you can use the following annotations:

@Id
String taskId
@Version
String taskVersion

Here is an example domain object:

import grails.plugins.couchdb.CouchEntity
@CouchEntity
class Trip {
    String name
    String city
    Date startDate
    Date endDate
    String purpose
    String notes
    Date createdDate
    Date lastUpdated
    static constraints = {
        name(nullable: false, blank: false)
        city()
        startDate()
        endDate()
        purpose()
        notes()
    }
}

Views and Finders

grails-app/
   conf/
      couchdb/
         foo/
            list.map.js
            count.map.js
            count.reduce.js

We haven't enabled dynamic finders yet, but you can query them by name. The implemented finders include

queryView(String viewName, Map options)
queryViewAndKeys(String viewName, List keys, Map options)

For example:

queryView("foo/list", ["max":10])

Will return the first 10 values mapped by the list.map.js function. The standard options "max" and "offset" are mapped to the CouchDB options "limit" and "skip". You can also pass the standard CouchDB options "desc", "update", "group", "stale" and "reduce".