October 27, 2008 by alex
Update: the gem is now available, see the installation instructions below.
After several weeks of incubating on my computer it’s finally time to get real: I have just open sourced Couch Potato under the MIT license. You can get Couch Potato on github now. For an introduction to CouchDB and ruby please read my previous blog post A CouchDB primer for an ActiveRecord mindset. The following is a very short introduction into using Couch Potato. If you want to know more you can start with the README.
The goal of Couch Potato is to create a migration path for users of ActiveRecord and other object relational mappers to port their applications to CouchDB. It therefore offers a basic set of the functionality provided by most ORMs and adds functionality unique to CouchDB on top.
Couch Potato is available as a gem from http://gems.github.com, so you can just do
Alternatively you can download the sources from github. If you are using rails just copy the files into vendor/plugins, create a RAILS_ROOT/config/couchdb.yml file (see the README for the format) and you are ready to go. For other applications you will have to require the lib/couch_potato.rb file and then set the database name by calling
CouchPotato::Config.database_name = 'name of the db'.
As Couch Potato is still very young you can expect its feature set to grow quite a bit in the near future. What you can download now is the very core together with a few features giving you a glimpse of what is about to come:
Create a new class and make its instances persistable by including the Persistence module. As there is no schema in a CouchDB you have to declare the properties you want to persist:
Now you can save your objects:
You can of course also retrieve your instance:
As of now has_many and belongs_to are supported. By default the associated objects are stored in separate documents linked via foreign keys just like in relational databases.
When saving an object all associated objects are automatically saved as well. All these save operations are sent to CouchDB in one operation which means the whole process is atomic across all objects saved, plus only one database roundtrip is required making it much faster.
As CouchDB can not only store flat structures you also store associations inline:
This will store the addresses of the user as an array within your CouchDB document.
Couch Potato supports the usual lifecycle callbacks known from ActiveRecord:
Couch Potato supports versioning your objects, very similar to the popular acts_as_versioned plugin for ActiveRecord. To use it include the module:
After that your object will have a version that gets incremented on each save.
You can access the older versions via the versions method.
When passing a version number the version method will only return that version:
Couch Potato supports ordered lists for has_many relationships (with the :stored => :separately option only), very similar to the popular acts_as_list plugin for ActiveRecord. To use it include the module:
You can move items up and down simply by changing the position:
Couch Potato is very young and it’s open source, so if you find any bugs (you most definitely will) please go to the bug tracker and file a ticket. If you want to contribute please create a fork on github. If you have ideas for improvements please email me or comment on this post.