Quick Start
This guide takes you from zero to a working KalamDB flow:
- Run the server
- Bootstrap authentication
- Create a namespace and table
- Execute SQL
- 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
git clone https://github.com/kalamstack/KalamDB.gitcd KalamDB/backendcargo run --release --bin kalamdb-serverDefault 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
curl http://127.0.0.1:2900/v1/api/healthcheckBootstrap Authentication
Check whether the server still needs first-time setup:
curl http://127.0.0.1:2900/v1/api/auth/statusIf it returns "needs_setup": true, initialize root + DBA user:
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:
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
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');"}JSONInsert And Query
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:
npm install @kalamdb/clientPackage reference: @kalamdb/client on npm
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]);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, Firebase, Keycloak, MinIO (S3-Compatible), Jaeger, and OpenTelemetry (OTEL).