Example for using Neo4j with Grails

In reply to my today’s annoncement of the Neo4j Grails plugin, @StigLau asked me to provide an example for using the Neo4j Grails plugin. So here we go:

  1. Create your sample application:
    grails create-app neo4jtest; cd neo4jtest
  2. Add the Neo4j plugin:
    grails install-plugin neo4j
  3. create some sample domain classes:
    grails create-domain-class Author
    grails create-domain-class Book
  4. create a controller for the domain class
    grails create-controller Author
    grails create-controller Book
  5. modify the domain classes:
    import grails.plugins.neo4j.Neo4jEntity
    class Author {
        String name
        Date dob
        static hasMany = [ books: Book ]


    import grails.plugins.neo4j.Neo4jEntity
    class Book {
        String title
        static belongsTo = [author:Author]
  6. modify the controller to use dynamic scaffolding:
    class AuthorController {
        def scaffold = true
    class BookController {
        def scaffold = true
  7. start up the application:
    grails run-app
  8. use it, love it: go to http://localhost:8080/neo4jtest, add some authors and books.
  9. to explore the Neo4j node space created with your grails app, check out Neoclipse.

UPDATE: Use Grails 1.2.1


Neo4j Grails Plugin

Today I released the first version of the  Neo4j Grails plugin. The plugin’s goal is to provide an alternative approach for storing Grails domain classes: in the Neo4j database.

Neo4j is a relative new and very interesting approach for persitence in a non-SQLish way. Neo4j is a graph database and uses the concept of


A node is the basic building block. It normally represents a “something”, a entity.


Relationsships are associations between nodes. Each relationship connects exactly two nodes. Relationsships have a direction: incoming, outgoing or both.


Each node or relationship might contain a set of properties. A property has a name (String) and a value (primitive datatype). Complex value are not allowed for properties.

This is completely different from the SQL approach. There are no tables, columns, indexes, and other stuff we’ve dealt with for years. Somewhat crucial is the way how to organize the node space. Neo4j gives some advice here.

Neo4j itself uses the AGPL license, the plugin is licensed the WTFPL.

How the plugin works

Using Groovy’s metaprogramming capabilities, the basic CRUD-methods list, save, get and delete are added transparently to each domain class. In addition, each domain instance gets a ‘node’ property referencing the associated Neo4j Node.

For each domain class a subreference node is created related to the reference aka root node. Each domain instance holds a relation to it’s subreference node. For non-primitive properties, either relations to other domain nodes are used or they are converted to strings using the Spring’s PropertyEditor approach.

Aside from this, the plugin starts up and closes the Neo4j database. The database’s path is configured using the grails.neo4j.storeDir property in Config.groovy.

Howto use the plugin

The plugin can be used transparently in a Grails application. The only thing you have to do is to remove the hibernate plugin and install the neo4j plugin:

grails uninstall-plugin hibernate
grails install-plugin neo4j

Add some domain classes and controllers with scaffolding – they should work.

What currently works

  • basic CRUD operations on domain classes
  • one-to-one, one-to-many, many-to-one and many-to-many relations of domain classes
  • the current implementation supports scaffolding
  • Together with the acegi plugin, you can store your user, role and requestmap information in neo4j. Since the default UserDetailsService relies on Hibernate’s SessionFactory you have to use a custom UserDetailsService to get this working.

What’s still missing (and hopefully will be added in upcoming releases)

  • currently all constraints are ignored
  • only a subset of the domain methods are implemented
  • dynamic finders have only a very basic support: just DomainClass.findBy[Property](value) works so far

New planned features

  • SVG controller/views to display the complete object graph, just like Neoclipse does.
  • Gant scripts for automatically snapshotting and restoring the database
  • Criteria queries implemented using Neo4j traversers

Any feedback is appreciated.


Gnome and CTI (computer-telephone-integration)

On my desk, there’s a Siemens Gigaset SX353 connected to the desktop PC via USB. There’s a nice command line tool for managing the telephone, esp. dialing numbers is possible using

gigacontr --dev /dev/ttyGB0 --dial 1 <number> 10

Unfortunately when passing in a international number with the “+” notation, e.g. +49163123456 the phone will not use the “+”. This could be easily solved with a small python wrapper script

import sys, os
assert len(sys.argv)==2
device = "/dev/ttyGB0"
internal_number = "10"
command = "/usr/local/sbin/gigacontr --dev %s --dial 1 %s %s"
number = sys.argv[1]

number = number.replace("+", "00")
if len(number) > 8 and number[0:2]=='49':
	number = "00%s" % (number)

command = command % (device, number, internal_number)

Gnome supports configuring a handler for callto: URLs. Using gconf-editor modify the setting /desktop/gnome/url-handlers/callto/command must be set to

<path-to>/ %s

To use Thunderbird’s addressbook with this, enable in Tool | Additional Settings | Misc the option “insert callto: link for phonenumbers”. When viewing contact data, the phone numbers show up as links. When clicking the phone number, the phone dials that number. Cool!

Even cooler: For Firefox, there the wonderful Telify addon that finds phone number in webpages and converts them to links. Telify must be configured to use callto: URLs instead of the default tel: URLS.