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 showing that an item was deleted.

Sync Gateway creates tombstones to make sure all synchronizing devices can identify that an existing document is now deleted. This matters for devices that may go offline for extended periods and therefore sync infrequently.

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, meaning 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 synced mobile deployments: when the server purges a tombstone, based on that interval, it no longer replicates to mobile clients.

Set the server’s metadata purge interval based on your expected client replication frequency. This makes sure clients receive the tombstone notification before the server purges it.

On Couchbase Server, the default metadata purge interval is 3 days, which can purge tombstones before all clients have synced them. On Capella, linking an App Service to a cluster sets the cluster’s metadata purge interval to 60 days for every bucket on that cluster. To use a longer interval, contact Couchbase Support, who assess the storage impact before they change it. When you delete the App Service, Capella resets the interval to 3 days, and the next compaction can purge tombstones older than 3 days. Before you delete an App Service, make sure your clients have synced their deletions. For more information, see Manage Buckets.

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

Bucket settings [on server UI] — Auto Compaction with UI
Bucket endpoint [on the REST API] — Creating and Editing Buckets

No matter how you sync, you 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`
Type of data	`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 affect tombstones differently depending on whether Shared Bucket Access is turned on or off.

Location

Activity

Value of enable_shared_bucket_access

false

true

Sync Gateway

Deleting a document

Creates a tombstone

Purging a document

Removes the document and metadata

Couchbase Server

Deleting a document body in the bucket (SDK, SQL++, 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 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 /{keyspace}/_purge endpoint, or deleting documents directly in the bucket.	Tombstones can be manually removed via Sync Gateway’s /{keyspace}/_purge endpoint.

You must also purge tombstones on Couchbase Lite. For example, you might decide to purge a document on a Couchbase Lite client as soon as Sync Gateway replicates the delete.

Cache Ejection

Deleted/expired tombstones are not 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`
Tombstone Purged On	`false`	`true`
Couchbase Server	Restarting Sync Gateway flushes the cache	Restarting Sync Gateway flushes the cache Running the /{db}/_compact endpoint removes purged tombstones from the channel cache ^[1] 1. Commencing with release 2.1.1
Sync Gateway	Restarting Sync Gateway flushes the cache. Starting in 2.1.1, this is done automatically.	Restarting Sync Gateway flushes the cache. Starting in 2.1.1, this is done automatically.

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials