Quilt / Couchquilt by TF

Access CouchDB JSON documents from filesystem

Get your Quilt

Installation

The preferred way to install Quilt is via Rubygems:

gem install couch-quilt

Das wars!

Set out your Quilt

Just type the following few words:

couchquilt http://127.0.0.1:5984 couch_dir

Now the databases on http://127.0.0.1:5984 are mapped to the (newly created) directory ./couch_dir.

Sit down on your Couch

Inspect your filesystem at ./couch_dir and...

Relax!

Tip: touch _delete will delete a database or document.

fstab entry

I like the following line in my /etc/fstab:

couchquilt#http://127.0.0.1:5984    /mnt/quilt    fuse    user,noauto    0 0

That way I can mount Quilt just with mount /mnt/quilt.
Note the noauto option. This is required because it is currently impossible to do the mount on bootup. I don't know why. Do you?

Digging deeper

CouchDB is a document based Database System. The documents are stored in JSON format. Documents can have so called attachements, so CouchDB can easyly store files.

CouchDB holds application code in Design Documents. These documents are normal CouchDB documents, which have the prefix _design/ as id, for example _design/Site. Design documents include application code, that is views (Map-Reduce functions), show and list transformations. Application Assets, as Images and CSS files, are stored inside design documents as attachements, too.

Quilt maps CouchDB documents to a filesystem, provided by FuseFS. Quilt is currently using Ruby to create a Fuse Filesystem.

The CouchDB documents are mapped to a directory structure in the following way:

Databases are directories in the root folder
each Document is a directory named after the id of the document. Design documents are stored in a subfolder called _design
a Key in the hash of the document is a directory inside the documents folder
the Value of the hash lives inside the key folder
Strings are plain text files with the extension .js
Booleans are plain text files with the extension .b.js
Floats are plain text files with the extension .f.js
Integers are plain text files with the extension .i.js
Arrays are directories where all elements are numbered with suffix i, like 0i, 1i and 2i.js

A JSON CouchDB document (design document)

{
   "_id": "_design/Site",
   "_rev": "955-e08d9e52c17159fa1c981202ae6bfcbb",
   "language": "javascript",
   "views": {
       "all": {
           "map": "function(doc) { emit(doc['_id'], 1) }"
       },
       "by_domain": {
           "map": "function(doc) { emit(doc['domain'], 1) }"
       }
   }
}

The corresponding Quilt filesystem

couchdb/
  _design/
    Site/
      _id.js                # _design/Site
      _rev.js               # 955-e08d9e52c17159fa1c981202ae6bfcbb
      _list/
      _show/
      _view/
        all/
          offset.i.js       # 0
          rows/
          total_rows.i.js   # 0
        by_domain/
          offset.i.js       # 0
          rows/
          total_rows.i.js   # 0
      language.js           # javascript
      views/
        all/
          map.js            # function(doc) { emit(doc['_id'], 1) }
        by_domain/
          map.js            # function(doc) { emit(doc['domain'], 1) }

(Here the database had no other documents)

Getting involved

If you share my euphoria on this approach feel free to fork my Quilt and start experimenting with Rubys FuseFS API and CouchDB.

Some resources you might consider as a starting point:

You can download Quilts source in either zip or tar formats.

You can also clone TFs Quilt with Git by running:

$ git clone git://github.com/jo/quilt

Author

TF Johannes Jörg Schmidt <schmidt@netzmerk.com>