CouchDB clients in Javascript

Apache CouchDB is an open source NoSQL document database that collects and stores data in JSON-based document formats. Since CouchDB makes use of HTTP protocol, therefore we can use any HTTP client to connect with CouchDB. However, there are some existing CouchDB client libraries that are very easy and convenience to use. Below I would like to share 3 libraries that I frequent use to connect with CouchDB.

---

1. Nano

The Offical Apache CouchDB library for Node.js.

Setup

npm install --save nano

Connect to CouchDB server

const nano = require('nano')('http://localhost:5984');

Create a new database

nano.db.create('blogs');

Use an existing database

const blogs = nano.db.use('blogs');

That's it, easy peasy.😎 Now we can perform some queries with blogs. nano underlying is making HTTP API calls to CouchDB service. Such operations are asynchronous, we can use either Promises or Callbacks to receive the asynchronous data back from the library.

Promises

blogs.get('post-A').then(response => {
  // succeeded
  console.info(response);
}).catch(err => {
  // failed
  console.error(err)
})
});

// OR

try {
  const response = await blogs.get('post-A')
  // succeeded
  console.log(response)
} catch (e) {
  // failed
  console.error(e)
}

Callbacks

blogs.get('post-A', (err, data) => {
  // errors are in 'err' & response is in 'data'
})

Nano even supports stream which mean we can proxy the whatever requests from CouchDB to the end user.

blogs.listAsStream()
  .on('error', (e) => console.error('error', e))
  .pipe(process.stdout)

Pros:

• Easy to use.
• CouchDB API compatible.
• Supports Stream.
• The vast majority of library calls return native Promises.
• Detailed TypeScript definitions are built in.
• Easy to debug as errors are proxied directly from CouchDB: if you know CouchDB you already know nano.

Cons:

• Cannot use in browser. Only Nodejs.

2. PouchDB

An open-source JavaScript database inspired by Apache CouchDB that is designed to run well within the browser. However, PouchDB also runs in Node.js and can be used as a direct interface to CouchDB-compatible servers. The API works the same in every environment, so you can spend less time worrying about browser differences, and more time writing clean, consistent code.

Setup

// For browser
npm install pouchdb-browser

// For Node
npm install pouchdb-node

PouchDB supports custom builds, meaning you can pick and choose the features of PouchDB that you want to use, potentially resulting in smaller bundle sizes and faster build times. Both pouchdb-browser and pouchdb-node contains the replication, HTTP, and map/reduce plugins. I personally prefer pick and choose the features of PouchDB I want instead of using pouchdb-browser or pouchdb-node.

For example:

const PouchDB = require('pouchdb-core')
  .plugin(require('pouchdb-adapter-http'))
  .plugin(require('pouchdb-mapreduce'))
  .plugin(require('pouchdb-replication'));

Connect to a CouchDB database

const blogs = new PouchDB('http://localhost:5984/blogs');

Create a new database

const blogs = new PouchDB('blogs');

Query

PouchDB also supports Promises and Callbacks

blogs.get('post-A').then(doc => {
  // handle doc
}).catch(err => {
  console.log(err);
});

// OR

try {
  const doc = await blogs.get('post-A');
} catch (err) {
  console.log(err);
}

blogs.get('post-A', function(err, doc) {
  if (err) { return console.log(err); }
  // handle doc
});

Pros:

• Easy to learn & use.
• Works in all modern browsers and Nodejs.
• Lightweight
• Support Offline
• Support Custom Builds / Plugins

Cons:

• Not fully support CouchDB API, one of the example is you cannot use CouchDB's update function via PouchDB.
• Official library doesn't come with Stream. However, since PouchDB supports custom builds, you still can do stream with external PouchDB projects.

There is a a list of known plugins, tools and projects can be used with PouchDB. You can find it here

3. Axios

If you are a javascript developer, you should probably already know about axios. It is a Promise based HTTP client for the browser and node.js.

Setup

npm install --save axios

Connect to CouchDB server

const couchdb = axios.create({
  baseURL: 'http://localhost:5984',
  timeout: 1000,
  headers: { 'X-Custom-Header': 'foobar'}
});

Create a new database

couchdb.put('/blogs').then(response => {
  // succeeded
}).catch(err => {
  // failed
});

// OR

try {
  const response = await couchdb.put('/blogs');
  console.info(response.data);
} catch (err) {
  console.error(err);
}

Query

couchdb.get('/blogs/post-A').then(response => {
  console.info(response.data);
}).catch(err => {
  console.error(err);
});

// OR

try {
  const response = await couchdb.get('/blogs/post-A');
  console.info(response.data);
} catch (err) {
  console.error(err);
}

Pros:

• Works in all modern browsers and Nodejs.
• Supports the Promise API
• Intercept request and response
• Transform request and response data
• Cancel requests
• Automatic transforms for JSON data

Cons:

• Codes are not as clean/minimal as PouchDB. In order to achieve minimal of code with axios, you will need to spend extra time to build your own factory functions on top of axios.

---

Thanks for Reading.

If you know any other interesting libraries that play well with CouchDB, please leave comments below to share with me. Thank you.☺