{"id":4832,"date":"2018-03-19T07:00:32","date_gmt":"2018-03-19T14:00:32","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=4832"},"modified":"2025-06-13T23:43:12","modified_gmt":"2025-06-14T06:43:12","slug":"document-conflicts-couchbase-mobile","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/document-conflicts-couchbase-mobile\/","title":{"rendered":"Document Conflicts & Resolution in Couchbase Mobile 2.0"},"content":{"rendered":"

Document conflicts can occur in distributed environments that support data synchronization, wherein a document can be updated concurrently by one or more writers. This is especially common in mobile environments where unreliable network connections may result in concurrent changes from multiple devices not being synchronized in a timely fashion.<\/p>\n

It can also occur on the client-side, for instance, if a document is being updated locally while changes to the document are being pulled down to the client from a remote server. Hence, there is a need to resolve these document conflicts. \u00a0Couchbase Mobile 2.0<\/a>, introduces \u201cAutomatic Conflict Resolution\u201d<\/em> or a\u00a0\u201cConflict-free\u201d<\/em> mode wherein conflicts are automatically handled and there are effectively no conflicting document revisions in the Couchbase database.<\/p>\n

As an app developer, you probably wouldn\u2019t ever have to do anything specific on the app side in order to deal with conflicts because the system\u2019s default conflict resolver will automatically handle things for you. However, if you need to, you have the option of being notified of conflicts and can take appropriate action. This post will discuss the fundamentals of how document conflicts are automatically handled in Couchbase Mobile 2.0 using the \u201cautomatic conflict resolution<\/em>\u201d or \u201cconflict-free <\/em>\u201d mode.<\/p>\n

<\/p>\n

 <\/p>\n

Assumptions<\/h2>\n

This post assumes that you are familiar with the architecture of Couchbase Mobile stack that includes the Couchbase Lite<\/a> embedded database for your mobile clients, the Sync Gateway<\/a> and Couchbase Server<\/a>. If you are new to the platform, I would recommend catching with these resources<\/a>.<\/p>\n

Background<\/h2>\n

If you haven\u2019t done so, it would be worthwhile reading this earlier demystifying conflict resolution post<\/a> that discusses the fundamentals of how conflict resolution is handled on \u201cnon-conflict-free\u201d mode in Couchbase Mobile including an overview Multi-Version Concurrency Control (MVCC) system.<\/p>\n

Document Revision Tree<\/h3>\n

To understand the conflict resolution process, you would have to a basic understanding of how documents are stored. In Couchbase Mobile, every document is assigned a unique system-generated revision ID or revID<\/em>. This ID is in addition to the document ID which remains the same across document revisions. Every change to a document, be it a modification or a delete is treated as a new revision to the document and is hence, assigned a new revision ID.<\/p>\n

In addition, every document revision has a \u201cgenerationID<\/em>\u201d associated with it. The first time a document is created, a revision gets created with a \u201cgenerationID<\/em>\u201d of 1. Every subsequent revision update will increment this number.<\/p>\n

Every time a change (edit or delete) is to be made to an existing document, the writer must include the revision ID of the current revision of the document that is being updated. A new revision is created for the change and added as a child node to the current revision that was being updated, resulting in a Revision Tree for the document.<\/p>\n

NOTE: The \u201crevID\u201d<\/em> must be treated as an opaque object by the app and the app must not try to generate the \u201crevID\u201d<\/em>.<\/p>\n

\"\"<\/figure>\n

How Document Conflicts Occur<\/h2>\n

At a high level, a conflict occurs when changes are made to the same parent revision of a document by multiple writers.<\/p>\n

Conflicts At Couchbase Lite<\/h3>\n

The illustration below describes a scenario where an app is updating a document revision in memory while the same revision is being updated as a result of a pull replication.
\n\"\"<\/p>\n

Conflicts At Sync Gateway<\/h3>\n

The illustration below describes a scenario where two clients push up changes to the same revision of the document.
\n\"\"<\/p>\n

Conflict Resolution in Couchbase Mobile 2.0<\/h2>\n

In \u201cConflict-Free\u201d<\/em> mode, the Sync Gateway essentially rejects all conflicting updates. The conflicts are automatically resolved at the time the document is created, updated or deleted.
\nSo the implication of this is that there are no conflicting documents stored in the database and is effectively, \u201cConflict Free<\/em>\u201d. We will take a look at how this works.<\/p>\n

Automatic Conflict Resolution in Couchbase Lite 2.0<\/h3>\n

Every document in Couchbase Lite 2.0 is associated with a \u201cconflict resolver\u201d<\/em> that is executed if a conflict occurs when an attempt is made to save<\/code> or delete<\/code> a document. The conflict resolver function chooses a \u201cwinner<\/em>\u201d among the conflicting revisions and this winner is added as a child to the document revision tree.<\/p>\n

\"\"<\/figure>\n

There are two concurrency control policies supported by Couchbase Lite.<\/p>\n

Concurrency Control Policy<\/h4>\n

Last Write Always Wins (Default):<\/strong><\/h5>\n

This is also the default conflict resolver policy. In this case, the last update to the database always wins.<\/p>\n

When you call saveDocument<\/code> with no Concurrency Control argument, this is the policy that is in effect by default.<\/p>\n

This is an example of the call in swift.<\/p>\n

 let savedDocument = try saveDocument(docToSave)<\/code><\/pre>\n
The examples below should clarify the implications of this policy<\/p>\n