About Sync Gateway’s use of Revisions, Revision Trees and Revision Caches.
    Revisions are at the heart of Couchbase Mobile’s ability to respond flexibly and securely to changing data from server to edge.

    Related concepts topics: Users | Roles | Channels | Revisions | Tombstones


    Documents and buckets (collections of, usually related, documents) are the basic units of data within Couchbase.

    Remember that within Couchbase Mobile a document comprises:

    • A Document ID

    • A current revision ID

    • A JSON body

    • Metadata

    Each change to a document (even its creation and deletion) is recorded as a revision. The document’s revisions are contained within its metadata, which stores the revision history as a revision tree.

    Note that binary data such images, audio or other multimedia objects are stored separately from the document,in an entity known as a blob (or attachment). Changes to blobs do not generate revisions.


    Couchbase creates a revision whenever a document is created, updated or deleted. So, each document comprises a series of one or more revisions, a revision tree.

    Each revision is given a unique Revision ID in addition to the Document ID.

    The revision id is used when resolving any conflicts arising when concurrent changes are made to replicated copies of distributed data. It comprises two parts:

    • a generation ID
      This is a sequential auto-incrementing number, specific to the database on which the document resides. Couchbase Lite generates simple integers. Sync Gateway generates more complex long base64 values.
      The contents of remote revision IDs are implementation dependent. Do not base any processing logic on their contents.

    • a hash derived from the document contents

    Revision Trees

    A document’s revision tree comprises each revision — in sequence — that has been made to the document throughout its lifetime to date. The tip of that tree, the leaf node, is the current revision — the most recent version of the document.

    A revision tree’s growth is unlimited and obsolete revisions need to be removed in order to maintain performance levels. This process is know as Revision Tree Pruning.

    Revision Tree Pruning

    In the section

    Algorithm | Controls | Constraints | Learn More

    The process of removing obsolete revisions (pruning) runs automatically every time a revision is added.


    Although fundamentally the same, the pruning algorithm works slightly differently between Sync Gateway and Couchbase Lite.

    On Sync Gateway, the pruning algorithm is applied to the shortest, non-tombstoned branch in the revision tree.

    The algorithm allows the branch to retain a configurable number of revisions (revs_limit) and removes all older revisions.


    You can vary the number of retained revisions using the Configuration File’s revs_limit setting.

    So, for example, with a revs_limit of 1000 the algorithm will keep the last 1000 revisions in the shortest non-tombstoned branch and remove any others from that branch.

    Do not set revs_limit below 100 when allow_conflicts = true
    Otherwise …​ you may adversely affect the conflict resolution process, as there may be insufficient revision history to resolve a given conflict.


    The default and minimum values of revs_limit are dependent on whether allow_conflicts is True or False.

    The presence of multiple unresolved conflicts in a revision tree can impair the pruning process. This may result in obsolete revisions not being pruned, or in revisions being pruned prematurely.

    Learn More

    To learn more about revision pruning and database size management in general see our blog: Pruning — Managing DB Sizes in Couchbase Mobile.

    Revision Caching

    Whenever a document is accessed its revision tree (or at least some portion of its revision tree) is also cached.


    You can control the size of the revision cache using the rev_cache settings within the configuration file, specifically:


    Use the rev_cache.size setting to specify the total number of document revisions to be cached in memory for all (recently accessed) documents.

    When the revision cache is full, Sync Gateway will remove older document revisions to make room for newer ones.

    By adjusting this setting you can fine-tune Sync Gateway’s memory consumption. This can be useful when working on servers with limited memory and in cases when Sync Gateway creates and-or updated many new documents relative to the number of read operations.


    This content relates only to ENTERPRISE EDITION

    The Community Edition is configured with the default value and ignores any rev_cache.shard_count value in the configuration file.

    You can control the number of shards ino which Sync Gateway will split its revisions cache by using the rev_cache.shard_count

    More shards means lower cache contention when accessing distinct revisions, at the cost of some memory overhead per-shard.

    Do not change the default rev_cache.shard_count unless advised to do so by Couchbase Support — see: Couchbase Support Policy.

    Delta Sync and Revisions

    This content relates only to ENTERPRISE EDITION

    When executing a write operation with delta_sync enabled the revision body is backed up in the bucket and retained for this_db.delta_sync.rev_max_age_seconds, during which time it is available for the calculation of future revision deltas.

    As a result, new deltas can only be generated for read requests that come in within the this_db.delta_sync.rev_max_age_seconds time window.

    Storing backed up revision bodies for delta sync incurs additional bucket storage, the size of which equates to:
    (doc_size * updates_per_day * 86400) / rev_max_age_seconds — see Example 1.

    Example 1. Calculating Additional Delta-Sync Storage

    Enabling delta sync would take up an additional 400 KB of storage on Couchbase Server, assuming:

    • The default {rev_max_age_seconds} value

    • An average document size of 4 KB

    • 100 writes/day

    Equating to: (4 * 100 * 86400)/86400 = 400 KB

    Setting this_db.delta_sync.rev_max_age_seconds to zero will generate deltas opportunistically on pull replications, with no additional storage requirements.

    Disabling the Revision Cache

    This content relates only to ENTERPRISE EDITION

    Disabling the revision cache can be useful when there are very large documents or if you expect a very low cache hit rate. Otherwise it can negatively impact the latency of replications.

    Do not disable the revision cache, unless advised to do so by Couchbase Support — see: Couchbase Support Policy.

    To disable the revision cache entirely, set rev_cache.size to zero. Community Edition ignores a zero setting.