Realtime

Railbase pushes record changes to subscribed clients in real time over WebSocket (or Server-Sent Events). Subscriptions respect the same access rules as the REST API — you only receive events for records you could read.

Connect and subscribe

The WebSocket endpoint is GET /api/realtime/ws (subprotocol railbase.v1). Subscribe by sending a JSON frame with the topics you care about:

{ "action": "subscribe", "topics": ["posts/*", "posts/abc123", "users/me"] }

You can subscribe / unsubscribe at any time without reconnecting.

For SSE, open GET /api/realtime?topics=posts/*,orders/create instead — the topics ride in the query string, and the connection also speaks the PocketBase-SDK dialect (a PB_CONNECT hello with a clientId, then POST /api/realtime to update that client's subscriptions). Both transports require an authenticated caller.

Topics

Topics are <collection>/<verb> or <collection>/<recordId>:

Topic	Matches
posts/*	every create/update/delete on posts
posts/create	only new posts
posts/abc123	changes to one record

Verbs are create, update, and delete.

Events

The server pushes one frame per matching record event; data carries the verb and the record:

{
  "event": "posts/create",
  "id": "<event_id>",
  "data": { "action": "create", "record": { "id": "abc123", "title": "…" } }
}

plus control frames (railbase.subscribed, pong, error). Over SSE the same triple maps onto the event: / id: / data: frame fields.

From the SDK

The generated TypeScript client wraps all of this:

const sub = rb.realtime.subscribe({ topics: ["posts/*"] }, (evt) => {
  console.log(evt.event, evt.data);
});
// later: sub.unsubscribe()

Publishing your own topics

Server-side (Go), plugins and apps can publish domain events on the bus:

app.Realtime().Publish("orders.shipped", payload, tenantID)

Subscribers receive them the same way as record events.