Definition

A tombstone record is a marker that indicates a UUID-identified resource has been logically deleted, without physically removing the underlying row or event from the data store. The tombstone preserves the UUID’s existence in the system — maintaining referential integrity, audit history, and replication correctness — while communicating to all readers that the resource is no longer active.

The term originates from distributed databases and log-compaction systems (notably Apache Kafka and Apache Cassandra), where physical deletion is impossible or unsafe because replicas may not yet have processed earlier writes.

Why hard deletes are problematic in distributed systems

A DELETE FROM users WHERE id = $uuid works cleanly in a single-node database. In a distributed system it creates several problems:

  1. Replication lag — a replica that has not yet received the delete may serve the row as active
  2. Foreign key violations — other tables referencing the UUID fail if the row is gone
  3. Audit loss — the deletion event disappears from the log with no record of who deleted it or when
  4. Idempotency — replaying an event stream that includes a delete cannot reconstruct the final state if the original row is gone

Tombstones solve all four problems by converting deletes into writes.

UUID v7 and tombstone timestamps

UUID v7 embeds a 48-bit millisecond timestamp in its most significant bits. A tombstone record keyed by UUID v7 carries its own deletion time — no separate deleted_at column is required:

// Extract deletion time directly from the tombstone's UUID v7 key
function deletedAtMs(uuidV7: string): number {
  return parseInt(uuidV7.replace(/-/g, '').slice(0, 12), 16);
}

const tombstoneId = '018fbe3a-4c5d-7b12-8abc-0123456789ab';
const deletedAt   = new Date(deletedAtMs(tombstoneId));
// deletedAt is derived from the UUID itself — zero extra columns

Database soft delete with tombstone pattern

Schema design

-- Users table with soft delete support
CREATE TABLE users (
  id         uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
  email      text        NOT NULL UNIQUE,
  name       text        NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now(),
  deleted_at timestamptz           DEFAULT NULL  -- NULL = active
);

-- Partial index: active users only — tombstoned rows invisible to normal queries
CREATE INDEX users_active_email_idx ON users (email)
  WHERE deleted_at IS NULL;

-- Separate tombstones table for event-sourced audit log
CREATE TABLE user_tombstones (
  id          uuid        PRIMARY KEY,  -- same UUID as the deleted user
  deleted_by  uuid        NOT NULL,     -- actor who performed the deletion
  deleted_at  timestamptz NOT NULL DEFAULT now(),
  reason      text
);

Soft delete operation

import { v7 as uuidv7 } from 'uuid';

async function softDeleteUser(
  db: Database,
  userId: string,
  actorId: string,
  reason?: string,
): Promise<void> {
  await db.transaction(async (tx) => {
    // Mark user as deleted (tombstone in-place)
    const result = await tx.query(
      'UPDATE users SET deleted_at = now() WHERE id = $1 AND deleted_at IS NULL RETURNING id',
      [userId]
    );

    if (result.rowCount === 0) {
      throw new Error(`User ${userId} not found or already deleted`);
    }

    // Write explicit tombstone record for audit and event sourcing
    await tx.query(
      'INSERT INTO user_tombstones (id, deleted_by, reason) VALUES ($1, $2, $3)',
      [userId, actorId, reason ?? null]
    );
  });
}

// Query active users — tombstoned rows automatically excluded by partial index
const activeUsers = await db.query(
  'SELECT id, email, name FROM users WHERE deleted_at IS NULL ORDER BY id'
);

Kafka log compaction tombstones

In Kafka, a tombstone is a message where the key is set to the UUID of the deleted record and the value is null. Log compaction retains the tombstone for a configurable period (delete.retention.ms) and then removes both the tombstone and all prior messages with the same key:

// Produce a Kafka tombstone for a deleted user
await producer.send({
  topic: 'users',
  messages: [{
    key:   userId,   // UUID v7 string — the deleted record's key
    value: null,     // null value = tombstone signal
    headers: {
      'event-type': 'user.deleted',
      'actor-id':   actorId,
    },
  }],
});

Consumers that process this topic handle null values as delete events:

consumer.on('message', async ({ key, value }) => {
  if (value === null) {
    // Tombstone — delete from local read model
    await readModel.delete(key.toString());
    return;
  }
  // Normal upsert
  const user = JSON.parse(value.toString());
  await readModel.upsert(user);
});

Purging old tombstones with UUID v7 range queries

UUID v7’s timestamp prefix enables efficient tombstone purging without a separate deleted_at index. The UUID for any given timestamp can be constructed by setting the timestamp bits and zeroing the rest:

-- Purge tombstones older than 90 days using UUID v7 range scan
-- (works because UUID v7 sorts chronologically)
DELETE FROM user_tombstones
WHERE id < (
  -- Construct the minimum UUID v7 value for (NOW() - 90 days)
  -- by encoding the cutoff timestamp into the first 12 hex chars
  lpad(to_hex(
    (extract(epoch from (now() - interval '90 days')) * 1000)::bigint
  ), 12, '0') || '0000-7000-8000-000000000000'
)::uuid;

For an exact utility function, see UUID in Databases — Range Queries.

Tombstone vs soft delete flag comparison

PropertySoft delete flag (deleted_at)Explicit tombstone record
Storage locationSame row, in-place updateSeparate row or table
Works with append-only storageNoYes
Kafka log compaction supportNoYes (null value)
Audit trail built-inPartial (timestamp only)Full (actor, reason, timestamp)
Foreign key safeYesYes
Easy to accidentally queryYes (forgetting WHERE clause)No (requires explicit join)
Purge complexitySimple UPDATEDelete from tombstone table

Many production systems use both: an in-place deleted_at flag for query convenience and an explicit tombstone record for event sourcing and audit.

Frequently asked questions

Why use a UUID as the tombstone key instead of an integer?

Distributed systems — multi-region databases, event-sourced architectures, Kafka topics — cannot rely on auto-increment integers because they are not globally unique across nodes. A UUID v7 primary key is globally unique and embeds a millisecond timestamp, so a tombstone record carries its own deletion time without a separate deleted_at column. Any replica that receives the tombstone can determine when the deletion occurred by decoding the UUID's timestamp field.

How does a tombstone differ from a soft delete flag?

A soft delete flag (deleted_at IS NOT NULL or is_deleted = true) modifies the existing row in place. A tombstone record is a separate record — often in a dedicated table or a Kafka compaction-enabled topic — that asserts the UUID no longer exists. Tombstones are preferred in event-sourced and log-based systems because they work with append-only storage where rows cannot be updated. In Kafka log compaction, a tombstone is a message with a non-null key and a null value, which triggers removal of all prior messages with the same key.

When should I purge tombstone records?

Tombstones can be purged once all consumers, replicas, and read models have processed the deletion event and are known to be up-to-date. A safe strategy is to retain tombstones for a configurable window — typically 30–90 days — and then delete them in a background job. UUID v7's embedded timestamp lets you query old tombstones efficiently: WHERE id < uuid_v7_from_ms(NOW() - INTERVAL '90 days') without a separate deleted_at index. See UUID in Databases for range-query patterns.

Do tombstones work with foreign keys?

Tombstones are specifically valuable when you need to preserve referential integrity during soft deletion. A hard delete with foreign key constraints would fail if other rows reference the deleted UUID. A tombstone (or soft delete flag) leaves the row in place — foreign keys remain valid — while signalling to the application that the record is logically deleted. Add a partial index to exclude tombstoned rows from active-record queries: CREATE INDEX ON orders (user_id) WHERE deleted_at IS NULL.