Skip to Content
Getting StartedQuick Start

Quick Start

This guide takes you from zero to a working KalamDB flow:

  1. Run the server
  2. Bootstrap authentication
  3. Create a namespace and table
  4. Execute SQL
  5. Connect from the TypeScript SDK or CLI

Use this path if you want the fastest route into a working local KalamDB setup before moving into the TypeScript SDK, HTTP API, PostgreSQL extension, or production guides.

Prerequisites

  • Git
  • Rust 1.92+ for source builds, or Docker

Option 1: Build From Source

BASH
git clone https://github.com/kalamdb/KalamDB.gitcd KalamDB/backendcargo run --release --bin kalamdb-server

Default server address is http://127.0.0.1:2900.

Option 2: Docker

Use the official compose files in the KalamDB repo:

  • single node: docker/run/single/docker-compose.yml
  • cluster: docker/run/cluster/docker-compose.yml

Detailed steps: Docker Deployment

Verify Health

BASH
curl http://127.0.0.1:2900/v1/api/healthcheck

Bootstrap Authentication

Check whether the server still needs first-time setup:

BASH
curl http://127.0.0.1:2900/v1/api/auth/status

If it returns "needs_setup": true, initialize root + DBA user:

BASH
curl -X POST http://127.0.0.1:2900/v1/api/auth/setup \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}'

If the server is already configured, this endpoint returns conflict; in that case, go directly to login.

Then log in:

BASH
curl -X POST http://127.0.0.1:2900/v1/api/auth/login \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!"}'

Keep the returned access_token for API calls.

Create Namespace And Table

BASH
TOKEN="<ACCESS_TOKEN>" curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"sql":"CREATE NAMESPACE IF NOT EXISTS app;"}' curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d @- <<'JSON'{"sql":"CREATE TABLE app.messages (id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(), sender TEXT NOT NULL, content TEXT NOT NULL, created_at TIMESTAMP DEFAULT NOW()) WITH (TYPE='USER', FLUSH_POLICY='rows:1000,interval:60');"}JSON

Insert And Query

BASH
curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d @- <<'JSON'{"sql":"INSERT INTO app.messages (sender, content) VALUES ('alice', 'Hello KalamDB');"}JSON curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"sql":"SELECT * FROM app.messages ORDER BY created_at DESC LIMIT 10;"}'

Connect With TypeScript SDK (@kalamdb/client)

Install the package first:

BASH
npm install @kalamdb/client

Package reference: @kalamdb/client on npm

TS
import { createClient, Auth } from '@kalamdb/client'; const client = createClient({  url: 'http://127.0.0.1:2900',  authProvider: async () => Auth.jwt('<ACCESS_TOKEN>'),}); const res = await client.query('SELECT * FROM app.messages LIMIT 5');console.log(res.results[0]);

Connect With Kalam CLI

Install the CLI with npm or the curl installer:

BASH
npm install -g @kalamdb/cli # orcurl -fsSL https://kalamdb.org/install.sh | sh

Log in and run a query:

BASH
kalam login --instance local --url http://127.0.0.1:2900 --user admin --passwordkalam -c "SELECT * FROM app.messages ORDER BY created_at DESC LIMIT 5;"kalam doctor

If you want to test the OIDC flow instead of local password login:

BASH
kalam login --instance local --url http://127.0.0.1:2900 --oidckalam login --instance local --url http://127.0.0.1:2900 --oidc --no-browser

Full CLI reference: CLI Guide

Use KalamDB Skills With Coding Agents

Install the official KalamDB skill for Codex, Claude Code, OpenCode, and Agent Skills-compatible tools:

BASH
npx skills add kalamdb/kalamdb-skills

Choose Your Next Track

Building an app or AI-agent backend in TypeScript

Continue with TypeScript Setup, Authentication, Querying & DML, and Realtime Subscriptions.

Building background workers and agent automation

Continue with Topic Consumers & ACK, Consumer Runtime, and AI Agent Coding Guidelines.

Integrating through PostgreSQL

Continue with PostgreSQL Extension Getting Started, SQL Syntax, and Data Type Conversions.

Hardening for production

Continue with Authentication & Bootstrap, Configuration, Security, and OIDC & Issuer Trust.

Advanced features and integrations

Continue with SQL Reference, Vector Search, Dex, OIDC & Issuer Trust, MinIO (S3-Compatible), Jaeger, and OpenTelemetry (OTEL).

Last updated on
OverviewAI Agent Coding Guidelines