RM, an ORM* for Riak

So in the course of building Sendak for 18F, I wanted to use an ORM. I found that ORMs were very complicated. I found that node itself was kind of poorly-suited to the way that ORMs worked. I also found that ORMs (for Javascript) generally did not provide the functionality I wanted (for example keeping state in the database).

As I sat down to write my own ORM, I realised that the biggest part of it, code-wise, was going to actually be the SQL layer. As it happens, writing SQL parsers, SQL generators, stored procedures, and so forth, while maintaining an agnostic stance towards choice of database (even without this), the task is nothing less than odious, and results in huge code-sprawl, when all I wanted was a way to create some simple objects and store them in a place that bunches of things could get to (accordingly, a json file was not sufficient), and I didn't want to have to worry about the "database layer"; I wanted objects — data structures — that I could read and write without having data logic in my code.

There are lots of document-store and key-value store "databases" out there. For various reasons, I chose Riak to put this on top of. No more need for SQL, native storage of JSON, and it seemed like a win.

Rather than use the rather ponderous and somewhat inscrutable riak-js, I wrote a very tiny library, riak-dc, which is the barest of wrappers around node's own http.

Accordingly, you will find that this library is very tiny, takes up very little space in terms of lines-of-code, is end-to-end javascript & json, and meets the above requirements:

• No stupid SQL tricks
• JSON object storage
• Schema stored in the database
• Exceedingly simple API
• No pyramid of fail

* note: RM is not actually "relational."

How to use RM

Basically, npm install rm should do the trick and install dependencies. Unit tests are mocked, but you will need a Riak somewhere to talk to. riak-dc assumes that you are using http://localhost:8098/riak, and if you are, RM requires no configuration. If not, be sure to initialise riak-dc before using RM.

Key concepts:

RM stores a 'schema' in Riak, from which it derives prototypes of each of the object types stored in the RM. The schema is not actually "bound" to anything, as such, and serves only as a template from which to build new objects.

These objects are stored in a Riak bucket according to their prototype (so all the 'automobile' objects are stored in riak/automobile/{serial}).

Objects are "anonymous" until they are stored in Riak, which gives them a unique serial (for SQL people, you might call this a 'primary key').

Objects also contain no metadata about what they are. So you must keep track of which type of object you have. RM is flexible enough that if you wanted to incorporate a typeof attribute, you could do this, but you would have to keep track of that yourself.

There is no strict checking for whether an object you are storing actually conforms to the schema.

Exported functions:

Unless otherwise specified, all references to returned values are actually promises (using q, rather than the value itself). So "returns a hash" means "returns a promise to a hash."

• add_object( type, object )

Takes two arguments, the type of object being added and an anonymous object to be added. Note that if this object is already in Riak, an Error will be returned. For existing objects, use update_object.

• del_object( type, object )

Takes two arguments, the type of object to be deleted from Riak and the object itself. This object must have a serial, or an exception will be thrown.

• get_objects( type )

Takes one argument, the type of objects requested. This returns all the objects of that type in Riak. This is actually a very fast operation in Riak at most practical scales.

Because Riak allows the storage of zero-byte tuples, it is possible to store an object in Riak which is defined but null. In the event this happens, you will receive an Error instead of the object (rather than not returning or returning the empty list or similar).

• get_schema( )

Returns a hash of what the objects look like in Riak. This includes metadata and should not be used to "create new objects" (see new_object). Takes no arguments.

• new_object( type )

Takes object type as sole argument, and returns a new object with relevant attributes from the schema. This will not be stored until add_object is called.

• object_types( )

Takes no arguments and returns a list of object types defined in the schema.

• update_object( type, object )

Provided a type and object, RM will attempt to find the object in Riak, delete that object, and re-insert, providing you with a new copy of your object with appropriate serial. Note that deleted objects are tricky in Riak, so be sparing about the this operation (delete & insert).

The basic design pattern

var rm     = require( 'rm' )
	, types   = rm.object_types()
	, schema  = rm.get_schema()
	, banana  = rm.new_object( 'fruit' );

banana['color'] = 'green';

var pbanana = rm.add_object( banana ).then( function (b) {
	// 'pbanana' infers 'promise to a banana'
	//
	// the banana object now has a serial and can be referenced in Riak.
	banana = b;

	// Time elapses...

	banana['color'] = 'yellow';

	var promise = rm.update_object( 'fruit', banana );

	promise.then( function (b) {
		// What will you do with your now-yellow banana?
		//
		banana = b;

		// Time elapses...

		// This will not return anything meaningful, although an error will be
		// returned if the serial for this banana is not found.
		//
		rm.del_object( 'fruit', banana ).then( function (e) {
			if (typeof e == 'error') {
				console.log( e )
			}
		} );
	} );

} );

What's in the box

There are two tools in the bin directory, rm.js and backupdb.js.

• rm.js is a simple command-line tool to interface with RM. For example, --get-schema will return the schema as it appears in Riak, and you can use --add-object --bucket bucketname --tuple base_64_encoded_object to add elements to the database. And so on.

• backupdb.js because Riak is not a relational database, we don't have anything analogous to pg_dumpall, and no real formal language in which to dump the database. But it is still important to have backups in a modern, production environment. So backupdb.js is a sort of minimum-effort "store all the things in the database on the disk somewhere." It can print to stdout for unixy pipey kinds of things, take a filename, or an s3 bucket (you will need credentials for this, obviously).

If you need to effectively "truncate" the database, there's a tool in the riak-dc package that will remove everything from the Riak ring. Careful with that axe, Eugene.

Future plans

If you look over the schema in examples/, you will notice I have left a couple fields reserved, and have stubs for relational properties. At some point RM may actually be relational, but it serves my purpose for now. Additionally, Riak supports Javascript, so it should be possible to add constraints to columns (that is, attributes of objects) such as "only allow this to be a url" and similar.

Don't mess with those fields.

I'm not going to break compatibility for a long time, though. So, in the event those things are added, it should be transparent.

Author

@janearc, jane@cpan.org