Since we are considering using CouchDB for data storage on our apps backend (and possibly on the frontend as well) I cooked this small intro.
Some facts about CouchDB that you should know:
- CouchDB is a JSON document-oriented database written in Erlang.
- It is a highly concurrent database designed to be easily replicable, horizontally, across numerous devices and be fault tolerant.
- It is an open source Apache foundation project.
- It allows applications to store JSON documents via its RESTful interface.
- It makes use of map/reduce to index and query the database.
Main Benefits of CouchDB
- JSON Documents – Everything stored in CouchDB boils down to a JSON document.
- RESTful Interface – From creation to replication to data insertion, every management and data task in CouchDB can be done via HTTP.
- N-Master Replication – You can make use of an unlimited amount of ‘masters’, making for some very interesting replication topologies.
- Built for Offline – CouchDB can replicate to devices (like Android phones) that can go offline and handle data sync for you when the device is back online.
- Replication Filters – You can filter precisely the data you wish to replicate to different nodes.
Taking CouchDB out for a ride
The easiest way to test CouchDB is to use one of the many services on the cloud, I’m assuming for the rest of the document that we use http://www.iriscouch.com, its free (for small users) and takes seconds to set up.
Feel the Futon
Users in CouchDB
Be advised! CouchDB, by default, is completely open, giving every user admin rights. This is great for development but obviously bad for production. In the bottom right, you will see “Welcome to Admin Party! Everyone is admin! Fix this”.
Go ahead and click fix this and give yourself a username and password. This creates an admin account and gives anonymous users access to read and write operations on all the databases, but no configuration privileges.
Users are just JSON documents like everything else so you can store any additional attributes you wish like email for example. You can then use groups within CouchDB to control what documents each user has write access to.
Creating a Document
Now we’re going to create our first document using Futon:
- Open the mydb database.
- Click “New Document”.
- Click “Add Field” to begin adding data to the document. Notice how an ID is completed out for you, you should not change this unless you know exactly what you´re doing (and the chances are that you don’t if you’re reading this). Add key “game” with the value of “Nextive CouchDB Tutorial”.
- Make sure you click the green tick next to each attribute to save it.
- Click “Save Document”.
Updating a Document
CouchDB is an append only database — that means that new updates are appended to the database and do not overwrite the old version. Each new update to a JSON document with a pre-existing ID will add a new revision. This is what the automatically inserted revision key signifies. Follow the steps below to see this in action:
- Viewing the contents of the mydb database, click the only record visible.
- Add another attribute with the key “type” and the value “game”.
- Hit “Save Document”.
Creating a Document Using cURL
I mentioned earlier that CouchDB uses a RESTful interface, let’s prove this by inserting a document using cURL via the Terminal.
First, let’s create a JSON document with the below contents and save it to the desktop calling the file person.json.
{
“name”: “Bruce”,
“surname”: ”Wayne”,
“type”: ”person”
}
Next, open the terminal in the Desktop then perform the insert with:
curl -X POST http://mysubdomain.iriscouch.com/mydb -d @person.json -H “Content-Type: application/json”
CouchDB should have returned a JSON document similar to the one below.
{”ok”:true,”id”:”259191a3020fd260d1bb66cf17594757″,”rev”:”1-f62208cb5761dd5c7d1c5954dfba0e7a”}
This is the ID and revision number of the inserted document.
CouchDB follows the RESTful convention so:
- POST – creates a new record
- GET – reads records
- PUT – updates a record
- DELETE – deletes a record
Viewing All Documents
We can further verify our insert by viewing all the documents in our mydb database by executing curl -X GET http://mysubdomain.iriscouch.com/mydb/_all_docs
Creating a Map Function
Viewing all documents is nice, but fairly useless in itself. What if we only want to show all game documents?. Follow the steps below to produce the magic:
- Within Futon, click on the view drop down and select “Temporary View”.
- This is the map reduce editor within Futon. Copy the code below into the map function.
function (doc) {
if (doc.type === “game” && doc.game) {
emit(doc.game, doc);
}
}
- Click run and you should see (if you didn’t mess up) the single game we added previously.
- Go ahead and make this view permanent by saving it.
curl -X GET http://mysubdomain.iriscouch.com/mydb/_design/games/_view/games
Notice that we get the document’s ID and revision by default.
Reduce Fat Fast
function (doc) {
if (doc.type === “game” && doc.users) {
emit(doc.id, doc.users);
}
}
The above map function simply checks to see if the inputted document is a game and that it has users. If these conditions have been met, the game users is emitted. Next, the reduce function:
function (keys, users) {
return sum(users);
}
It takes the users count and returns the sum using one of CouchDB’s built in reduce functions. Make sure you check the reduce option in the top right of the results table as you may otherwise be unable to see the results of the reduce. You need to save the view first to see the results of the reduce.
Conclusion
In this article, we took a brief look at CouchDB, one of the more mature NoSQL database available today. Even the most fervent SQL believer can see the advantages that this type of database offers, especially for high demand write operations.
