Realtime

Scribase Realtime provides WebSocket subscriptions over Postgres logical replication. Clients subscribe to table changes, broadcast messages, or track presence — all through a single WebSocket connection.

Channels

A channel is a named subscription topic. Three channel types are supported:

Type	Description
`postgres_changes`	Subscribe to INSERT/UPDATE/DELETE on a Postgres table
`broadcast`	Pub/sub message passing between clients
`presence`	Track which clients are online in a channel

Subscribing to database changes

TypeScript

import { createClient } from '@supabase/supabase-js';

const scribase = createClient(
  'https://<your-project-url>',
  '<anon-key>'
);

scribase
  .channel('orders')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'orders' },
    (payload) => {
      console.log('Change received!', payload);
    }
  )
  .subscribe();

The event filter can be '*', 'INSERT', 'UPDATE', or 'DELETE'.

Row-level filtering

Subscriptions respect RLS policies — clients only receive changes for rows their JWT is authorized to see.

You can also add a filter string for server-side filtering:

TypeScript

.on('postgres_changes', {
  event: 'INSERT',
  schema: 'public',
  table: 'messages',
  filter: 'channel_id=eq.42',
}, handler)

Broadcast

Send messages to all subscribers of a channel without touching the database:

TypeScript

const channel = scribase.channel('room:42');

channel.on('broadcast', { event: 'typing' }, (payload) => {
  console.log(payload.userId, 'is typing');
});

await channel.subscribe();

// Send
channel.send({ type: 'broadcast', event: 'typing', payload: { userId: 'alice' } });

Presence

Track which clients are currently subscribed to a channel:

TypeScript

const channel = scribase.channel('room:42');

channel.on('presence', { event: 'sync' }, () => {
  const state = channel.presenceState();
  console.log('Online users:', state);
});

await channel.subscribe();
await channel.track({ user: 'alice', online_at: new Date().toISOString() });

RLS and security

Realtime respects your Postgres RLS policies. A subscriber only receives events for rows they can SELECT.
For public events (no auth), use a public table or an open policy.
The anon key authorizes subscriptions as the anonymous role.

HTTP API (management)

The realtime management API is accessible via the SDK:

TypeScript

const { channels } = await scribase.realtime.listChannels(ref);

Local development

scribase dev starts the Realtime service automatically. Connect to:

ws://localhost:8000/realtime/v1/websocket?apikey=<anon-key>