Table of Contents

There are many ways to use CouchDB, and many areas of application. As a lowest common denominator, we’ll be exploring the API with a simple Web application using plain old HTML and JavaScript. The lessons we learn should apply to usage from Django or Rails style application servers and even to data mining tasks. The CouchDB API is the same, regardless of whether you’re running a small installation or an industrial cluster.

There is no right answer about which application development framework you should use with Couch. We’ve seen successful applications in almost every commonly used language and framework. The ubiquity of JSON and HTTP are due in larger part to the browser. We can also assume that all of you have a browser at hand. In this section we get right to the heart of the CouchDB database API, by using it in a running application.

This section is interactive, so be prepared to work with your laptop, and a running CouchDB database, alongside the book. We’ve made the full example application and all of the source code examples available online, so if you don’t feel like doing all the typing you can skip directly to each stage of development.

If you’re not familiar with JavaScript, we hope the source examples are given with enough context and explanation so that you can keep up. If you are familiar with JavaScript, you’re probably already excited that CouchDB supports view and template rendering JavaScript functions.

One of the advantages to building applications that can be hosted on any standard CouchDB installation, is that they are portable via replication. This means that your application, if you develop it to be served directly from CouchDB, gets offline mode "for free". Local data makes a big difference for users, in a number of ways which we won’t get into here. We call applications that can be hosted from a standard CouchDB, CouchApps.

CouchApps are a great vehicle for teaching CouchDB because we don’t need to worry about picking a language or framework, we’ll just work directly with CouchDB, so that readers get a quick overview of a familiar application pattern. Once you’ve worked through the example app you’ll have seen enough to know how to apply CouchDB to your problem domain. If you don’t know much about Ajax development you’ll learn a little about jQuery as well, we hope you find the experience relaxing.

Application Modeling

Applications are stored as design documents. You can replicate design documents just like everything else in CouchDB. Because design documents can be replicated, whole CouchApps are replicated. CouchApps can be updated via replication, but they are also easily "forked" by the users, who can alter the source code at will.

Note

Thinking of peer-based application replication takes me back to high school. As freshman, my friends and I would share little programs between the TI-85 graphing calculators we were required to own. Two calculators could be connected via a small cable and we’d share physics cheat sheets, Hangman, some text-based adventures, and at the height of our powers, I believe there may have been a Doom clone running.

The TI-85 programs were in Basic, so everyone was always hacking each others hacks. Perhaps the most ridiculous program was a version of Spy Hunter that you controlled with your mind. The idea was that you could influence the pseudo random number generator by concentrating hard enough, and thereby control the game. Didn’t work. Anyway, the point is that when you give people access to the source code, there’s no telling what might happen.

Chris blogged: http://jchrisa.net/drl/_design/sofa/_show/post/standalone_applications_with_co

If one person doesn’t like the æsthetics of your application, she can tweak the CSS. If she doesn’t agree with your interface choices, she can improve the HTML. If she wants to modify the functionality, she can edit the JavaScript. Taken to the extreme, she may want to completely fork your application for her own purposes. When she shows the modified version to her friends and co-workers, and hopefully you, there is a chance that more people may want to make improvements.

As the original developer, you have the control over your version and you can accept or reject changes as you see fit. If someone messes about with the source code for a local application and breaks things beyond repair they can replicate the original copy from your server.

Of course, this may not be your cup of tea. Don’t worry, you can be as restrictive as you like with CouchDB. You can restrict access to data however you wish, but beware of the opportunities you might be missing. There is a middle ground between open collaboration and restricted access controls.

Once you’ve finished the installation procedure, you’ll be able to see the full application code for Sofa, both in your text editor, and as a design document in Futon.

Standalone

In the previous chapters we saw that CouchDB is adept and handling a wide range of data. The schemaless documents help CouchDB adapt to all sorts of situations. Yet despite all of this, there’s still one thing JSON isn’t very good with. Binary data. Sure, you can encode images, or music, or video with something like base64 and shove this into one of your documents using a string. Unfortunately, base64 data is usually 137% the size of the original data and CouchDB does not “stream” documents, each document is read into memory first and then sent to the client. Unless you have a lot of disk space, a lot of memory, and a lot of bandwidth, don’t go there — it’s not worth it.

What happens if you add a HTML file as a document attachment? Exactly the same thing. We can serve Web pages directly with CouchDB. Of course, we might also need images, stylesheets, or scripts. No problem, just add these resources as document attachments and link to them using relative URIs.

Let’s take a step back. What do we have so far? A way to serve HTML documents and other static files on the Web. That means that we can build and serve traditional Web sites using CouchDB. Fantastic! Right? Isn’t this a little like reinventing the wheel? Well, a very important difference is that we also have a document database sitting in the background. We can talk to this database using the JavaScript served up with our Web pages. Now we’re really cooking with gas!

CouchDB’s features are a foundation for building standalone Web application backed by a powerful database. As a proof of concept, look no further than CouchDB’s built-in administrative interface. Futon is a fully functional database management application built using HTML, CSS, and JavaScript. Nothing else. CouchDB and Web applications go hand in hand.

To see Sofa in action, visit http://jchrisa.net which has been running Sofa since late 2008.

Wrapping Up

Chris decided to port his blog from Ruby on Rails to CouchDB. He started by exporting Rails ActiveRecord objects as JSON documents, paring away some features and adding others, as he converted to HTML and JavaScript.

The resulting blog engine features access controlled posting, open comments with the possibility of moderation, Atom feeds, Markdown formatting, and a few other little goodies. This book is not about jQuery, so while we use this JavaScript library, we’ll refrain from dwelling on it. Readers familiar with using asynchronous XMLHttpRequest (XHR) should feel right at home with the code. Keep in mind that the figures and code samples in this section elide many of the bookkeeping details.

We will be studying this application and learning how it exercises all the core features of CouchDB. The skills learnt in this section should be broadly applicable to any CouchDB application domain, whether you intend to build a self hosted CouchApp or not.