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
Prerequisites
- Git
- Rust
1.92+for source builds, or Docker
Option 1: Build From Source
git clone https://github.com/jamals86/KalamDB.git
cd KalamDB/backend
cargo run --release --bin kalamdb-serverDefault 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/healthcheckBootstrap Authentication
On first boot, initialize root + DBA user:
curl -X POST http://127.0.0.1:8080/v1/api/auth/setup \
-H 'Content-Type: application/json' \
-d '{"username":"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 '{"username":"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');"}
JSONInsert 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 (kalam-link)
Install the package first:
npm install kalam-linkPackage reference: kalam-link on npm
import { createClient, Auth } from 'kalam-link';
const client = createClient({
url: 'http://127.0.0.1:8080',
auth: Auth.jwt('<ACCESS_TOKEN>'),
});
await client.connect();
const res = await client.query('SELECT * FROM app.messages LIMIT 5');
console.log(res.results[0]);Next Steps
Last updated on