Edits of

Copy of Original Draft Score by Handel

Photo courtesy of Adrian Pallant with permission under license CC BY-SA 2.0

The U in CRUD

In this earlier post, I wrote about getting started with basic CRUD operations in Couchbase Lite on Android. In this quick note, I want to go a little deeper on document updating.  This will open the door to a whole new set of issues.  Let’s take a peek inside.

Couchbase Lite is a document-oriented database.  The documents are stored as JSON objects.  As described in the previous post, it’s easy to work with the document contents directly.  They’re stored in the document object as a map.  That fits nicely with native ways of manipulating the contents.

Tweaking the direct approach

When you retrieve a document, you get a copy which contains an immutable version of the data.  You can deal with this by copying the map into a separate map object, then overwriting the old map.  That’s shown in this code snippet:

This actually creates a new revision of the document, using the new document body.

Alternatively, you can use createRevision() to obtain a new UnsavedRevision. This returns a copy of the latest revision, but with mutable contents. You can then manipulate the properties map directly. Changes are committed by calling save().  This code snippet has the same end effect as the previous one:

Revisions, you say?

That’s great for a lot of applications.  I haven’t said much about revisions yet.  You get the idea that a document is changing.  Couchbase Lite has a notion of document revisions to go along with those changes.

Revisions go deeper than just tracking a linear set of changes, though.  What doesn’t jump out from examples like the ones I have shown is the possibility of conflicts.  Conflicts occur when more than one update of a specific document revision gets committed back to the database.

Think of it just like a real world document.  Maybe you write an article (or a blog post!) and send it around to several people for comments.  You get one set of comments back and make some changes.  Then another set of comments come back, based on the same original document.  Do this often enough and you’re almost guaranteed to hit the case where some changes overlap.  (Well, for software devs, probably the better example is in merge conflicts when using source control.)  Conflict!


Dealing with document conflicts, revision history, and so on, is more than I want to address in this post.  But we can get a glimpse of how Couchbase helps.  This last approach to updating may seem like overkill, but you’ll come to appreciate it once conflict resolution come into play.  Here’s the code:

Wow, this looks a lot more complex than the earlier examples.  It’s really only a little more complicated.  That added structure ends up making life a lot easier.  So what’s happening?

This construction lets Couchbase Lite deal with the grunge work of handling conflicts.  You define a callback based on the DocumentUpdater interface. Couchbase Lite will take care of creating a new UnsavedRevision instance, just like in the earlier example. Your method then needs to make the changes you want. On return, Couchbase Lite automatically tries to save the document. If it detects a conflict Couchbase Lite simply calls update() again.  Return true if you’ve made changes you want saved, or false otherwise.

If you want to learn more about revisions, collisions, and conflict resolution, take a look at our guide here


Check out more resources on our developer portal and follow us on Twitter @CouchbaseDev.

You can post questions on our forums. And we actively participate on Stack Overflow.

You can follow me personally at @HodGreeley

Posted by Hod Greeley, Developer Advocate, Couchbase

Hod Greeley is a Developer Advocate for Couchbase, living in Silicon Valley. He has over two decades of experience as a software engineer and engineering manager. He has worked in a variety of software fields, including computational physics and chemistry, computer and network security, finance, and mobile. Prior to joining Couchbase in 2016, Hod led developer relations for mobile at Samsung. Hod holds a Ph.D. in chemical physics from Columbia University.


  1. … [Trackback]

    […] Read More: blog.couchbase.com/better-updates-couchbase-lite/ […]

  2. […] So, in a nutshell, we have an example of both creating and updating documents. This isn’t the preferred way to update, although it suffices in many cases. You can read more about updates here. […]

Leave a reply