Tombstones

    +

    What tombstones are

    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 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 tombstone artefact
    {
      "_deleted": true,
      "_id": "foobar",
      "_rev": "3-db962c6d93c3f1720cc7d3b6e50ac9df"
    }

    The 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

    What you can do with tombstones

    Whether your synchronizations are purely sync gateway or you use Couchbase Lite, you wil need to manage tombstone artefacts (see Working with tombstones):

    • Remove tombstones — you need to purge them, manually or automatically

    • Clear Sync Gateway’s in-memory channel caches by ejecting