Realtime

Subscribe to live data changes — every INSERT, UPDATE, and DELETE on an enabled table or collection is pushed to connected clients the moment it happens. No polling.

1. Enable realtime per table

Nothing broadcasts by default. Open your project's Settings → Realtime and switch on the tables or collections your app should broadcast. This is an explicit opt-in: change events carry full row data and are delivered to anyone holding a project API key, independent of row-level security.

2. Subscribe with the SDK

import { createClient } from 'basefyio-js';

const bf = createClient({ apiUrl, projectId, apiKey });

const sub = bf.realtime.subscribe(
  { table: 'orders', event: 'INSERT' },
  (change) => {
    console.log('new order:', change.new);
  },
);

// NoSQL collections work the same way:
bf.realtime.subscribe({ collection: 'messages' }, (change) => {
  console.log(change.type, change.new ?? change.old);
});

// Stop listening:
sub.unsubscribe();

event filters by change type (INSERT, UPDATE, DELETE, or * for all — the default). Omit table/collection to receive every enabled entity's events. The SDK reconnects automatically with exponential backoff.

Change payload

{
  "eventId": "9b2f…",
  "type": "UPDATE",            // INSERT | UPDATE | DELETE
  "kind": "table",             // table | collection
  "entity": "orders",
  "new": { "id": 42, "status": "paid", … },   // null on DELETE
  "old": { "id": 42 },                         // identifying fields; null on INSERT
  "commitTimestamp": "2026-06-12T15:04:05.000Z"
}

Plain EventSource (no SDK)

const url = 'https://api.basefyio.com/api/realtime/v1/stream'
  + '?apikey=YOUR_ANON_KEY'
  + '&channels=table:orders,collection:messages';

const es = new EventSource(url);
es.addEventListener('data_change', (e) => {
  const change = JSON.parse(e.data);
  console.log(change.type, change.entity, change.new);
});

The API key travels as a query parameter because EventSource cannot set headers. A ping event arrives every 25 seconds to keep the connection alive.

What triggers events

• REST API writes (POST/PATCH/DELETE /api/rest/v1/{table})
• SDK writes (bf.from(...) inserts/updates/deletes)
• Dashboard table editor and collection document edits

Raw SQL executed in the SQL editor or from an external client does not broadcast in this version — events are produced at the API layer, not from the write-ahead log.

Node.js

Node 22+ ships a global EventSource. On older versions install a polyfill (e.g. eventsource) and assign it to globalThis.EventSource before calling bf.realtime.subscribe().

See the SDK reference for the full client API.