Beginner’s Guide to PouchDB

PouchDB is an open source client-side database API written in JavaScript. It is modelled after CouchDB – a NoSQL database that runs within the browser.

If you are not familiar with NoSQL databases, let me give you a short introduction. NoSQL is a term used for high-performance, non-relational databases. It provides a mechanism for storage and retrieval of data other than tabular relations model used in relational databases. These databases utilize a variety of data models, including document, graph, key-value, and column store. Checkout the list of NoSQL databases here.

Using PouchDB API, we can build applications that work offline and online. It uses WebSQL and IndexedDB internally to store the data. It is framework-agnostic, so you can use it with Angular, React, Ember, Backbone, or your framework of choice.

PouchDB supports all the modern browsers. Some of them are Firefox 29+, Chrome 30+, Safari 5+, Internet Explorer 10+, Opera 21+ and so on.

As we know PouchDB can be used as a direct interface to CouchDB-compatible servers. So, let’s set up CouchDB.

Installing CouchDB

If you are using one of the Linux distributions, you can install using the following command.

$ sudo apt-get install couchdb

For Windows, download and install from CouchDB site.

In case of Mac, you can run the following command in the terminal.

$ brew install couchdb

Once it is installed, you can open http://127.0.0.1:5984/ or http://localhost:5984/ in the browser. The response should be something as follows:

{"couchdb":"Welcome","version":"1.6.1", .. }

When you open http://127.0.0.1:5984/_utils/index.html and you will see a screen as follows.

Screen Shot 2017-09-02 at 16.35.58

Note: On Mac, if you do not get any response when you open http://127.0.0.1:5984/ in the browser, verify if couchdb service is running using the command:

$ curl http://127.0.0.1:5984/

If you get the following response, usually the service will not be running.

curl: (7) Failed to connect to 127.0.0.1 port 5984: Connection refused    

In that case, run the following command to start the service.

$ couchdb

Setting up CORS

To create a PouchDB database in a remote CouchDB server, we will need to enable CORS in CouchDB.

Install CORS using the following script.

$ npm install -g add-cors-to-couchdb

Then run the script:

$ add-cors-to-couchdb

Installing PouchDB

Download the latest pouchdb-6.3.4.min.js from their website and include in index.html as follows:

< script src="pouchdb-6.3.4.min.js">< /script>

If you are using Node.js, you can run the command:

$ npm install pouchdb

Refer this documentation for other various ways to install PouchDB.

Creating a Database

To create a local database in PouchDB using node, we can simply write the following code snippet and save it as index.js.

//Requiring PouchDB module

let pouchDB = require("PouchDB");

//Creating the database object

let db = new PouchDB("techshard");

console.log ("Database created Successfully.");

Then run the command as follows:

$ node index.js

Screen Shot 2017-09-02 at 16.49.46

To create a remote database, you will need to provide remote server URL.

//Requiring the package

let PouchDB = require("PouchDB");

//Creating the database object

let db = new PouchDB("http://127.0.0.1:5984/techshard");

db.info().then(function (info) {

  console.log(info);

});

Here, the remote database will not be created until we do an API call db.info(). Once you run the above JavaScript, you should be able to view the info as follows:

Screen Shot 2017-09-02 at 17.53.37

We can also view the information by opening http://127.0.0.1:5984/techshard in the browser.

So far, we learned how to install and setup PouchDB. Let’s look at some database operations.

Storing and reading a document

Since PouchDB is a NoSQL database, we store unstructured documents. For example:

let doc = {

   _id : '01',

   name: 'John Doe',

   age : 24,

   designation : 'Developer'

 }; 

db.put(doc);

This will store the document in database. To read the same document, we can write as follows:

db.get('01').then(function (doc) {

  console.log(doc);

});

Here ‘01’ is an _id of the document.

We will see the following output in the console.

{ 

_id: '01',

  _rev: '1-7624dcaea7247ee0c6e280f8482d4ee7',

  name: 'John Doe',

  age: 24,

  designation: 'Developer'

}

Here, the new field _rev is the revision marker. It is a randomly-generated ID that changes whenever a document is created or updated.

Deleting a document

For deletion, we can simply fetch the document and delete the returned document.

db.get('01').then(function (doc) {  

return db.remove(doc);

});

There are other ways to delete a document in PouchDB API, please refer this documentation for the same.

Wrapping up

PouchDB has a lot more powerful features. If you are interested in learning in depth, check out their official site for a detailed documentation and API reference. I hope this article has sparked your interest in PouchDB. Let me know in the comments, if you already have experience with CouchDB or PouchDB.

2 thoughts on “Beginner’s Guide to PouchDB

Comments are closed.