Permalink
Browse files

update the README

  • Loading branch information...
1 parent cd2fa48 commit e1df25775505e58e5d54d93717668002ba8e7618 @paulca committed Feb 8, 2009
Showing with 29 additions and 15 deletions.
  1. +29 −15 README.textile
View
@@ -4,9 +4,9 @@ Stuffing is a Rails plugin that allows you to really easily add CouchDB document
I love CouchDB and I love the principles behind it. I love the flexibility of a 'schemaless' document, crash-only architecture and single file databases.
-After prototyping a few apps using CouchDB however, I found that I was trying to bend CouchDB around corners that it just didn't fit. There are so many great things that have been developed around ActiveRecord that I take for granted every day like plugins that 'just work' : will_paginate, Paperclip, ThinkingSphinx.
+After prototyping a few apps using CouchDB however, I found that I was trying to bend CouchDB around corners that it just didn't fit. There are so many great things that have been developed around ActiveRecord that I take for granted every day. Plugins that 'just work' like will_paginate, Paperclip, ThinkingSphinx.
-Still, from playing around with CouchDB, I found I was missing some things from my experiments with it. Just adding a form field to a form and getting a per-record field. It's really nice.
+Still, from playing around with CouchDB, I found myself missing some of the things from my experiments with it. Just adding a form field to a form and getting a per-record field. It's really nice.
And so: Stuffing. Stuffing bridges the gap between building a completetly "ActiveRecord aware" or "ActiveRecord like" wrapper around CouchDB and simply adding the ability to add a "CouchDB" store to an existing ActiveRecord model.
@@ -19,7 +19,7 @@ You can install CouchDB via the CouchDB website:
http://couchdb.apache.org/downloads.html
*CouchRest*
-Stuffing uses CouchDB via "jchris's CouchRest gem":http://github.com/jchris/couchrest/tree/master.
+Stuffing accesses CouchDB via "jchris's CouchRest gem":http://github.com/jchris/couchrest/tree/master.
<pre><code>
sudo gem sources -a http://gems.github.com
@@ -37,24 +37,24 @@ Stuffing is a Ruby on Rails plugin. Installation is as easy as:
h2. Example
<pre><code>
-class Post < ActiveRecord::Base
+class Post &lt; ActiveRecord::Base
stuffing
end
</code></pre>
-This enables Stuffing by adding a 'stuffing' method to your ActiveRecord model. This method is a hash that will be persisted in CouchDB after you save or update your model.
+That's all you need to get going. This enables Stuffing by adding a 'stuffing' method to your ActiveRecord model. This method is a hash that will be persisted in CouchDB after you save or update your model.
-By default, Stuffing will connect to CouchDB on http://localhost:5984. It will use or create a CouchDB database the same name as your Rails app, as defined by your RAILS_ROOT folder and your current environment. For exmplae, if your RAILS_ROOT were /var/www/stuffing_app in production environment, by default Stuffing would use stuffing_app_development as the DB name. Documents are stored with an ID of "Class-ID", so or the example "Post" model above, document IDs in CouchDB would be "Post-1", "Post-2". "Post-3" etc.
+By default, Stuffing will connect to CouchDB on http://localhost:5984. It will use or create a CouchDB database the same name as your Rails app, as defined by your RAILS_ROOT folder and your current environment. For example, if your RAILS_ROOT were /var/www/stuffing_app in production environment, by default Stuffing would use stuffing_app_development as the DB name. Documents are stored with an ID of "Class-ID", so for the example "Post" model above, document IDs in CouchDB would be "Post-1", "Post-2". "Post-3" etc.
-To save attributes, just assign a hash to your "stuffing":
+To save attributes, you can treat your 'stuffing' method like any other ActiveRecord attribute. Just assign a hash to your "stuffing":
<pre><code>
@post = Post.new
@post.stuffing = {:title => 'Fantastic', :description => 'this is an example post'}
@post.save
</code></pre>
-The stuffing method can take any hash you want, which will be saved to CouchDB as JSON. Simple types (Strings, Integers etc. will be preserved.)
+The stuffing method can take any hash you want, which will be saved to CouchDB as JSON. Simple types (Strings, Integers etc. will be preserved. See the CouchRest documentation for more on how this works)
Your stuffing is retrieved when you load your posts via ActiveRecord:
@@ -72,31 +72,45 @@ A sensible set of defaults should let you get up and running with Stuffing / Cou
You can specify a different method name for your stuffing:
<pre><code>
- class Post < ActiveRecord::Base
+ class Post &lt; ActiveRecord::Base
stuffing :contents
end
</code></pre>
This will give you @post.contents instead of @post.stuffing
-You can also dynamically choose the host, database and Couch document ID:
+You can also dynamically choose the host, database and Couch document ID. You can call any method, or method chain, prefixed by ':'
+(inspired by the "interpolated path and url strings in Paperclip":http://dev.thoughtbot.com/paperclip/classes/Paperclip/Attachment.html#M000066)
<pre><code>
- class Blog < ActiveRecord::Base
+ class Blog &lt; ActiveRecord::Base
end
- class Post < ActiveRecord::Base
+ class Post &lt; ActiveRecord::Base
belongs_to :blog
- stuffing :host => ':couch_host.example.com'
+ stuffing :host => ':couch_host.example.com', :port => '1234', :database => 'blog-:blog.id', :id => ':class-:id-:locale'
- def couch_host
+ def locale
+ ['en', 'fr'].rand
+ end
+ def couch_host
+ 'subdomain'
end
end
</code></pre>
+This will connect, for example, to the 'blog-1' database on http://subdomain.example.com on port 1234, saving the stuffing document as 'Post-1-en' or 'Post-1-fr' depending on the result of the 'locale' method.
+
+h2. What's next
+
+From where I see it, this is a lot of fun and potentially kind of powerful. The plugin is well tested for basic usage. It's not, however, in any way optimised for performance.
+
+There's probably a lot wrong with mixing MySQL and CouchDB in this way. What this plugin is, however, is a really quick, really easy way of adding some of the most powerful features of CouchDB to your app without leaving the save, fluffy familiar world of MySQL / ActiveRecord behind.
+h3. About me
-Fire up CouchDB and away you go.
+I'm Paul Campbell. I'm a partner in Contrast (http://www.contrast.ie) and I work on Exceptional, a Ruby on Rails exception tracker (http://getexceptional.com).
+Follow me on Twitter http://twitter.com/paulca
Copyright (c) 2009 Paul Campbell, released under the MIT license

0 comments on commit e1df257

Please sign in to comment.