React Live Queries

@kalamdb/react turns a KalamDB live query into React rows and state. Start with useLiveQuery: the hook owns subscription setup and cleanup, while your component renders loading, empty, error, and data states.

Prepare the live-query example

Create the app.live_messages table from the TypeScript inbox setup, then install:

BASH

1npm install @kalamdb/client @kalamdb/react @kalamdb/orm drizzle-orm

These examples target a React TypeScript app. In Next.js, put the provider and query components behind a 'use client' boundary. Pass the URL and your auth integration’s token getter from the application; never bundle an admin password.

One client per signed-in session

TSX

1'use client';2 3import { useState } from 'react';4import { Auth, createClient } from '@kalamdb/client';5import { KalamProvider } from '@kalamdb/react';6import { MessagesPane } from './MessagesPane';7 8type AppProps = {9  url: string;10  getAccessToken: () => Promise<string>;11};12 13export function App({ url, getAccessToken }: AppProps) {14  const [client] = useState(() => createClient({15    url,16    authProvider: async () => Auth.jwt(await getAccessToken()),17    onDisconnect: (reason) => console.warn('Connection interrupted:', reason.message),18    onConnectionError: (error) => console.error('Connection:', error.message),19  }));20 21  return (22    <KalamProvider client={client}>23      <MessagesPane key="main" roomId="main" />24    </KalamProvider>25  );26}

The auth integration must return a current token, including after refresh. Keep the client stable across ordinary renders. When the signed-in account changes, unmount its query tree, disconnect its client, and create a client for the new session. KalamProvider supplies context; it does not own disconnecting your client.

Define the typed table

Use the schema generator in an existing project, or copy this definition for the example table. Declaring a TypeScript table does not create the server table.

1import { kTable } from '@kalamdb/orm';2import { text } from 'drizzle-orm/pg-core';3 4export const messages = kTable.user('app.live_messages', {5  id: text('id').primaryKey(),6  room: text('room').notNull(),7  body: text('body').notNull(),8});

Render rows and handle writes

TSX

