Real-Time Subscriptions
Every table a role can read has a ...Changes subscription that delivers its INSERT, UPDATE and
DELETE events as they happen. Events travel over the same path as queries,
wss://api.excalibase.io/{projectId}/graphql, using the graphql-transport-ws protocol.
On Excalibase Cloud
The subscription field is the table's query field plus Changes: publicFeedbackPostsChanges for
public.feedback_posts. A table of the project's default schema may also be named without the
schema prefix (feedbackPostsChanges). A field that names no table the role can read is refused
with an error message instead of being subscribed silently.
subscription {
publicFeedbackPostsChanges {
operation # INSERT | UPDATE | DELETE
table
data # the row, cut to the role's columns; for UPDATE, { old, new }
timestamp # ISO-8601 UTC
}
}
Each change reaches only callers whose permissions cover the row, with only the columns their role can read. Realtime must be enabled for the table.
Browser or Node, with the SDK
The SDK sends the current session's token in connection_init and refreshes it for you:
import { createClient } from '@excalibase/sdk'
import WebSocket from 'ws' // Node before 22 has no global WebSocket; browsers do not need this
const PUBLISHABLE_KEY = 'esk_pub_live_Tb2pe6iauenJiWtTdBDMbeMp'
const db = createClient({
url: 'https://api.excalibase.io',
projectId: 'proj-jfp7kx46kb',
key: PUBLISHABLE_KEY,
WebSocket,
})
await db.auth.signInWithApiKey()
const subscription = db.graphql.subscribe(
'subscription { publicFeedbackPostsChanges { operation table data timestamp } }',
{
next: (message) => console.log(message.publicFeedbackPostsChanges),
error: (error) => console.warn(error),
},
)
// later: subscription.unsubscribe()
Any graphql-transport-ws client
Connect to the URL above with the subprotocol graphql-transport-ws, send
{"type":"connection_init","payload":{"Authorization":"Bearer <token>"}}, wait for
connection_ack, then send a subscribe message with the subscription as its query.
A browser cannot set headers on a WebSocket, which is why the token goes in the payload.
A request with no token subscribes as anon.
Event shapes
An INSERT carries the row; an UPDATE carries { old, new }; a DELETE carries the row's key (the
whole row when the table's REPLICA IDENTITY is FULL, which enabling realtime sets):
{ "operation": "INSERT", "table": "feedback_posts", "timestamp": "2026-10-07T10:00:00Z",
"data": { "id": "7", "kind": "idea", "body": "Dark mode", "author_name": "Ada" } }
Timestamps in data are formatted like REST and GraphQL queries return them
(2026-10-07T10:00:00.123+00:00).
Self-hosting
This section is for running the engine yourself: the realtime path is excalibase-watcher and NATS,
which a cloud project already has. The browser-facing endpoint is the same
(ws://localhost:10000/graphql for a standalone engine).
How it works
Database change (INSERT / UPDATE / DELETE)
↓
WAL (PostgreSQL) or Binlog (MySQL)
↓
excalibase-watcher (CDC server)
↓
NATS JetStream (cdc.{schema}.{table})
↓
excalibase-graphql (NatsCDCService)
↓
GraphQL subscription (WebSocket)
↓
Client
The watcher owns the replication slot / binlog connection. Excalibase-graphql is a pure NATS consumer — this means you can scale horizontally without duplicate CDC events.
DDL changes (CREATE TABLE, ALTER TABLE, etc.) are also captured and automatically invalidate the GraphQL schema cache — no restart needed.
Setup
1. Enable logical replication (PostgreSQL)
-- postgresql.conf
wal_level = logical
max_replication_slots = 5
max_wal_senders = 5
The provided docker-compose.yml already has this configured, along with NATS and excalibase-watcher.
2. Configure NATS connection
app:
nats:
enabled: true
url: nats://localhost:4222
stream-name: CDC
subject-prefix: cdc
REPLICA IDENTITY
Controls how much data appears in UPDATE/DELETE events:
-- Default: UPDATE/DELETE only include primary key
ALTER TABLE customer REPLICA IDENTITY DEFAULT;
-- Full: UPDATE/DELETE include all column values
ALTER TABLE customer REPLICA IDENTITY FULL;
Recommendation: use REPLICA IDENTITY FULL for tables where clients need the full row on DELETE or before/after values on UPDATE.
Horizontal scaling
Because excalibase-watcher owns the single replication slot and publishes to NATS, you can run multiple excalibase-graphql pods behind a load balancer. Each pod receives every event via NATS fan-out — no duplicate replication slots, no duplicate events.
Related
- excalibase-watcher documentation — CDC server setup and configuration
- excalibase-watcher on GitHub