Skip to Content
Setup & Quick Start

Setup & Quick Start

Status: The TypeScript SDK is in beta.

This page gets you from install to first query. Pick the package set that matches the code you are writing.

Pick the right package

If you are writing…Install
UI, service, or script that runs SQL@kalamdb/client
Typed Drizzle table code@kalamdb/client @kalamdb/orm drizzle-orm
Background worker or agent@kalamdb/client @kalamdb/consumer

Looking for Rust instead? Use the Rust SDK.

Install

App client only

BASH
npm i @kalamdb/client

App client plus worker runtime

BASH
npm i @kalamdb/client @kalamdb/consumer

App client plus Drizzle ORM

BASH
npm i @kalamdb/client @kalamdb/orm drizzle-orm

Runtime requirements:

  • Node.js >= 18 (or a modern browser for @kalamdb/client)
  • running KalamDB server (http://localhost:2900 by default)

Quick start: @kalamdb/client

Copy this into a script after KalamDB is running locally.

TS
import { Auth, createClient } from '@kalamdb/client'; const client = createClient({  url: 'http://localhost:2900',  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),}); const result = await client.query('SELECT CURRENT_USER()');console.log(result.status, result.results?.[0]); await client.disconnect();

Notes:

  • query() works over HTTP and does not require a WebSocket connection.
  • When using Auth.basic(user, password), the SDK only sends those credentials to POST /v1/api/auth/login, then switches authenticated requests and WebSocket traffic to JWT automatically.
  • The high-level SDK manages the WebSocket lifecycle automatically. connect() is public for eager or manual reconnect flows, but most apps do not need to call it directly.
  • With the default wsLazyConnect: true, the first subscription call opens the shared socket automatically.

Start a live query

TS
const inboxSql = `  SELECT id, room, role, body, created_at  FROM support.inbox  WHERE room = 'main'`; const stop = await client.live(  inboxSql,  (rows) => {    renderInbox(rows);  },  {    lastRows: 100,  },); await stop();await client.disconnect();

Notes:

  • live() is the recommended UI API because it gives you the current materialized row set directly.
  • Use liveEvents() only when you need raw low-level events such as subscription_ack or change frames.
  • Keep live SQL in SELECT ... FROM ... WHERE ... form without ORDER BY or LIMIT.

Parameterized queries

Use $1, $2, … placeholders:

TS
const filtered = await client.query(  'SELECT * FROM app.messages WHERE conversation_id = $1 AND is_deleted = $2',  ['conv_42', false],);

Optional WASM path override

In environments where auto-WASM resolution fails, pass wasmUrl:

TS
const client = createClient({  url: 'http://localhost:2900',  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),  wasmUrl: '/wasm/kalam_client_bg.wasm',});

Quick start: @kalamdb/consumer

Use a separate worker client when you need topic polling or agents. This package is for Node.js worker processes, not browser bundles.

TS
import { Auth } from '@kalamdb/client';import { createConsumerClient } from '@kalamdb/consumer'; const worker = createConsumerClient({  url: 'http://localhost:2900',  authProvider: async () => Auth.basic('worker', 'Secret123!'),}); const handle = worker.consumer({  topic: 'orders',  group_id: 'billing',  auto_ack: true,  batch_size: 10,}); await handle.run(async (ctx) => {  console.log(ctx.message.offset, ctx.message.value);});

The consumer client reuses the same auth model as @kalamdb/client, but adds topic-specific APIs:

  • consumer({...}).run(...)
  • consumeBatch(...)
  • ack(...)
  • runConsumer(...)

If WASM auto-resolution fails in the worker runtime, use consumerWasmUrl.

Quick start: @kalamdb/orm

Use this path when you want generated tables or Drizzle queries.

Generate a Drizzle schema from a running KalamDB server:

BASH
npx kalamdb-orm \  --url http://localhost:2900 \  --user admin \  --password AdminPass123! \  --namespace app \  --out src/db/schema.ts

For local development, pair that generator with the CLI schema watcher so DDL changes rerun your script automatically:

BASH
kalam --watch-schema --namespace app --run "npm run schema:gen" --run-on-start

Then use the generated tables with the driver:

TS
import { Auth, createClient } from '@kalamdb/client';import { kalamDriver } from '@kalamdb/orm';import { messages } from './db/schema'; const client = createClient({  url: 'http://localhost:2900',  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),}); const db = kalamDriver(client);const rows = await db.select().from(messages).limit(20);

Common startup pitfalls

  • For local dev auth, confirm server credentials and URL first.
  • If browser bundling cannot find the client WASM file, provide wasmUrl explicitly.
  • If the worker runtime cannot find the consumer WASM file, provide consumerWasmUrl explicitly.
  • Set wsLazyConnect: false only when you want the app client’s WebSocket established eagerly.

Next

App-facing docs

Worker docs

Last updated on
OverviewAuthentication