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
.
{
"_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.
Type of data |
Value of |
|
---|---|---|
|
|
|
Mobile metadata |
Persisted on the document ( |
Persisted as system extended attributes ( |
Tombstone |
Persisted on the document |
Persisted as system extended attributes ( |
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 |
|
---|---|---|---|
|
|
||
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.
Value of |
||
---|---|---|
|
|
|
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.
Tombstone |
Value of |
|
---|---|---|
|
|
|
Couchbase Server |
Restarting Sync Gateway will flush the cache |
1. Commencing with release 2.1.1
|
Sync Gateway |
|
|