Clutch is a Clojure library for Apache CouchDB. Although it’s in an early stage of development (Clutch API subject to change), Clutch supports most of the basic Apache CouchDB APIs. To get a sense of where we are at with Clutch, please view the tests.

  (ns #^{:author "Tunde Ashafa"}
      clutch-example
      (:use com.ashafa.clutch))

  (def example-database
    (get-database {:name     "clutch_test_db"
                   :language "clojure"}))     ; use Clutch (Clojure) view server

  (with-db example-database
           ;; insert or update multiple documents
           (bulk-update [{:test-grade 10}
                         {:test-grade 20}
                         {:test-grade 30}])
           ;; create temporary (or permanent) views using clojure 
           (ad-hoc-view
             (with-clj-view-server
                {:map    (fn [doc] [[nil (:test-grade doc)]])
                 :reduce (fn [keys values _] (apply + values))}))) ; => 60

To include Clutch in your project, simply add the following to your project.clj:

(:dependencies [com.ashafa/clutch "0.2.5"])

and run…

lein deps

Or, if you’re using Maven, add this dependency to your pom.xml:

  <dependency>
      <groupId>com.ashafa</groupId>
      <artifactId>clutch</artifactId>
      <version>0.2.5</version>
  </dependency>

Clutch is compatible with Clojure 1.2.0 and 1.3.0.

CouchDB needs to know how to exec Clutch’s view server. Getting this command string together can be tricky, especially given potential classpath complexity. You can either (a) produce an uberjar of your project, in which case the exec string will be something like:

java -cp <path to your uberjar> clojure.main -m com.ashafa.clutch.view-server

or, (b) you can use the com.ashafa.clutch.utils/view-server-exec-string function to dump a likely-to-work exec string. For example:

user=> (use '[com.ashafa.clutch.utils :only (view-server-exec-string)])
nil
user=> (println (view-server-exec-string))
java -cp "clutch/src:clutch/test:clutch/classes:clutch/resources:clutch/lib/clojure-1.3.0-beta1.jar:clutch/lib/clojure-contrib-1.2.0.jar:clutch/lib/data.json-0.1.1.jar:clutch/lib/tools.logging-0.1.2.jar" clojure.main -m com.ashafa.clutch.view-server

This function assumes that java is on CouchDB’s PATH, and it’s entirely possible that the classpath might not be quite right (esp. on Windows — the above only tested on OS X and Linux so far). In any case, you can test whether the view server exec string is working properly by trying it yourself and attempting to get it to echo back a log message:

[catapult:~/dev/clutch] chas% java -cp "clutch/src:clutch/test:clutch/classes:clutch/resources:clutch/lib/clojure-1.3.0-beta1.jar:clutch/lib/clojure-contrib-1.2.0.jar:clutch/lib/data.json-0.1.1.jar:clutch/lib/tools.logging-0.1.2.jar" clojure.main -m com.ashafa.clutch.view-server
["log" "echo, please"]
["log",["echo, please"]]

Enter the first JSON array, and hit return; the view server should immediately reply with the second JSON array. Anything else, and your exec string is flawed, or something else is wrong.

Once you have a working exec string, you can use Clojure for views and filters by adding a view server configuration to CouchDB. This can be as easy as passing the exec string to the com.ashafa.clutch/configure-view-server function:

(configure-view-server (view-server-exec-string))

Alternatively, use Futon to add the clojure query server language to your CouchDB instance’s config.

In the end, both of these methods add the exec string you provide it to the ‘local.ini’ file of your CouchDB installation, which you can modify directly if you like (this is likely what you’ll need to do for non-local/production CouchDB instances):

  [query_servers]
  clojure = java -cp …rest of your exec string…

Appreciations go out to:

• Chas Emerick
• Pierre Larochelle
• Matt Wilson
• Patrick Sullivan
• Toni Batchelli
• Hugo Duncan
• Ryan Senior