Updating and deleting documents

As we saw in the past two chapters, working with PouchDB documents can be tricky, because you have to manage the revision identifier _rev.

Now that we understand promises, though, there are few techniques we can use to make our code more elegant and readable.

Creating a default document

Often in our code, we'll want to get() a document, and if it doesn't exist, we want to create some default.

For instance, let's say we have a configuration object. We want to provide some reasonable defaults for our config:

{
  _id: 'config',
  background: 'blue',
  foreground: 'white',
  sparkly: 'false'
}

This is a pretty good default setting! So let's write the code to set it as our default.

Thankfully, promises make this rather easy:

db.get('config').catch(function (err) {
  if (err.name === 'not_found') {
    return {
      _id: 'config',
      background: 'blue',
      foreground: 'white',
      sparkly: 'false'
    };
  } else { // hm, some other error
    throw err;
  }
}).then(function (configDoc) {
  // sweet, here is our configDoc
}).catch(function (err) {
  // handle any errors
});

This code is doing the following:

Try to get() a doc with _id equal to 'config'
If it doesn't find it, return the default doc
Otherwise, you'll just get back the existing document

You can see a live example of this code.

Why must we dance this dance?

A common question from new PouchDB/CouchDB users is: why do we have to deal with _rev at all? Why can't I just put() the document without providing a _rev?

The answer is: because _revs are what makes sync work so well. PouchDB asks for a little upfront effort with managing document revisions, so that later on, sync is a breeze.

In fact, you are probably already familiar with a system that forces you to go through a similar dance. This system is called Git.

PouchDB and CouchDB's document revision structure is very similar to Git's. In fact, each document's revision history is stored as a tree (exactly like Git), which allows you to handle conflicts when any two databases get out of sync.

rev 3-a  rev 3-b
      \___/
        |
      rev 2
        |
      rev 1

Conflicts will be discussed later in this guide. For now, you can think of revisions as being a single lineage:

Deleting documents

When you remove() a document, it's not really deleted; it just gets a _deleted attribute added to it.

That is, the database saves a tombstone at the end of the revision tree.

{_id: 'foo', _rev: '4-z', _deleted: true}
            |
{_id: 'foo', _rev: '3-y'}
            |
{_id: 'foo', _rev: '2-x'}
            |
{_id: 'foo', _rev: '1-w'}

There are three ways of deleting a document, which are all equivalent:

1) You can call db.remove(doc):

db.get('mydoc').then(function (doc) {
  return db.remove(doc);
});

2) You can call db.remove(doc._id, doc._rev):

db.get('mydoc').then(function (doc) {
  return db.remove(doc._id, doc._rev);
});

3) You can call db.put(doc) with _deleted set to true:

db.get('mydoc').then(function (doc) {
  doc._deleted = true;
  return db.put(doc);
});

Of course, you will want to add catch() to the end of all these, unless you like to live dangerously.

You can see a live example of this code.