Managing Tombstones

By design, when a document is deleted in Couchbase Mobile, they are not actually deleted from the database, but simply marked as deleted (by setting the _deleted property). The reason that documents are not immediately removed is to allow all devices to see that they have been deleted - particularly in the case of devices that may not be online continuously and therefore not syncing regularly.

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 SG 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

Document (doc._sync)

System extended attribute (xattr._sync)

Tombstone storage location

Document

System extended attribute (xattr._sync). Empty document body.

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