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

git clone https://github.com/kalamstack/KalamDB.git
cd KalamDB/backend
cargo run --release --bin kalamdb-server

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

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:8080/v1/api/healthcheck

Bootstrap Authentication

Check whether the server still needs first-time setup:

curl http://127.0.0.1:8080/v1/api/auth/status

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

curl -X POST http://127.0.0.1:8080/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:8080/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:8080/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:8080/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

curl -X POST http://127.0.0.1:8080/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:8080/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/client

Package reference: @kalamdb/client on npm 

import { createClient, Auth } from '@kalamdb/client';
 
const client = createClient({
  url: 'http://127.0.0.1:8080',
  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, Agent 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).

Last updated on
OverviewAI Agent Coding Guidelines

Getting Started

Documentation

Resources

Community

© 2026 KalamDB. All rights reserved.
PrivacyTerms