1'use client';2 3import { useState } from 'react';4import { useLiveQuery } from '@kalamdb/react';5import { asc, eq } from 'drizzle-orm';6import { messages } from './schema';7 8export function MessagesPane({ roomId }: { roomId: string }) {9  const [draft, setDraft] = useState('');10  const [actionError, setActionError] = useState<string>();11  const { rows, state, insert, update, remove, clearError, refetch } = useLiveQuery({12    table: messages,13    where: (table) => eq(table.room, roomId),14    orderBy: (table) => asc(table.id),15    limit: 100,16    deps: [roomId],17  });18 19  // Mutations set state.error AND reject. Catch every event-handler promise.20  async function run(action: () => Promise<void>) {21    setActionError(undefined);22    clearError();23    try { await action(); }24    catch (error) {25      setActionError(error instanceof Error ? error.message : String(error));26    }27  }28 29  const error = actionError ?? state.error?.message;30  const canWrite = state.status === 'live' && !state.loading;31 32  return (33    <section aria-label="Inbox">34      {state.loading && <p role="status">Loading messages…</p>}35      {error && <p role="alert">{error}</p>}36      {state.status === 'error' && rows.length > 0 && (37        <p>Showing the last received messages; they may be out of date.</p>38      )}39      <button40        type="button"41        disabled={state.loading}42        onClick={() => { void run(refetch); }}43      >44        Reload messages45      </button>46      <button type="button" onClick={() => {47        clearError();48        setActionError(undefined);49      }}>50        Dismiss write error51      </button>52      {!state.loading && !error && state.status === 'live' && rows.length === 0 && (53        <p>No messages yet. Send the first one.</p>54      )}55      <ul>56        {rows.map((row) => (57          <li key={row.id}>58            {row.body}59            <button60              type="button"61              disabled={!canWrite || state.updating.has(row.id) || state.deleting.has(row.id)}62              onClick={() => { void run(() => update(messages, row.id).set({ body: `${row.body}!` })); }}63            >64              {state.updating.has(row.id) ? 'Saving…' : 'Add !'}65            </button>66            <button67              type="button"68              disabled={!canWrite || state.updating.has(row.id) || state.deleting.has(row.id)}69              onClick={() => { void run(() => remove(messages, row.id)); }}70            >71              {state.deleting.has(row.id) ? 'Deleting…' : 'Delete'}72            </button>73          </li>74        ))}75      </ul>76      <form onSubmit={(event) => {77        event.preventDefault();78        const body = draft.trim();79        if (!body || state.inserting || !canWrite) return;80        void run(async () => {81          await insert(messages).values({ id: crypto.randomUUID(), room: roomId, body });82          setDraft(''); // Keep the draft if the write fails.83        });84      }}>85        <label>86          Message87          <input value={draft} onChange={(event) => setDraft(event.target.value)} disabled={state.inserting} />88        </label>89        <button disabled={!canWrite || state.inserting || !draft.trim()}>90          {state.inserting ? 'Sending…' : 'Send'}91        </button>92      </form>93    </section>94  );95}

Open the screen twice with the same user. Send a message in one, edit it in the other, then delete it. Both lists should follow the server changes. These helpers send writes; the live subscription supplies the resulting rows. The example does not add an optimistic local row.

Understand state, errors, and retries

Value	How to use it
`rows`	Current materialized rows; replace the rendered list rather than merging whole snapshots yourself
`state.loading`	Show startup/reload progress; an empty array during loading is not an empty result
`state.status`	Controller state: `idle`, `loading`, `live`, `reconnecting`, `error`, or `disposed`
`state.error`	Latest mutation error, otherwise the live-controller error
`state.inserting`	Disable a repeated send while a write is pending
`state.updating` / `state.deleting`	Sets of row keys for pending mutations
`clearError()`	Clear the mutation error only; it does not repair a failed subscription
`refetch()`	Restart the live subscription; call after fixing a table, query, or permission problem

A transient connection interruption is different from invalid SQL, missing tables, or denied access. Let the SDK manage transport reconnects. Fix permanent causes before using Reload. Do not blindly retry writes: a lost response does not prove the server rejected the write.

state.connected and state.status describe the live controller, not a complete transport-health monitor. The current hook does not forward every socket disconnect into its snapshot. Use the client’s connection callbacks for an application-wide offline indicator; do not treat state.connected as proof of freshness. Retained rows may remain visible while a reload is underway.

To test error handling, temporarily change the table name to a missing table. The screen should show an error, not “No messages yet.” Restore the schema and reload/remount. Test a rejected write with an identity that lacks write access: keep the input, show the error, and avoid an unhandled promise rejection. See authentication for credential refresh.

Filters, ordering, and cleanup

Put captured filter values in deps. Use Drizzle eq(table.room, roomId) instead of interpolating untrusted input into SQL. The hook cleans up its old subscription when its query changes and on unmount.

When switching rooms, render <MessagesPane key={roomId} roomId={roomId} /> to reset the component’s draft and old rows immediately. For an account switch, replace the session client too.

orderBy sorts locally and limit selects displayed rows; the matching row set remains retained so a deletion can reveal the next row. This is not a server-side memory bound. Narrow where for large datasets. The underlying subscription uses the supported SELECT ... FROM ... WHERE ... shape.

Do not disconnect the shared client in every list component. The application/session owner is responsible for it.

Raw SQL and render-prop alternatives

For fixed SQL without Drizzle models, use LiveQuery. Raw rows use typed cell accessors:

TSX

1import { LiveQuery } from '@kalamdb/react';2 3export function SqlMessagesPane() {4  return (5    <LiveQuery query="SELECT id, body FROM app.live_messages WHERE room = 'main'" getKey="id">6      {({ rows, state }) => (7        <section>8          {state.loading && <p>Loading…</p>}9          {state.error && <p role="alert">{state.error.message}</p>}10          {!state.loading && !state.error && rows.length === 0 && <p>No messages yet.</p>}11          {rows.map((row) => <p key={row.id.asString()}>{row.body.asString()}</p>)}12        </section>13      )}14    </LiveQuery>15  );16}

LiveQuery also accepts the typed table, where, orderBy, limit, and deps options from the hook. Raw SQL mode does not expose a params option; prefer typed predicates for dynamic values.

Multiple queries and derived views

useLiveQueries and LiveQueries create one controller per named dataset. Inspect a dataset’s own error when one panel fails; the aggregate state alone cannot explain which query failed.

TSX

1import { useLiveQueries, useLiveSelection } from '@kalamdb/react';2import { eq } from 'drizzle-orm';3import { messages } from './schema';4 5export function RoomCounts() {6  const live = useLiveQueries({7    queries: {8      main: { table: messages, where: (table) => eq(table.room, 'main') },9      support: { table: messages, where: (table) => eq(table.room, 'support') },10    },11  });12  const count = useLiveSelection(live, (context) => context.main.rows.length);13  return (14    <section>15      <p>{live.main.state.loading ? 'Loading main…' : `${count} main messages`}</p>16      {live.main.state.error && <p role="alert">Main: {live.main.state.error.message}</p>}17      {live.support.state.error && <p role="alert">Support: {live.support.state.error.message}</p>}18    </section>19  );20}

Use select on useLiveQuery to derive one view from its context. useMutationActions(client) provides mutations without opening a query; useMutationState exposes the mutation-state reducer for custom integrations. Neither adds an offline outbox.