Tutorial: Building with CleaveDB

Subscribe to a bucket

Subscribing to an entire bucket allows your application to receive live streams of every document insertion (POUR), field modification (CHANGE), and removal (DRAIN) happening within that namespace.

Subscription syntax

Over a WebSocket connection, issue the LISTEN TO command followed by the target bucket:

LISTEN TO chat

The server registers your WebSocket client under the internal channel bucket:chat and begins streaming data events in real time.

Connecting over WebSockets

You can connect directly from JavaScript, Python, or command-line utilities like wscat:

# 1. Connect to the WebSocket port (default 8301)
wscat -c ws://127.0.0.1:8301

# 2. Authenticate session credentials
> {"action": "authenticate", "username": "david", "password": "secret"}
< [{"status": "ok", "message": "Authenticated as david"}]

# 3. Open bucket subscription
> LISTEN TO chat
< [{"status": "listen", "target": "bucket:chat"}]

Your client remains open and awaits real-time push events from the database.

Real-time broadcast in action

When any client writes a message into the bucket:

POUR INTO chat "msg_1" {"user": "Alice", "text": "Welcome to CleaveDB!"}

All connected subscribers on chat immediately receive the broadcast payload:

{
  "event": "POUR",
  "bucket": "chat",
  "id": "msg_1",
  "data": {
    "user": "Alice",
    "text": "Welcome to CleaveDB!"
  },
  "timestamp": 1728562400
}

No external polling loops or cache invalidation pings are necessary; the UI updates instantly.