What it does
A WebSocket endpoint accepts a Phoenix-shaped join, leave, broadcast and presence protocol. Joined channels receive INSERT, UPDATE and DELETE events for collection records, filtered per subscriber by the collection's row-level policy. A separate server-sent-events stream gives operators a feed of every change. Delivery is live and in-process, with no replay.
How it works
Write handlers publish an event after a commit to an in-process broadcast bus. The bus buffers up to 1,024 events; a subscriber that falls further behind loses the oldest ones. The events carry the full record after a write and the last known record before a delete, which is what lets the receiving side evaluate access rules and deliver the new and old values.
Application clients use GET /realtime/v1 as a WebSocket. A token is sent as a query parameter, because browsers cannot set headers on a WebSocket, and resolves with the same priority as HTTP credentials. A client sends join with a channel name and a configuration. The configuration can list postgres_changes subscriptions, each with an event (INSERT, UPDATE, DELETE or all), a table and an optional filter of the form column=eq.value. It can also ask for presence under a key, and for its own broadcasts to be echoed back.
For postgres_changes, delivery is gated twice. First, the event's kind must belong to the connection's project, so a connection for one project never receives another project's events. Second, unless the credential is a service key, the collection's select policy is evaluated against the changed record for that subscriber, and the event is dropped if the policy denies it. If the collection definition cannot be read because of a storage fault or an active recovery fence, the event is withheld rather than delivered unchecked.
Channels also carry client-to-client broadcast messages and presence: track and untrack calls produce presence_state and presence_diff messages with joins and leaves, and a dropped connection removes its presence entries.
GET /v1/realtime is a server-sent-events stream with optional topics and kinds filters and a keep-alive comment. It is an operator interface, not a client API; clients subscribe through the WebSocket. GET /v1/changes serves the same role as a pollable feed.
Where you reach it
- HTTP
GET /realtime/v1?token=<token> (WebSocket upgrade) - HTTP
GET /v1/realtime?topics=entities,files&kinds=<kind> (server-sent events, operator credentials) - HTTP
GET /v1/changes?since=<seq> (change feed, operator credentials)
Limits
- Delivery is live, with no catch-up. The bus is in memory with no replay or resume: a client that disconnects or lags misses events and should re-read after reconnecting.
- Broadcast and presence channels are namespaced by channel name alone, so choose channel names that are unique to your project; the postgres_changes feed is separately scoped to the project.
- The WebSocket token travels in the URL query string. Treat WebSocket URLs as sensitive in logs and proxies.
- postgres_changes covers collection records. Events for other entity kinds, files and agents are not delivered through that feed, and the filter supports column=eq.value comparisons alone.
- On a read replica, realtime connections from project credentials are refused. Connect to the primary.
- The server-sent-events stream has no dedicated test in the engine repository.
Evidence
- On this siteHTTP API reference
- TestsCovered in the engine repository by 15 WebSocket tests (filter parsing, row-level select policy, service-key bypass, project isolation by kind prefix, withheld delivery on a definition fault or recovery fence) and 3 event-bus tests
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.