Subscriptions & Live Queries
KalamDB’s real-time engine pushes data changes to connected clients over WebSocket. This eliminates the need for polling and separate pub/sub infrastructure.
SUBSCRIBE TO
Subscribe to a table for real-time change notifications:
SUBSCRIBE TO <namespace>.<table_name>[WHERE <condition>][OPTIONS (last_rows=<n>, batch_size=<n>, from=<n>)];Options
| Option | Description |
|---|---|
last_rows=<n> | Receive the last N rows as initial data |
batch_size=<n> | Maximum rows per notification batch |
from=<n> | Resume from a specific sequence ID |
Examples
-- Subscribe to all messages in a conversationSUBSCRIBE TO chat.messagesWHERE conversation_id = 1OPTIONS (last_rows=50); -- Subscribe to typing events with batchingSUBSCRIBE TO chat.typing_eventsWHERE conversation_id = 1OPTIONS (last_rows=10, batch_size=5); -- Resume from a specific pointSUBSCRIBE TO chat.messagesWHERE conversation_id = 1OPTIONS (from=1234);KILL LIVE QUERY
Cancel an active subscription:
KILL LIVE QUERY '<subscription_id>';Using Subscriptions via SDK
The recommended way to use real-time subscriptions is via the TypeScript SDK:
import { createClient, Auth } from '@kalamdb/client'; const client = createClient({ url: 'http://localhost:2900', authProvider: async () => Auth.basic('admin', 'AdminPass123!')}); // Open live events with a SQL WHERE clauseconst unsub = await client.liveEvents( 'SELECT * FROM chat.messages WHERE conversation_id = 1', (event) => { if (event.type === 'change') { console.log('New message:', event.rows); } }, { batchSize: 50 }); // Simple table event streamconst unsubTyping = await client.liveEvents( 'SELECT * FROM chat.typing_events', (event) => { console.log('Typing:', event.change_type, event.rows); }); // Check active subscription countconsole.log(`Active: ${client.getSubscriptionCount()}`); // Cleanupawait unsub();await unsubTyping();await client.disconnect();Using Subscriptions via CLI
In the interactive CLI, use \live or \subscribe:
kalam> \live SELECT * FROM chat.messages WHERE conversation_id = 1 OPTIONS (last_rows=20);Both forms start the same live query flow. Press Ctrl+C to stop the subscription.
How It Works
- Client sends a
SUBSCRIBE TOstatement (via SQL, SDK, or WebSocket) - KalamDB registers the subscription with filter conditions
- On every
INSERT,UPDATE, orDELETEmatching the filter, a change event is pushed - Events are delivered over the persistent WebSocket connection
- Client can cancel with
KILL LIVE QUERYor disconnect
UPDATE notification payload
For UPDATE events, the notification includes:
rows: All non-null columns from the updated row, plus the primary key and_seq. This provides a full snapshot of the current row state without requiring a re-query.old_values: Only the columns that actually changed (plus PK and_seq), with their previous values.
This design makes tables usable as change triggers — when any column is updated, subscribers receive every non-null value, not just the diff.
Last updated on