Tutorial: Building with CleaveDB

UNDO — global rollback

While transactions (BEGIN ... COMMIT) require you to plan atomic blocks in advance, accidents in interactive shells or operational scripts often happen on live, committed writes. CleaveDB solves this with the global UNDO ledger, allowing you to audit committed mutations and roll back mistakes dynamically.

Inspecting the undo stack (UNDO SHOW)

Every write (POUR) and update (CHANGE) automatically pushes an operation record into the system _undo_stack. You can inspect recent operations at any time:

UNDO SHOW

The engine returns an array of operations ordered by timestamp descending, showing the unique operation ID (uid), action type, target document, and previous state.

Rolling back an accidental mutation

Consider an accidental price overwrite on a product document:

POUR INTO products "1" {"price": 100}
CHANGE products "1" SET price TO 9999    -- Accidental bad price update

Inspect the undo stack to find the target operation ID:

UNDO SHOW
-- Returns:
-- [
--   {"uid": "tester.1791248457533_7852", "action": "CHANGE", "target": "products:1", ...},
--   {"uid": "tester.1791248450123_4510", "action": "POUR",   "target": "products:1", ...}
-- ]

Execute UNDO with the operation ID to roll back all mutations down to that point:

UNDO "tester.1791248457533_7852"

CleaveDB automatically restores the before document snapshot, returning {"status": "ok", "message": "Successfully reverted 1 operations.", "reverted": 1}.

Cascading batch rollbacks

If an errant batch script applied multiple updates across documents, specifying an older operation ID unwinds all intermediary mutations in reverse chronological order:

-- Reverts all actions performed up to the initial creation
UNDO "tester.1791248450123_4510"

The engine unwinds each step sequentially, safely cleaning the undo stack and keeping document history consistent.