Grails CouchDB Plugin

  • Authors: Marc Palmer
0 vote
Dependency:
compile ":gorm-couchdb:0.9.2"

 Documentation

Summary

Installation

grails install-plugin gorm-couchdb

Description

Install

To install gorm-couchdb you just need to do

grails install-plugin gorm-couchdb
and grails will pull it from the repository

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
This annotation can also take a "type" parameter, we've defined this so that you can easily define what kind of document you are storing in CouchDB, by default it uses the class name (lower-cased) as the type name. But you can configure this by doing this instead
@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

It is possible to store your views in your grails project for pushing into CouchDB. You just have to set up a directory structure with all your design documents and views in them, like this:
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".