PouchDB, the In-Browser Database That Replicates

By Max Thayer

PouchDB is a JavaScript package that runs either in the browser or in a Node.js environment, and acts like its own little Cloudant instance, so you can write data to it even if you're not online, and sync data between it and remote Cloudant instances.

That means you can run a PouchDB instance on your server or in a user's browser, sync it with a Cloudant database, and then access that data right from the server, without needing to ping Cloudant on every request. This lets you use PouchDB like a caching layer, but it gets better:

  1. Any changes to your PouchDB instance get propagated back to Cloudant when you have Internet access.
  2. If you don't have Internet access, you can still access your PouchDB instance.
  3. When Internet access is restored, PouchDB will bring your instance and Cloudant back into sync.

Using PouchDB to sync with Cloudant on the server lets you serve data without needing to ping Cloudant on every request, while using it on the client gives you offline functionality: even if your users are, say, on a train and they lose connection, they can still use your app uninterrupted.

Getting PouchDB

To install PouchDB on your Node.js server:

npm install pouchdb

Then, import it in your code with this:

var PouchDB = require('pouchdb');

If you want to use PouchDB in client-side JavaScript, put this inside your HTML's <head> tag:

<script type="text/javascript" src="http://download.pouchdb.com/pouchdb-nightly.min.js"></script>

Using PouchDB

Let's see it in action by connecting and syncing. Then, do this in your JavaScript:

var db = new PouchDB('dbname'),
    remote = 'https://USERNAME:PASSWORD@USERNAME.cloudant.com/DATABASE',
    opts = {
      continuous: true
    };

db.replicate.to(remote, opts);
db.replicate.from(remote, opts);

Now your PouchDB instance is proactively syncing with your Cloudant database: when either changes, they'll push those changes to each other.

PouchDB also acts as a fully-capable interface to Cloudant, like Nano or Cradle, so you can use it to get and insert documents, perform queries, etc.:

// create a document; log the response
db.post({
  name: 'Mike Broberg'
}, function (err, response) {
  console.log(err || response);
});

// read a document by ID; log the response
db.get(DOCUMENT_ID, function (err, response) {
  console.log(err || response);
});

// update a document; log the response
db.put({
  _id: DOCUMENT_ID,
  _rev: DOCUMENT_REV,
  name: 'Mike Broberg',
  title: 'Baseballer of the Ninth Circle'
}, function (err, response) {
  console.log(err || response);
});

// delete a document; log the response
db.remove({
  _id: DOCUMENT_ID,
  _rev: DOCUMENT_REV
}, function (err, response) {
  console.log(err || response);
});

You can even execute ad-hoc queries on PouchDB's local data:

db.query({
  // write your map function in JavaScript
  map: function (doc) {
    if (doc.title) emit(doc.title, null);
  }
}, {
  // in this example, we won't use a reduce function
  reduce: false
}, function (err, response) {
  // log the error, or the response if no error
  console.log(err || response);
});

PouchDB in the Wild

You can see PouchDB in action in our express-cloudant project template, as part of its API in routes/api.js. There, it allows you to provide rapid, controlled access to your Cloudant databases.

If you have any trouble with any of this, post your question on StackOverflow, hit us up on IRC, or if you'd like to speak more privately, send us a note at support@cloudant.com

Create an account and try it yourself

Sign Up for Updates!

Recent Posts