A newer version of this documentation is available.

View Latest

Tombstones

      +

      Sync Gateway’s Tombstones are the means by which mobile clients are notified that a document has been deleted.
      Here we introduce the concept of Tombstones and their role in the Sync Gateway revision process.

      Tombstone Objects

      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 are not syncing regularly.

      The actual tombstone artefact is a document revision comprising only:

      • The (deleted) document ID

      • A revision ID

      • A key value pair deleted:true.

      Example 1. Example tombstone artifact
      {
        "_deleted": true,
        "_id": "foobar",
        "_rev": "3-db962c6d93c3f1720cc7d3b6e50ac9df"
      }

      Sync

      When mobile tombstones sync with a Couchbase Server (that is, when enable_shared_bucket_access: true) they become server tombstones. The document body is deleted, and only the mobile sync metadata required to replicate the tombstone is retained in the mobile extended attribute.

      The server’s metadata purge interval becomes an important consideration for sync’d mobile deployments. Because, when the server purges a tombstone (based on the metadata purge interval), that tombstone is no longer replicated to mobile clients.

      So, users should set the server’s metadata purge interval based on their expected client replication frequency, to ensure that clients are notified of the tombstone prior to that tombstone being purged.

      The default metadata purge interval is set to 3 days which can potentially result in tombstones being purged before all clients have had a chance to be notified.

      For how to tune the metadata purge interval on Couchbase Server, see the server documentation on:

      No matter how you sync, you will need to manage tombstone artifacts to:

      • Remove tombstones (manually or automatically) — see Purging

      • Clear Sync Gateway’s in-memory channel caches — see Cache Ejection

      Storage Location

      The storage location of tombstones differs slightly depending on whether the Shared Bucket Access feature is enabled (enable_shared_bucket_access: true) — see, Table 1 for those differences.

      Table 1. Tombstone locations

      Type of data

      Value of enable_shared_bucket_access`

      false

      true

      Mobile metadata

      Persisted on the document (doc._sync)

      Persisted as system extended attributes (xattr._sync)

      Tombstone

      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

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

      Location

      Activity

      Value of enable_shared_bucket_access`

      false

      true

      Sync Gateway

      Deleting a document

      Creates a tombstone

      Creates a tombstone

      Purging a document

      Removes the document and metadata

      Removes the document and metadata

      Couchbase Server

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

      Removes the document and metadata

      Creates a tombstone

      Purging a document’s metadata

      N/A

      Removes the tombstone metadata

      Purging

      To remove tombstones, you need to purge them. The table at Table 2 shows when tombstones are purged automatically and how to manually purge them.

      Table 2. Purging tombstones

      Value of enable_shared_bucket_access`

      false

      true

      Automatic

      Tombstones are not automatically purged from the bucket.

      Tombstones can be purged by setting a server expiry on tombstone documents. This can be easily automated via Sync Gateway.

      Use the expiry() function in the Sync Function.

      Set the expiry time to be sufficient to allow for all other devices to sync and receive the delete notification —  perhaps a week, or a month.

      Tombstones are automatically purged from the bucket based on the server’s metadata purge interval.

      Manual

      Tombstones can be manually removed via Sync Gateway’s /\{tkn-db}/_purge endpoint, or deleting documents directly in the bucket.

      Tombstones can be manually removed via Sync Gateway’s /\{tkn-db}/_purge endpoint.

      Purging of tombstones is also required on Couchbase Lite. For example, you might decide that if a document is deleted on a Couchbase Lite client, that you want to purge the document (on that device) as soon as the delete has been successfully replicated to Sync Gateway.

      Cache Ejection

      Deleted/expired tombstones aren’t automatically ejected from Sync Gateway’s in-memory channel caches. See Table 3, which shows when channel caches are ejected.

      Table 3. Flushing Sync Gateway channel caches

      Tombstone
      Purged On

      Value of enable_shared_bucket_access`

      false

      true

      Couchbase Server

      Restarting Sync Gateway will flush the cache

      • Restarting Sync Gateway will flush the cache

      • Running the /\{tkn-db}/_compact endpoint will remove purged tombstones from the channel cache [1]


      1. Commencing with release 2.1.1

      Sync Gateway

      • Restarting Sync Gateway will flush the cache.

      • Starting in 2.1.1, this is done automatically.

      • Restarting Sync Gateway will flush the cache.

      • Starting in 2.1.1, this is done automatically.