Introduction to Apache CouchDB using Python

TK Kaushik Jegannathan 23 Jul, 2022 • 6 min read

This article was published as a part of the Data Science Blogathon.

Introduction

Apache CouchDB is an open-source, document-based NoSQL database developed by Apache Software Foundation and used by big companies like Apple, GenCorp Technologies, and Wells Fargo. CouchDB is similar to MongoDB and uses JSON, also known as Javascript Object Notation, to store data, while MongoDB stores data using BSON, which stands for Binary Javascript Object Notation.

CouchDB is powerful yet simpler when compared to MongoDB, which makes it a good option for beginners to learn and use. The update mechanism of CouchDB is optimistic and lockless. It implements multi-version concurrency control to ensure that there is no need to lock the database fields while performing writes. CouchDB can easily scale and provides an in-built, easy-to-use replication mechanism to synchronize data in databases across multiple machines. CouchDB, irrespective of being a document-based NoSQL database, follows ACID properties where A stands for Atomicity, C stands for Consistency, I stands for Isolation, and D stands for Durability. To read more about ACID properties, refer to this article.

couchdb
Source: Analytics Vidhya – Understanding Transaction Management in SQL

This article will teach us how to run CouchDB locally and perform basic CRUD operations using python. To run CouchDB locally, you could either install it from their official website or could run it on a docker container. I will be explaining the latter in detail.

Installing and Running CouchDB using Docker

The first step is to install Docker on your Windows machine. You can download Docker Desktop from here. The installation process is fairly simple and direct. Now that we have Docker on our machine, we will try to fetch the official image of CouchDB from Docker Hub. You can view the official CouchDB image here. To fetch the CouchDB image, run the following command on a command prompt.

$ docker pull couchdb

Once this is done, the final step is to spin up a container using the CouchDB image that we just downloaded from Docker Hub.

couchdb

Run the following docker command to start a container using the CouchDB image.

$ docker run -p 5984:5984 -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password -d couchdb

The -p tag is used to expose a local port connecting to the container’s port, which is 5984, as it is the default port for CouchDB. Specifying the user and password credentials when creating the container post CouchDB version 3 is mandatory; we will be using the default credentials.

couchdb

We can see that the Couchdb container is up and running. Now let’s shift our focus to the coding part.

Installing CouchDB client for Python

We will be installing the CouchDB python module, which is a CouchDB client for python. It can be installed like any other python module using pip.

$ pip install couchdb

Now that we have everything ready let’s get our hands dirty and deep-dive into the programming part.

Performing CRUD operations on CouchDB

Before performing any CRUD operations, we must first connect to the local CouchDB database. If you are running CouchDB version 3 or higher, it is important to specify the user credentials in the URL while connecting to the database.

import couchdb
server = couchdb.Server('http://admin:[email protected]:5984/') # connect to local server
server
<Server 'http://127.0.0.1:5984/'>

Now that we have connected to the database let’s first look at database operations.

To create a new database, we use the “create()” function, which accepts the name of the database to be created. The code below creates a database named “sample_database.”

db = server.create('sample_database') # creating a database

To use an existing database, we can directly access it using the server object by considering it like a dictionary object and specifying the database name in place of the key. Let’s try to access the above-created database using the server object.

server['sample_database'] # accessing an existing database

We can use the del command available in python to delete an existing database. It is just like accessing an existing database but with the “del” keyword prepended to it.

del server['sample_database'] # deleting a database

Now that we have understood how to create, use, and delete a database, let’s look at how CRUD operations can be performed. Let’s first create a database named “employee_info.”

db = server.create('employee-info')

It is time to insert a document into the database we just created. Let us insert some documents containing the details of an employee, including their name, age, country, and programming languages they know. New documents can be inserted into a database using the “save” command, which takes in the dictionary object as an argument and returns a unique document id and the revision number.

# inserting documents
db = server['employee-info']
employee_details_1 = {
    'name': 'Vishnu',
    'age': 22,
    'country': 'India',
    'programming_languages': ['python', 'C++', 'C#']
}
employee_details_2 = {
    'name': 'Sanjay',
    'age': 21,
    'country': 'India',
    'programming_languages': ['C++', 'C#', 'javascript']
}
employee_details_3 = {
    'name': 'Arjun',
    'age': 30,
    'country': 'Germany',
    'programming_languages': ['python', 'nodejs']
}
doc_id, doc_rev = db.save(employee_details_1)
db.save(employee_details_2)
db.save(employee_details_3)
doc_id, doc_rev
('0bba8f74f5974cb204d4270e6d000c14', '1-54ad9527cac88effa0545271cf3acb11')

Now that we have inserted a document into the database let’s try to fetch a document. Documents can be fetched from a database using their document id that is returned when the document is inserted into the database.

doc = db['0bba8f74f5974cb204d4270e6d000c14'] # fetching documents
doc['name']
'Vishnu'

Apart from fetching documents using their unique document id, to use search queries in CouchDB, we use something called mango queries that are similar to mongo queries. Let’s see a couple of examples to see this in action. Let’s try to search for all employees whose age is above 23.

mango = {'selector': {'age': {'$gt':23}}}
for i in db.find(mango): print(i)

If you are familiar with mongo queries, the same query will work fine for MongoDB. As mentioned earlier, mango queries are very similar to mongo queries, and people with MongoDB knowledge can easily use CouchDB without any hassle. Now let’s try to find the employee whose name is “Sanjay,” but the catch is that we want only his name and age information instead of all the data.

mango = {'selector': {'name':'Sanjay'}, 'fields': ['name', 'age']}
for i in db.find(mango): print(i)

Just like the fields parameter, the find function also accepts a key called “sort” that can be used to sort the result of the queries.

Now let’s try to add a new record with a specific document id and then try to modify its data once it is created and saved to the database. We will create a new employee named ‘John’ and push it to the database. While saving it, we will use his name as the document id to store. Once that is done, we will try to modify his age and save it back to the database with the same document id.

db['John'] = {
    'name': 'John',
    'age': 36,
    'country': 'USA',
    'programming_languages': ['java']
}
db['John']
data = db['John']
data['age'] = 40 # updating the age
db['John'] = data
db['John']

Now that we have seen the create, read, and update operations, let’s move to the delete operation. To delete a document, we make use of the “delete()” function that accepts the document to be deleted as an argument. Let’s try to delete the John document we just created.

db.delete(db['John'])

Conclusion

Some of the key takeaways are:

  • Understanding what CouchDB is
  • Understanding how to host a local CouchDB instance using Docker
  • Learning how to perform basic database operations on CouchDB using python
  • Learning how to perform basic CRUD operations on CouchDB using python

The functions described in this article are good enough for getting started with CouchDB, but this is not the end. The CouchDB python client is pretty vast and has been well documented. You can refer to their documentation for further understanding. If you wish to learn more about other NoSQL databases, please check out Google Firestore, which is arguably one of the best document-based production-ready NoSQL databases. You can refer to my article to get started with Google Firestore.

That’s it for this article. I hope you enjoyed reading this article and learned something new. Thanks for reading, and happy learning!

The media shown in this article is not owned by Analytics Vidhya and is used at the Author’s discretion.

Frequently Asked Questions

Lorem ipsum dolor sit amet, consectetur adipiscing elit,

Responses From Readers

Clear

julio
julio 07 Feb, 2023

I hope you enjoyed reading this article and learned something new. Thanks for reading, and happy learning!

Related Courses