Skip to content
excalibase
subscriptions
GraphQL APIstable

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