Document versioning and conflicts FAQ
When you use distributed databases, copies of your data might be stored in multiple locations. Keeping this data in sync is important. However, your work environment might prevent your users from updating documents with their changes immediately, or even replicating to the database.
As a result, the copies of a document might have different updates. "Conflicts" occur because IBM® Cloudant® for IBM Cloud® can't determine which copy is the correct one.
IBM Cloudant uses multi-version concurrency control (MVCC) to ensure that all nodes in each database cluster include only the newest version of a document.
What is eventual consistency?
IBM Cloudant databases are eventually consistent, which means IBM Cloudant must ensure that no differences exist between nodes. These inconsistencies can happen when out-of-date documents are synchronized.
It's important for IBM Cloudant databases to have concurrent read and write access. MVCC enables that capability. MVCC is a form of optimistic concurrency control that makes read and write operations on IBM Cloudant databases faster because a database lock isn't necessary for read and write operations. At the same time, MVCC enables synchronization between IBM Cloudant database nodes.
How do I know whether there's a conflict?
You don't know. Sometimes you request a document that has a conflict. At those times, IBM Cloudant returns the document normally, as though no conflict exists. However, the version that is returned isn't necessarily the most current version. Instead, the version is selected based on an internal algorithm that considers multiple factors. You must not assume that when documents are returned they're always the most current.
How do I identify a document with a conflict?
If a conflict with a document exists and you try to update it, IBM Cloudant returns a 409 response. If you try to update a document while you're offline, IBM Cloudant can't check for potential conflicts, and you don't receive a 409 response.
When this situation happens, it's best to check for document conflicts when you're back online. If you need to find document conflicts, use the following example map function:
function (doc) {
if (doc._conflicts) {
emit(null, [doc._rev].concat(doc._conflicts));
}
}
If you want to find conflicts within multiple documents in a database, write a view.
What happens if I ignore conflicts?
If you don't check for conflicts, or don't fix them, your IBM Cloudant database has the following problems:
- Document inconsistency increases because conflicting documents continue to multiply.
- Database size increases because documents with conflicts must be kept until the conflict is resolved.
- Performance degrades because it takes more work for IBM Cloudant to respond to each request since it has to go through all the conflicted documents to find the "best possible" version.
How do I resolve conflicts?
After you find a conflict, follow these four steps to resolve it.