Python SDK - Realtime#

Subscribe to table changes with two transports:

  • websocket - WebSocket to the realtime server. One persistent connection, auto-reconnect with backoff. Needs the optional websockets package: pip install rafikidb[realtime].
  • sse - Server-Sent Events stream using only the standard library.
  • auto (default) - WebSocket when websockets is installed, else SSE.

Subscribe#

def on_event(event):
    event.type         # "INSERT" | "UPDATE" | "DELETE"
    event.table        # "messages"
    event.record       # the row dict
    event.old_record   # previous row (UPDATE/DELETE) or None
    event.created_at

sub = db.realtime.subscribe(
    "messages",
    on_event,
    events=["INSERT", "DELETE"],   # optional filter
    transport="auto",              # auto | websocket | sse
)

sub.wait()     # block until stopped (returns bool)
sub.close()    # stop from another thread
sub.stopped    # bool
Python

Events are delivered on a background daemon thread, so the callback should be fast (queue work off if needed).

How it works#

  1. The WebSocket transport calls POST /projects/{id}/realtime/connect?table=... and receives a scoped token and channel for the realtime server.
  2. The SSE transport reads the plain HTTP stream at /projects/{id}/realtime/events?api_key=...&table=....
  3. SSE reconnects every 3 seconds; WebSocket reconnects with exponential backoff min(1.0 * 2**retry, 30.0).

Event payload#

{
  "id": "uuid",
  "type": "INSERT",
  "table": "messages",
  "project_id": "5c73dab0-...",
  "record": { "id": "...", "message": "hello" },
  "old_record": null,
  "created_at": "2026-10-03T20:47:34Z"
}
JSON

Next: Storage.