CouchDB & CouchApp Managing Design Documents

I’ve been working with CouchDB and I was never really happy with how I was managing/version controlling my design documents.  Luckily, I read about CouchApp — I had initially thought it was a tool for developing CouchDB hosted appilcations, but now know that it can be used to at a very basic level to make it easy to control my desgin documents.  Here are a few notes that might make it easy for others to get started; I’m still learning this tool, so this may not be the optimal procedure (also, I’m not using any of the advanced features of CouchApp [e.g. macros], but will in the future).

There are two ways of using CouchApp  to push design documents to CouchDb: 1.  Generating the design document from multiple files (preferred), and 2. Generating the views from a single JSON file.

Generating the Design Document from its Component Pieces

1. Install CouchDB & CouchApp – Both are easy to install and well documented, so need for any additional notes.
2. The directory structure used is used to hold the atomic pieces of the design document and should have a structure as follows:
   • {myapp} – app directory
   • {myapp}/{sampledesign} — design document name
   • {myapp}/{sampledesign}/views — directory that holds views
   • {myapp}/{sampledesign}/views/{viewname}/ — view name
   • {myapp}/{sampledesign}/views/{viewname}/map.js — map function
   • {myapp}/{sampledesign}/views/{viewname}/reduce.js — reduce function

   We create a directory for the application {myapp}, we  then create a directory to hold our design document {sampledesign}, and last we create a directory for our view {viewname}.  Each view must contain one map.js file, and can (optional) contain one reduce.js file.

3. In this example we’re only going to create a map function, so map.js should look like:

           //This is a simple function that doesn't do anything
           //useful, but will work on all CouchDB databases.
           function(doc) {
              emit(doc._id, doc);
           }

4. To generate the design document and push it into CouchDB: Go to the {myapp} directory run the following command (for this example assume: {myapp} = myapp and {sampledesing} = mydesigndoc ):

   couchapp push mydesigndoc http://127.0.0.1:5984/myapp

5. To view the generate design document you can go to  http://localhost:5984/_utils/document.html?myapp/_design/mydesigndoc#source (the following url is for a db named myapp with a design document named mydesigndoc)

And that’s all there is to it.  You can develop and version control the design documents.

Alternate: Generating the views from a single JSON file.

1. Install CouchDB & CouchApp – Both are easy to install and well documented, so need for any additional notes.
2. Create a directory to store the design documents: “myapp/_design”  (this directory can be anything)
3. Create a directory for each design document: “myapp/_desgin/design_document”
4. Inside the design document create a JSON file named views (views.json) : “myapp/_design/design_document/views.json”
5. The contents of thee view document should be a JSON document containing view objects with map and reduce functions. For example, see the code listing below we have the view test with a map function.  Note: This is a useless view, but it will work on any CouchDB database.

   {
      "views": {
          "test": {
           "map": "function(doc) {\n    emit(doc._id, doc);\n}\n"
          }
      }
   }

6. From the “_design” directory run the following command:

   couchapp push {desgin_document_dir} http://127.0.0.1:5984/{dbname}

   where {dbname} is the name of your db and {design_document_dir} is the name of the design document directory , so if my database was named: “myapp”  and the design document dir was named: “sampledesign” it would look like:

   couchapp push sampledesign http://127.0.0.1:5984/myapp

   Note: If you are unsure of what the view json structure is you can create your views using Futon which is installed at: http://localhost:5984/_utils/ by creating a temporary view, saving it, and then navigating to the design document it created.  http://localhost:5984/_utils/document.html?myapp/_design/sampledesign#source (the following url is for a db named myapp with a design document named sampledesign)

After following those steps you can easily push json documents to couchdb and use whatever version controll system that you’d like; however, there is a better way of laying out the files.

So there you have it, a quick introduction to the two ways of using CouchApp to manage CouchDB Documents.