Reconnect KalamDB Live Subscriptions

Keep one client for the signed-in session, show connection failures, and choose a recovery strategy that matches how your application stores its rows.

Start with a managed KalamDB subscription

1const stop = await client.liveTable('app.todos', (rows) => {2  renderTodos(rows);3});4 5// When the view is permanently removed:6await stop();

Here client is authenticated and renderTodos updates your screen. The high-level API maintains the row set. Reuse the client instead of constructing a new WebSocket connection on every render. In React, useLiveQuery() manages the view lifecycle.

Choose a recovery strategy

State you keep	Recovery approach
Rows only in memory	Let the SDK reconnect while the client remains alive. After a full app restart, load a fresh snapshot.
A durable local row cache	Persist the row changes and their matching checkpoint together, then resume using that cache.
Flutter offline application	Use kalam_sync for local reads, synchronization, and queued writes.

A saved cursor by itself is not a local database. Resuming after a cursor while starting with an empty cache can omit rows that have not changed since that cursor. If you cannot restore the matching cache, start a fresh subscription.

Scope a saved checkpoint

Keep a checkpoint with the authenticated user, query and filter parameters, table, and local schema version it belongs to. A checkpoint from one account or query must not resume another. Do not turn a checkpoint into a timestamp or increment it yourself.

The SDK represents resume positions with version-specific types. Consult the matching TypeScript lifecycle guide, Rust lifecycle guide, or Dart lifecycle guide before wiring persistence. Development SDKs expose version and domain information that older sequence-only examples may not include.

Verify recovery in your application

Open the live view and wait for its initial rows.
Interrupt that client’s network connection.
Insert, update, and delete rows from a second connection using the same account.
Restore connectivity and compare the live view with a fresh SQL query.
Repeat after restarting the app and after changing accounts.

Surface subscription errors. If the server rejects a resume position or requires a fresh snapshot, recover the view explicitly rather than continuing with stale rows. Only advance a durable checkpoint after the corresponding local writes succeed.

Next step

Inspect active subscriptions in the Admin UI →

Reference: WebSocket lifecycle and errors.

Reconnect after schema changes

Schema renames, column type changes, and rolled-back schema changes can disconnect live WebSocket subscriptions. Reconnect and create the subscription against the committed catalog and active search_path; do not keep decoding rows with a stale generated shape. Regenerate typed clients when the schema contract changes.