Skip to Content
Overview

TypeScript SDK Packages

KalamDB has separate TypeScript packages for separate jobs. Pick one package path, copy the first example, then move to the package docs when you need more detail.

Which Package Should I Use?

JobInstallStart here
Query SQL, login, upload files, subscribe to rows@kalamdb/clientSetup & Quick Start
Use Drizzle tables or generate schema.ts@kalamdb/client @kalamdb/orm drizzle-ormDrizzle ORM & Generator
Build React live-query hooks and components@kalamdb/client @kalamdb/react plus @kalamdb/orm drizzle-orm for typed modeReact Live Queries
Consume topics, ACK messages, run agents@kalamdb/client @kalamdb/consumerTopic Consumers & ACK
Install the terminal CLI through npmnpm install -g @kalamdb/cliKalam CLI

@kalamdb/cli is published from the TypeScript package tree because npm is one of the supported distribution channels, but it is documented with the server guides because it is an operational client rather than an in-app SDK dependency.

Fast Start: App Client

Use @kalamdb/client in browser apps, Next.js apps, scripts, and API services.

BASH
npm i @kalamdb/client

Copy this smoke test:

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();

Use it for:

  • query(), queryOne(), queryAll(), and queryRows()
  • login() and refreshToken()
  • live(), liveTable(), and liveEvents()
  • queryWithFiles() for FILE uploads

Realtime subscriptions have two documented usage modes in the client API:

  • simple: use live() or liveTable() and let the SDK materialize the latest row set for you. Read: Simple Realtime Mode
  • advanced: use liveEvents() when you want raw events, change_type, and batch metadata. Read: Advanced Realtime Mode

Fast Start: ORM Package

Use @kalamdb/orm when you want typed tables and Drizzle-style queries. It sits on top of @kalamdb/client; it is not a second connection layer.

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

Generate a 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

Keep that file fresh in local dev with the CLI schema watcher:

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

Query with the generated table:

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);console.log(rows);

Read next: Drizzle ORM & Generator.

Fast Start: Consumer Package

Use @kalamdb/consumer only in workers or agents that consume topics. Keep this code out of browser bundles.

BASH
npm i @kalamdb/client @kalamdb/consumer

Copy this worker skeleton:

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.events',  group_id: 'billing-worker',  auto_ack: false,  batch_size: 10,}); await handle.run(async (ctx) => {  await processOrder(ctx.message.payload);  await ctx.ack();});

Read next: Topic Consumers & ACK and Consumer Runtime.

Fast Start: React Package

Use @kalamdb/react when a React app wants live rows, typed mutations, aggregate multi-query state, or assistant workflow composition.

BASH
npm i @kalamdb/client @kalamdb/react react react-domnpm i @kalamdb/orm drizzle-orm
TSX
import { LiveQueries } from '@kalamdb/react';import { asc, eq } from 'drizzle-orm';import { messages, typing } from './schema.generated'; <LiveQueries  queries={{    messages: {      table: messages,      where: (table) => eq(table.conversationId, conversationId),      orderBy: (table) => asc(table.createdAt),      deps: [conversationId],    },    typing: {      table: typing,      where: (table) => eq(table.conversationId, conversationId),      deps: [conversationId],    },  }}>  {({ messages, typing, state }) => <ChatView messages={messages.rows} typing={typing.rows} busy={state.loading} />}</LiveQueries>

Read next: React Live Queries.

How Packages Work Together

Use this split in real projects:

  • UI code imports @kalamdb/client.
  • Typed table code imports @kalamdb/orm plus the app client.
  • Worker code imports @kalamdb/consumer.
  • React helpers live in @kalamdb/react so the base client stays framework-neutral.

Common Paths

I want to…Read
Run the first querySetup & Quick Start
Subscribe to rows for a UIRealtime Subscriptions, Simple Realtime Mode, and Advanced Realtime Mode
Build a React live-query screenReact Live Queries
Generate typed tablesDrizzle ORM & Generator
Build a topic workerTopic Consumers & ACK
Build a retrying workerConsumer Runtime
Copy full example flowsExamples and Cookbook
Last updated on
Setup & Quick Start