Introduction to CouchDB with .NET part 2: Fauxton UI basics

Introduction

In the previous post we laid the foundations for this series. We’ll discuss the basics of the NoSql document-based data store CouchDB. CouchDB stores its records in documents as JSON which makes integration with clients relatively easy. CouchDB comes with a web-based administrative UI that allows us to create databases, check their content, create users, administrators and many other things that we’ll eventually cover in this series. CouchDB is completely schemaless, has no data integrity checks and its JSON storage format allows us to store our domain objects in a more natural way than table-based relational databases do.

We successfully installed CouchDB on Windows. It was a straightforward and painless experience. The installer also set up a Windows Service so that the CouchDB server is up and running all the time. We had to solve one issue though after the initial setup: 3 administrative databases were not installed and we had to create them in the UI. In the absence of those tables the CouchDB server keeps logging the same exception message in the log file.

In this post we’ll be looking into various basic functions in the CouchDB management UI called Fauxton.

Creating databases and documents

We saw a glimpse of the CouchDB management UI called Fauxton. It can be accessed on localhost:5984/_utils/ on the local machine. We’ve also seen how to create a database. Note that Fauxton is a new project and is still under development. Some features that the earlier UI tool Futon had had not yet been implemented.

We’ll first continue to explore the Databases section. Click on the Databases node and you should see the 3 databases we created before. Let’s now create a database for our demo purposes. Click on the Create Database button and add a database called “customers”. On the next screen click on the + sign to the right of All Documents and click on New Doc:

This leads to a JSON editor with a predefined _id property. _id is populated by a unique ID such as “77802a7eaffab7458a00f1f6cf00027c”. It can be overwritten but the ID must be unique within a database. I will leave it untouched and create the following customer JSON object:

{
  "_id": "77802a7eaffab7458a00f1f6cf00027c",
  "name": "Great customer Inc",
  "preferred": true,
  "address": {
    "street": "Victory avenue",
    "city": "New York",
    "country": "USA"
  },
  "telephone": {
    "office": "34543534",
    "sales": "576545645",
    "customer_care": "456456567"
  },
  "year_joined": 2016
}

Press the green Create Document button. If nothing seems to happen then there’s most likely something wrong with the JSON format. Unfortunately the Fauxton UI doesn’t show any alerts. You can always use an online JSON validator such as JSONLint. If the JSON is valid then you’ll be redirected to the customers collection:

The above example shows how we can take advantage of the flexible nature of JSON and include nested objects like address and telephone.

Take note of the _rev property. It stands for “revision” and its value starts with an integer followed by an identifier. The first integer stands for the revision number. In our case we have the first revision of this customer document. CouchDB keeps the revisions of the documents so we can always revert to a previous version if necessary. Revisions are kept until a process called “compaction” is performed on the database. It’s mostly a task for database admins and we’ll take a look at it later on.

Note that this screen only shows the various ID fields of the document at first. You can select the Include Docs option to see more:

You can also check out the JSON and Table view options to the left of Include Docs. They toggle the two views available for documents: JSON or tabular format.

Let’s now update the document using the pencil icon:

I’ll add a new address property called “postal_code” and set its value to 11111. I’ll also update the year_joined property to 2015. Save the document and you’ll see that the revision number jumped up to 2:

That’s great so where is revision 1? One missing feature of Fauxton is the ability to view revisions of a document. There’s a JIRA issue related to this with priority major. So currently we can only view revisions using the CouchDB HTTP API which we’ll look at in the upcoming posts.

The schemaless nature of CouchDB enables us to add documents of completely different structure to the same database. There’s nothing that prevents us from adding the following JSON document to the customers database:

{
  "_id": "0c458e911e3ff5b4e423bfe06c00098f",
  "some_key": "some value"
}

However, we’ll probably not want to mix unrelated objects in the same database. If we want to extract all customers from the database then we’re expecting to see only customer objects returned, right? Databases being schemaless proves more useful when we’re extending a domain. Domain objects are usually not rigid entities and they can get new properties after their first incarnation. The customer domain may look like in the first JSON example above but with time it can be extended with new properties like here:

{
  "_id": "0c458e911e3ff5b4e423bfe06c00133c",
  "name": "New customer Inc",
  "preferred": false,
  "address": {
    "street": "New street",
    "city": "Birmingham",
    "country": "UK",
    "postal_code": 22222
  },
  "telephone": {
    "office": "34543534",
    "sales": "576545645",
    "customer_care": "456456567"
  },
  "year_joined": 2017,
  "current_status": "approved"
}

A new property “current_status” was added to this customer. We didn’t have to update any database table. The client will of course need to handle the documents that don’t have this property in some way, such as a default value.

Deleting a document in Fauxton is easy. Just select a document and press the delete icon:

Other functions in Fauxton

Let’s quickly review the other options available in Fauxton. We’ll look at some of them in upcoming posts, there’s no point of providing details on every single one of them in this intro post. The following goes through the menu items on the left hand side:

Also, most of these options are meant for database administrators whereas this series is more directed at developers who want to create databases and documents and query them.

• Setup: configure a cluster with new nodes or a single node with security credentials
• Active tasks: CouchDB can perform various repeated tasks with specific time intervals. A typical repeated activity is database compaction or data replication.
• Configuration: view the current configuration values extracted from default.ini and local.ini that we saw previously. We can also add new sections, keys and values and update them by double-clicking on an entry. Note that the CouchDB server process must be restarted for the updated setting to take effect.
• Replication: replicate data from one node to another
• Documentation: a collection of links for further documentation
• Admin party: create new admin users
• Verify: run the verification steps and check if the CouchDB installation is healthy. This is very useful even for developers who may suspect that a specific CouchDB node is misbehaving.

In addition to the above Fauxton provides other features at the database level:

• All documents: we’ve seen its “New Doc” feature in action above. The + icon opens a gateway to creating views for our searches and indexes for our Mango queries. We’ll look at views and Mango in later posts.
• Run a query with Mango: we can run Mango-index based queries here. Mango features a JSON query syntax which will look familiar for MongoDB users. MongoDB queries rely heavily on JSON and certain keywords for selectors such as $gt for greater-than and Mango follows a very similar setup.
• Permissions: define the users and roles with admin and member access for a database
• Changes: view the changes made to the selected database
• Design documents: these are documents with application code inside. It is possible to assign a function to the JSON properties in a document. Instead of just having a simple key-value like “name”:
  “john” we can assign a JavaScript function to a key like “age” : “function(yearOfBirth){return…}”. We’ll take a look at design documents as well later on.

There’s one further feature I want to mention before closing this post. We can upload documents associated with a document. Say that a customer has a PDF or text file attached or a person domain has a photo. We can upload documents when creating or updating a document:

Here’s what an attached document in JSON will look like:

 "_attachments": {
    "Some image name.PNG": {
      "content_type": "image/png",
      "revpos": 4,
      "digest": "md5-zHrwohh+oRdL29TExyrhrA==",
      "length": 33926,
      "stub": true
    }
  }

We’ll continue in the next post with the basics of the HTTP API.

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