Realtime

Why realtime instead of polling

Polling trades freshness against load: poll often and you hammer the backend for mostly-unchanged data; poll rarely and your UI feels stale. Realtime removes the trade. The subscription holds an open stream, and the server sends you a small event only when a row you can see actually changes. Reach for it whenever the screen should reflect what other people (or other tabs, or a background job) just did:

• Chat — live-tail new messages as they're inserted.
• Presence-style UIs — show who's online or active by subscribing to a status table.
• Live dashboards — counters and feeds that update as the underlying rows move.
• Collaborative lists — todos, kanban cards, and docs where two people edit the same data.

Realtime reflects the same data your queries return — it's not a separate copy. So the natural pattern is to combine an initial .select() to load history with a .subscribe() to live-tail everything after.

The SDK

One method on the table builder:

client.from('table').subscribe(onChange, onError?) // → unsubscribe

Your onChange callback receives a single event object each time a row changes:

{
  table: string,                          // which table the change came from
  type: "INSERT" | "UPDATE" | "DELETE",   // what happened
  row: object                             // the affected row
}

The return value of subscribe is an unsubscribe function. Call it when you're done — typically on component unmount — to close the stream. Keeping the handle and calling it is the one rule that matters; forget it and you leak open streams.

const off = lingcode.from('messages').subscribe(({ type, row }) => {
  if (type === 'INSERT') appendMessage(row);
});

// later, on teardown:
off();

A complete example

Here's the whole loop for a chat view: load the recent history once with .select(), then subscribe to live-append new messages, then unsubscribe on teardown. Inside /try and the Mac preview, lingcode already exists; in your own app, create the client first (see the API reference).

// 1. Load history.
const { data: history } = await lingcode
  .from('messages')
  .order('created_at', { ascending: true })
  .limit(100)
  .select();

for (const row of history) appendMessage(row);

// 2. Live-tail everything after.
const off = lingcode.from('messages').subscribe(
  ({ type, row }) => {
    if (!row) { reloadMessages(); return; } // large-row "refetch" signal
    if (type === 'INSERT') appendMessage(row);
    if (type === 'UPDATE') replaceMessage(row);
    if (type === 'DELETE') removeMessage(row);
  },
  (err) => console.error('realtime stream error', err)
);

// 3. On teardown (e.g. component unmount), close the stream.
function teardown() {
  off();
}

That's the canonical shape: an initial read for state, a subscription for the live tail, and an unsubscribe handle you actually call.

Under the hood (REST)

The SDK's subscribe opens an SSE connection to one endpoint:

GET https://lingcode.dev/api/cloud/be/<backend-id>/realtime

It's a Server-Sent Events stream — the response is Content-Type: text/event-stream. Authenticate with your anon key or a signed-in user token (the same credential you use for queries; it's what scopes the RLS filtering). An optional query parameter narrows which tables you hear about:

GET /api/cloud/be/<backend-id>/realtime?table=messages,presence

The ?table= filter is comma-separated and limits the stream to those tables. Each change arrives as an SSE change event:

event: change
data: {"table":"messages","type":"INSERT","row":{"id":42,"body":"hi"}}

The stream also sends a heartbeat about every 25 seconds to keep the connection alive through proxies and idle timeouts. The SDK handles all of this for you — the endpoint is here so you can see exactly what the subscription is doing, or consume it directly from a non-JS client.

What realtime is — and is not

Realtime streams row changes from your tables. That's the whole surface. It is deliberately not:

• Not a general pub/sub or broadcast bus. There's no "publish an arbitrary message to a channel" primitive.
• Not a presence service. There's no built-in "who's connected" feed.

The good news is you rarely need those as separate systems. For arbitrary server→client messaging, write to a table and subscribe to it — insert a row to send, and every subscriber gets the change. The same trick gives you presence: keep a presence table, write a heartbeat row, and subscribe to it.