Tutorial: Building with CleaveDB

Soft Delete (DRAIN)

The DRAIN command performs a safe, reversible soft delete. Instead of instantly erasing files from disk, CleaveDB moves the targeted documents into an isolated system collection called _rubbish.

Drain a document by ID

To soft delete a specific document, pass the bucket name and the document ID:

DRAIN users "jane"

Jane's record is immediately removed from standard lookups. Any future SCOOP users WHERE id = "jane" or graph traversals through Jane will treat the record as nonexistent.

Drain matching documents with WHERE

You can soft delete groups of records matching conditional criteria:

DRAIN orders WHERE status = "cancelled" AND created_at < 1704067200

All matching orders are moved to the rubbish bin in a single atomic transaction.

Inspecting the rubbish bin

Administrators and authorized services can inspect soft-deleted records directly by querying the _rubbish collection:

SCOOP _rubbish WHERE original_bucket = "users"

Each entry in _rubbish retains its original payload, document ID, deletion timestamp, and provenance metadata so it can be audited or restored later.