Tutorial: Building with CleaveDB

Subscribe to a document

While subscribing to a bucket streams all activity across a collection, many client use cases—such as user profile sync, live checkout tracking, or order status monitors—only care about changes to a single entity. CleaveDB supports fine-grained document subscriptions using LISTEN TO <bucket> "<id>".

Pinpoint document subscription

Specify both the bucket name and the target document ID:

-- Listen exclusively to updates on David's profile
LISTEN TO users "david"

-- Monitor an individual document
LISTEN TO docs "1"

The WebSocket dispatcher registers a listener specifically on users:david. Any writes to other users (e.g., Alice or Bob) are filtered out, conserving client bandwidth and eliminating client-side filtering.

Listening to state mutations

When an administrative process or background task updates the subscribed entity:

CHANGE users "david" SET status TO "online", last_seen TO 1728562450

The subscriber immediately receives an event payload:

{
  "event": "CHANGE",
  "bucket": "users",
  "id": "david",
  "target": "users:david",
  "data": {
    "status": "online",
    "last_seen": 1728562450
  },
  "timestamp": 1728562450
}

The payload includes the updated attributes, letting client applications update local UI components in place.