Change Streams (CDC)

patinaDB can stream every committed graph change as it happens, so external systems can react to writes — invalidate a cache, sync a search index, feed a downstream ETL pipeline. This is Change Data Capture (CDC), and it is built directly on the engram log: every commit is an engram of resolved delta-ops, and the change stream is simply that log made subscribe-able.

CDC is a server (Raft) feature, exposed over HTTP as Server-Sent Events (SSE).

The endpoint

GET /changes?db=<name>&since=<engram-uuid>

• db — the database to observe (default default).
• since — a resume cursor: the engram id of the last change you already processed. The stream first replays every engram committed after that id, then live-tails new commits. Omit it (or pass 0) to start from the beginning of history.

The response is an SSE stream (Content-Type: text/event-stream). Each committed write arrives as one change event:

id: 6f9c…-a1b2            ← the engram id = your next resume cursor
event: change
data: {"engram_id":"6f9c…-a1b2","parent_id":"…","db":"default",
       "timestamp":1751900000,"author":"alice",
       "changes":[{"op":"createNode","id":"…","label":"Person"},
                  {"op":"setNodeProperty","id":"…","key":"age","value":30}]}

The SSE id: field is the engram id, so a standards-compliant SSE client resumes automatically via Last-Event-ID after a dropped connection; you can also pass it back explicitly as ?since=.

Change records

Each event’s changes array holds one compact record per delta-op:

Resume & delivery semantics

Delivery is at-least-once with the engram cursor. On reconnect with since=<cursor>, the stream replays exactly the engrams after that cursor and then continues live. The server subscribes to the live feed before reading history, so no commit can slip through the gap between “read the past” and “start tailing”; the small replay/live overlap is de-duplicated internally, so a well-behaved consumer sees every engram after its cursor, with no gap and only a bounded, self-healing overlap.

Persist the last engram_id you successfully processed. If your consumer restarts, reconnect with it as since= and you continue exactly where you left off.

Lag

The stream is backed by a bounded in-memory buffer per database. A consumer that falls too far behind receives a lagged event:

event: lagged
data: {"resumeFrom":"6f9c…-a1b2"}

When this happens the server automatically re-reads the engram log from your last cursor (so no changes are lost) and continues. The lagged event is only a cue that a resync occurred.

Consistency (read this)

The change stream is node-local and eventually consistent, exactly like a consistency=local read:

• It observes this node’s applied HEAD as it advances. On a follower it lags the leader slightly; it never reflects an uncommitted write.
• Ordering within a database is the engram chain order (each event’s parent_id is the previous event’s engram_id).
• Publishing a change never blocks replication — a slow or dead subscriber can never stall the write path; it just lags and resyncs.

For a single-writer-of-record consumer, subscribe to the leader (see cluster routing); a follower stream is fine for best-effort reactions where a small delay is acceptable.

Authorization

/changes is authorized as a read on the target database — the caller needs at least the Reader role for that db (see Authentication & RBAC). An unauthenticated request is rejected with 401.

Example

# Tail the default database's changes (with credentials + resume cursor).
curl -N -u alice:apw \
  'http://localhost:8080/changes?db=default&since=6f9c…-a1b2'

-N disables curl’s buffering so events print as they arrive. Any SSE-capable client (browser EventSource, an SSE library in your language) works the same way.

Related: CDC is a live view over the same engram log that powers diffs and time travel. Where those read history on demand, CDC pushes each new engram as it commits.