A newer version of this documentation is available.

View Latest

Tombstones

      +

      About Sync Gateway Tombstones.
      Here we introduce the concept of Tombstones and their role in the Sync Gateway revision process.

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

      What tombstones are

      A tombstone is a persistent record that an item has been deleted.

      Sync Gateway creates tombstones to ensure all synchronizing devices can identify that a previously existing document has now been deleted, this is particularly necessary in the case of devices that may not be online continuously and therefore not syncing regularly.

      The actual tombstone artifact is a document revision comprising only:

      • the (deleted) document ID

      • a revision ID

      • a key value pair deleted:true.

      Example tombstone artefact
      {
        "_deleted": true,
        "_id": "foobar",
        "_rev": "3-db962c6d93c3f1720cc7d3b6e50ac9df"
      }

      The tombstone lifecycle

      The storage location of tombstones differs slightly depending on whether the Shared Bucket Access feature is enabled (enable_shared_bucket_access: true).

      The table below describes those differences.

      enable_shared_bucket_access: false enable_shared_bucket_access: true

      Mobile metadata storage location

      Persisted on the document (doc._sync)

      Persisted as system extended attributes (xattr._sync)

      Tombstone storage location

      Persisted on the document

      Persisted as system extended attributes (xattr._sync).

      Additional user properties on a tombstone

      Persisted on the document

      Not persisted

      Additional system properties on a tombstone

      Persisted on the document

      Not persisted

      Document operations also have a different impact on tombstones when Shared Bucket Access is enabled/disabled.

      enable_shared_bucket_access: false enable_shared_bucket_access: true

      Deleting a document through Sync Gateway

      Creates a tombstone

      Creates a tombstone

      Purging a document through Sync Gateway

      Removes the document and metadata

      Removes the document and metadata

      Deleting a document body in the bucket (SDK, N1QL, expiry)

      Removes the document and metadata

      Creates a tombstone

      Purging a document’s metadata (on Couchbase Server)

      N/A

      Removes the tombstone metadata

      What you can do with tombstones

      Whether your synchronizations are purely sync gateway or you use Couchbase Lite, you wil need to manage tombstone artefacts (see Working with tombstones):

      • Remove tombstones — you need to purge them, manually or automatically

      • Clear Sync Gateway’s in-memory channel caches by ejecting