Skip to content
Aurabase Logo
aurabase

Subscribe to a channel

GET/v1/realtime/ws

Upgrade WebSocket to realtime service. Messages are JSON objects discriminated by a type field — this is not the Phoenix protocol.

Settings#

ParameterTypeRequiredDescription
tokenqueryyesUser JWT, passed as a query parameter (a browser cannot set a header on a WebSocket).
channelquerynoChannel to join at connection. It must be prefixed with the project: {project_id}:{topic}. Otherwise, send a subscribe message after opening.
vsn / formatquerynoProtocol version: 1.0.0 = JSON text (default), 2.0.0 = 6 byte binary header + JSON payload.
config.postgres_changes[]body (subscribe)noCDC filters: event (INSERT, UPDATE, DELETE or *, default *), schema, table, filter. On a channel not named db:<schema>.<table>, each filter needs a table.
config.postgres_changes[].filterstringnoSyntax column=op.value. Operators: eq, neq, lt, lte, gt, gte, in, like, optionally prefixed with not..
config.broadcastobjectnoself_broadcast (receive its own broadcasts, default false) and ack (acknowledgement of receipt, default false).
config.presenceobjectnokey — presence key allowing you to follow the same user on several tabs.
config.privatebooleannoPrivate channel: an authorization check is made before joining.

Protocol messages#

Info

Client → server: subscribe, unsubscribe, broadcast, presence_update, ping, access_token. Server → client: subscribed, event, pong, error, token_refreshed, broadcast_ack, presence_state, channel_recovered.

HSE Alternative#

Tip

GET /v1/realtime/sse provides unidirectional flow. Unlike WebSocket, requires an API key and infers the project from ?project_id= or the prefix of ?channel=.

RLS#

Info

CDC events inherit RLS policies: a client is only notified of changes on rows it can read. The JWT is re-validated periodically (every 5 minutes at most) — send access_token to renew it without breaking the connection.