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:

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

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, 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`
Tombstone Purged On	`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.

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials