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
Consume topics, ACK messages, run agents@kalamdb/client @kalamdb/consumerTopic Consumers & ACK
Build React hooks and UI helpersplanned @kalamdb/react packageuse @kalamdb/client directly for now

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() and subscribeWithSql()
  • queryWithFiles() for FILE uploads

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.

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.
  • Future React helpers should live in a separate React-focused package instead of growing the base client.

Common Paths

I want to…Read
Run the first querySetup & Quick Start
Subscribe to rows for a UIRealtime Subscriptions
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