Why CouchDB and Cloudant?
After playing around with a little project that required a lot of “document” retrieval from a database, I decided to try one of the hosted NoSQL options that are out there. I decided to try Cloudant, a cloud-based CouchDB host that has add-ons for both Heroku and AppHarbor.
Why Cloudant? I was looking for something in the cloud, free and not constrained by too much of a size issue. The choice between MongoDB and CouchDB came down to what would be less of a hassle. Cloudant is officially supported by AppHarbor, so that was my ultimate choice. At this point, you should create yourself a free Cloudant account.
Interacting with the Database
It is very easy to interact with the database as CouchDB is REST based, so standard HTTP calls can be made to perform CRUD operations. Divan is a popular .NET wrapper that will be used instead of hand crafting the calls to the CouchDB server. To get started, a reference to the Divan project will be needed in the website project.
- From Visual Studio 2010, choose “File” -> “Add” -> “Existing Project” from the menu bar.
- In the “Add Existing Project” dialog box navigate to the location of the Divan “src” folder and open Divan.csproj.
- Upgrade the Divan project to .NET Framework 4.0 by right-clicking on the Divan project in Solution Explorer and choosing Properties. From here change the “Application” tab’s “Target Framework” option from .NET Framework 3.5 to .NET Framework 4.0.
- Remove the Newtonsoft.Json reference under the “References” folder because we will need to upgrade the Json.NET reference from .NET 3.5 to .NET 4.0, so both our website project and Divan project are in sync. (This won’t be that important until Part 2)
- Using either the internet or NuGet to reference Json.NET 4.0.x (or later).
- In NuGet, this can be done by right-clicking on “References” and selecting “Manage NuGet Packages”.
- Select the “Online” tab and search for “Json.NET”.
- Once “Json.NET” is located. Select it from the list and click the “Install” button.
- Finally, right-click the website’s “References” and under “Projects” add the Divan project.
With project setup complete, it is now time to create and query a Cloudant database. In order to do this, a CouchServer object will be created to store the server connection information and perform a call to create/get a database. For this example, the trivial example of a database called “people” that stores “firstName” and “lastName” will be used. Ensure that the Divan namespace is resolved in the file that you are creating this code (right-click “Resolve” on the squiggly lines under CouchServer).
CouchServer server = new CouchServer("INSERTUSERNAME.cloudant.com", 5984, "INSERTUSERNAME", "INSERTPASSWORD");
ICouchDatabase database = server.GetDatabase("people");
In the above example, remember to insert your username and password. After digging in Cloudant’s FAQ, it can be found that Cloudant runs their servers on port 5984. The final interesting thing to note with the above code sample is that the GetDatabase call will create the database if a database with that name is not found on the server.
With the database in hand, it is time to create a document on the server and call it a day. CouchDB is Json based. Creation of documents can be done by specifying an object to be serialized or hand supplying the Json. For simplicity, the latter will be done.
ICouchDocument doc1 = database.CreateDocument("{\"firstName\": \"Scott\", \"lastName\": \"Heckel\"}");
ICouchDocument doc2 = database.GetDocument(doc1.Id);
All CouchDB documents have Id and Rev(ision) properties. These properties are used to identify specific documents. While the Id was supplied directly in the Json, CouchDB provided the Id for the document automatically. With the help of that Id, the program is able to retrieve the document that was just created.
A great start! Part 2 will show how to improve the code by creating custom objects that implement ICouchDocument.