A newer version of this documentation is available.

View Latest

Delta Sync


      Use Sync Gateway’s delta sync feature for secure, resilient and efficient sync from cloud to edge
      This content introduces Sync Gateway’s delta sync feature; sync only the data that has changed.


      Delta Sync provides the ability to replicate only those parts of a Couchbase Mobile document that have changed. This can result in significant savings in bandwidth consumption as well as throughput improvements, especially useful where network bandwidth is constrained.


      Delta sync is disabled by default on Sync Gateway databases.

      If delta sync is enabled on a Sync Gateway database (see: Example 1), then Couchbase Lite clients syncing with that database will switch to using delta sync automatically. It is also automatically enabled for peer-to-peer sync between Couchbase Lite clients. However, if delta sync is disabled on Sync Gateway then Couchbase Lite clients will operate in normal mode.

      For inter-Sync Gateway Replication — You should note that delta sync does not apply to attachment contents and that it is disabled for Couchbase Lite database replicas.

      Replication does not use Delta Sync when pushing to a pre-2.8 target.


      You can enable delta-sync on a per-database basic in your Sync Gateway configuration file using the delta_sync properties inDatabase Configuration — as shown in Example 1:

      Example 1. Sample of Database with Delta Sync
      // ... other configuration properties as appropriate
        "databases": {
          "db": {
            "name": "dbname",
            "bucket": "default",
            "allow_conflicts": false,
            "revs_limit": 20,
            "delta_sync": { (1)
              "enabled": true,
              "rev_max_age_seconds": 86400
            // ... any other configuration properties as appropriate
      1 database_schema.delta_sync — enable or disable delta sync property for this database; also allows you to tune the amount of additional Couchbase Server bucket storage used by delta sync — see: Couchbase Server Bucket Storage Needs.

      Couchbase Server Bucket Storage Needs

      Delta sync’s storage of backed-up revision bodies in the Couchbase Server bucket means additional Couchbase Server storage is required. This storage is used by Sync Gateway to generate the deltas between old and new revisions. — see Example 2.

      Calculate required storage using: (doc_size * updates_per_day * 86400) / rev_max_age_seconds

      With each delta sync write operation the revision body is backed up in the bucket and retained for rev_max_age_seconds to calculate future revision deltas. So new deltas can only be generated for read requests arriving within the rev_max_age_seconds time window.

      Setting rev_max_age_seconds = 0 will generate deltas opportunistically on pull replications, with no additional storage requirements.

      Example 2. Additional storage calulation


      • rev_max_age_seconds = default value

      • average document size = 4 KB

      • writes/day = 100

      Then enabling delta sync would take up an additional 400 KB of storage on Couchbase Server:
      ((4 * 100 * 86400)/86400)