Introduction to CouchDB with .NET part 1: foundations and setup

Introduction

CouchDB is a document based NoSql database by Apache written mostly in the Erlang programming language with C and C++ added in. It is also open-source and free-of-charge in both hobby and real-life commercial projects. If you’ve only worked with traditional relational databases like MS SQL with its tables, schemas, integrity checks, primary and secondary keys etc. then a document database will require a significant shift in the way you think of storing data. CouchDB shares a number of traits with MongoDB which is the most popular document based data store at this time. Both CouchDB and MongoDB store their data in documents, they don’t have any strictly enforced schema and no strict data integrity by way of secondary keys. They can both store our domain objects “as they are”, without the need of designing tables for them. In other words CouchDB represents our domain objects much closer than table-based relational databases can do. CouchDB and MongoDB can run on both Linux and Windows. Also, they can be clustered with in a master-slave setup with a primary database serves as the read/write node and the secondary databases all share the read-load. The master is then responsible for replicating data modifications such as inserts, updates and deletes to the secondary nodes.

CouchDB comes with a built-in management tool where we can view our databases and documents, edit them, delete them and perform a range of other administrative tasks. Relational databases are still the norm and the primary choice among developers for the data storage needs for their projects. However, it’s always good to know that there are alternatives that offer alternative ways of storing data. Both CouchDB and MongoDB provide fast read and write operations. CouchDB offers a REST API based query interface with the usual HTTP verbs like GET, PUT, DELETE etc. Querying can be performed with either predefined views or a new query language called Mango that was added to CouchDB 2.0.

In this series we’ll be looking at the basics of CouchDB, how to set it up on Windows, how to insert data, how to execute queries and finally how to communicate with a CouchDB database from your .NET project.

By the way, if you’re interested in MongoDB then this blog has two series dedicated to it:

• MongoDb original series
• MongoDb more updated series

CouchDB and MongoDB are often compared and contrasted. There are many threads devoted to their pros and cons, here are some excellent sources:

• Thread on Quora with very good answers
• MongoDB, CouchDB or Redis?
• CouchDB vs MongoDB on ScottLogic blog

The second link mentions Redis. If you don’t know Redis then it’s also a NoSql database but not a document-based one. It is a key-value store which is another category within the NoSql landscape. People often mistakenly view it as only a cache engine but it’s really more than that. I have an introductory series about Redis with .NET starting here if you’re interested.

Installation on Windows

I am going to run the installation and all subsequent demos on a Windows 10 PC. The current version of CouchDB is 2.0.0. There might be an update by the time you read this series but hopefully this material will still be valid. Go to the CouchDB homepage and click on the big red download icon:

Then click on the Windows installation link:

It will download an MSI installer. Run the installer. Pay attention to the warning in the installation screen after accepting the terms and conditions:

The installer will by default select the C:\CouchDB\ folder as the root for CouchDB. That should be just fine, I won’t change it. Then let the installer do its work, it will be very fast.

The installer performed two actions. First, it has created the CouchDB related files and folders in the designated root, i.e. C:\CouchDB by default:

Second, it has also installed a Windows Service so that the CouchDB database is always up and running. If you open the Services window then CouchDB will be located there:

I think this is a nice feature as we don’t need to worry about starting the server process separately or installing the Windows service as a second step.

The most important files and folders in the CouchDB installation root are the following:

• The “data” folder: this is where your data will be stored
• The “etc” folder with two configuration files: default.ini and local.ini. Default.ini contains the default configuration settings for CouchDB. You can open it in a text editor such as Notepad++.
  It is a key-value properties file and many options are well documented. We can understand some of the settings already now like database_dir and bind_address with port. These latter two define the URL to access the database. Local.ini is also a configuration file in which the properties of default.ini can be overridden. CouchDB will first extract the properties from default.ini and then it proceeds with local.ini. If a property is overridden in local.ini then CouchDB takes that value as the “winner”. Hence it’s a good idea to keep default.ini intact and only change the settings in local.ini. Upon first installation only a single key “uuid” is overridden with a unique identifier. The first couple of lines of documentation of local.ini contain an important note: “unlike changes made to default.ini, this file won’t be overwritten on server upgrade”, hence your custom properties won’t be rewritten when CouchDB is upgraded to a newer version.
• The couchdb.log file in the var/log folder. As its name suggests this is the CouchDB log which contains various log messages from the database engine.

We can easily check if the CouchDB server is up and running. As hinted at by the bind_address and port properties we can navigate to http://localhost:5984 in a web browser and we should see a simple JSON response similar to the following:

{"couchdb":"Welcome","version":"2.0.0","vendor":{"name":"The Apache Software Foundation"}}

Now open the couchdb.log file in a text editor to see what a typical message format looks like. I’m not sure about you but my log file contains an increasing number of errors of the same type:

Error in process on node ‘couchdb@localhost’ with exit value: {database_does_not_exist,[{mem3_shards,load_shards_from_db,”_users”,[{file,”src/mem3_shards.erl”},{line,327}]},{mem3_shards,load_shards_from_disk,1,[{file,”src/mem3_shards.erl”},{line,315}]},{mem3_shards,load_shards_from_disk…

The same message is repeated at regular intervals. So a database called “_users” doesn’t exist and the CouchDB server logs an exception when it’s looking for it. A little research led me to the this documentation page: “When you run 2.0 as a single node, it doesn’t create system databases on startup. You have to do this manually:”

…followed by 3 commands using the curl utility. Each command creates a database: _users, _replicator and _global_changes. I don’t have curl installed on my PC but we need to solve this problem quickly. We don’t like exceptions in general and the log file just keeps growing. We have to jump ahead a little and create these 3 databases using the CouchDB administrative UI. Navigate to http://localhost:5984/_utils/ in the web browser. It opens a web page called Project Fauxton. Click on the Databases section:

Click on the Create Database option highlighted in the picture above and create a database called “_users”. Repeat the process for _replicator and _global_changes. We’ll have the following databases at the end of the process:

The error messages reported in the log file should stop now.

By the way, the UI tool as mentioned is called Fauxton. Earlier versions of CouchDB had a different UI called Futon which had similar functionality but a different UI. Therefore if you happen to come across an older CouchDB project then the _util node may open a different looking administrative UI. Then you’ll know that it’s Futon.

Alright, that was a quick start, we’ll continue in the next post.

You can view all posts related to data storage on this blog here.