Managing Tombstones

Mobile tombstones enable mobile clients to be notified when a document has been deleted.

Purging Tombstones

To remove tombstones, you need to purge them. The following tables describe how to purge tombstones (automatically or manually) and reset the Sync Gateway channel cache when Shared Bucket Access is enabled or disabled.

Automatic purging of tombstones

enable_shared_bucket_access: false

enable_shared_bucket_access: true

Tombstones can be automatically purged from the bucket by setting a server expiry on tombstone documents. This can be easily automated via Sync Gateway using the expiry() function in the Sync Function. The expiry time should be sufficient (perhaps a week, or a month) to allow for all other devices to sync and receive the delete notification.

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

Manually purging tombstones

enable_shared_bucket_access: false

enable_shared_bucket_access: true

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

Tombstones can be manually removed via Sync Gateway’s /{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 out to Sync Gateway.

Cache Ejection

Deleted/expired tombstones aren’t automatically ejected from Sync Gateway’s in-memory channel caches. The following table describes how to eject Sync Gateway’s cache.

enable_shared_bucket_access: false enable_shared_bucket_access: true

For tombstones purged on Couchbase Server

  • Restarting Sync Gateway will flush the cache

  • Restarting Sync Gateway will flush the cache.

  • Starting in 2.1.1, running the /{db}/_compact endpoint will remove purged tombstones from the channel cache.

For documents purged on 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.

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