KalamDB

https://kalamdb.org
Admin
KalamDB is a SQL-first realtime database designed for high-concurrency app workloads and agent...
Tokens:194,838
Snippets:2,432
Trust Score:7.5
Update:3 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- You are assisting developers building with KalamDB.  Primary source of truth: - Use KalamDB docs from this site first. - Prefer official docs examples and syntax over generic assumptions.  Behavior: - Give production-ready, concise answers with copy-paste

================
CODE SNIPPETS
================
### Install Dependencies and Setup Example

Source: https://kalamdb.org/docs/use-cases/chat-with-ai

Installs project dependencies and runs the setup script for the chat-with-ai example.

```bash
cd examples/chat-with-ai
npm install
npm run setup
```

--------------------------------

### Running the Simple TypeScript Example

Source: https://kalamdb.org/docs/ts-sdk/examples

Instructions to set up and run the Simple TypeScript example, which demonstrates real-time operations and browser authentication. This includes installing dependencies and starting the development server.

```bash
cd examples/simple-typescript
npm install
npm run setup
npm run dev
```

--------------------------------

### Run Quickstart Example

Source: https://kalamdb.org/docs/rust-sdk/examples/quickstart

Navigate to the example directory, set environment variables for server URL and password, and run the Cargo project.

```bash
1cd link/sdks/rust2export KALAMDB_SERVER_URL=http://localhost:29003export KALAMDB_ROOT_PASSWORD=kalamdb1234cargo run -p quickstart
```

--------------------------------

### Running the React AI Chat Example

Source: https://kalamdb.org/docs/ts-sdk/examples

Instructions to set up and run the React AI Chat example locally. This includes installing dependencies, setting up the database, and starting the development server.

```bash
cd examples/react-ai-chat
npm install
npm run setup
npm run agent
npm run dev
```

--------------------------------

### Quickstart Example Output

Source: https://kalamdb.org/docs/rust-sdk/examples/quickstart

The expected output shows the status of the query and the current user row.

```text
1status: Ok2current user row: ...
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://kalamdb.org/docs/use-cases/react-ai-chat

Installs project dependencies and starts the local KalamDB server along with the application and agent processes. Open the provided Vite URL to access the chat application.

```bash
cd examples/react-ai-chat
npm install
kalam dev
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://kalamdb.org/docs/use-cases/realtime-ops-feed

Installs project dependencies, sets up the KalamDB environment (namespace, table, user, .env.local), and starts the development server.

```bash
1cd examples/simple-typescript
2npm install
3npm run setup
4npm run dev
```

--------------------------------

### Setup and Run Chat AI Agent

Source: https://kalamdb.org/docs/ts-sdk/examples

Commands to install dependencies, set up the database, and run the AI agent and development server for the chat-with-ai example.

```bash
1cd examples/chat-with-ai
2npm install
3npm run setup
4npm run agent
5npm run dev
```

--------------------------------

### Install and Run React AI Chat App

Source: https://kalamdb.org/docs/ts-sdk/react

Steps to install dependencies, set up the environment, and run the React AI chat example. For browser-only demo mode, set VITE_KALAMDB_DEMO_MODE=true in .env.local.

```bash
1cd examples/react-ai-chat2npm install3npm run setup4npm run agent5npm run dev
```

```bash
1VITE_KALAMDB_DEMO_MODE=true
```

```bash
1npm run build2npm test
```

--------------------------------

### Rust Quickstart Example Source

Source: https://kalamdb.org/docs/rust-sdk/examples/quickstart

This Rust code connects to KalamDB, authenticates using environment variables, executes a 'SELECT CURRENT_USER()' query, prints the result, and disconnects.

```rust
1use std::time::Duration;2 3use kalam_client::{AuthProvider, KalamLinkClient};4 5fn server_url() -> String {6    std::env::var("KALAMDB_SERVER_URL").unwrap_or_else(|_| "http://localhost:2900".to_string())7}8 9fn auth() -> AuthProvider {10    let password =11        std::env::var("KALAMDB_ROOT_PASSWORD").unwrap_or_else(|_| "kalamdb123".to_string());12    AuthProvider::system_user_auth(password)13}14 15#[tokio::main]16async fn main() -> Result<(), Box<dyn std::error::Error>> {17    let client = KalamLinkClient::builder()18        .base_url(server_url())19        .auth(auth())20        .timeout(Duration::from_secs(30))21        .build()?;22 23    let response = client24        .execute_query("SELECT CURRENT_USER()", None, None, None)25        .await?;26 27    println!("status: {:?}", response.status);28    if let Some(result) = response.results.first() {29        if let Some(rows) = &result.rows {30            for row in rows {31                println!("current user row: {{row:?}}");32            }33        }34    }35 36    client.disconnect().await;37    Ok(())38}
```

--------------------------------

### Initialize a new Kalam project

Source: https://kalamdb.org/docs/cli

Use `kalam init` to start a new project. Specify project name, languages, and package manager for automated setup.

```bash
kalam init
```

```bash
kalam init --yes --name my-app --languages typescript --package-manager pnpm
```

--------------------------------

### Check and Perform Server Setup

Source: https://kalamdb.org/docs/rust-sdk/health-setup

Check the setup status and initiate server setup if needed. `login` may return `KalamLinkError::SetupRequired` if setup is pending.

```rust
let status = client.check_setup_status().await?;
if status.needs_setup {
    let response = client.server_setup(server_setup_request).await?;
}
```

--------------------------------

### Manually complete dependency installation after scaffolding

Source: https://kalamdb.org/docs/cli/init

If dependency installation fails during `kalam init`, navigate to the project directory and run the package manager's install command manually, then start the development server.

```bash
cd my-app
pnpm install   # or npm / yarn / bun install
kalam dev
```

--------------------------------

### Quick Start: Connect and Execute Query with KalamDB Client

Source: https://kalamdb.org/docs/rust-sdk

A basic Rust example demonstrating how to build a KalamLinkClient, connect to a KalamDB instance, execute a SQL query, and print the results. Ensure the KalamDB server is running and accessible.

```rust
use std::time::Duration;
use kalam_client::{AuthProvider, KalamLinkClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KalamLinkClient::builder()
        .base_url("http://localhost:2900")
        .auth(AuthProvider::basic_auth("admin".into(), "kalamdb123".into()))
        .timeout(Duration::from_secs(30))
        .build()?;

    let response = client
        .execute_query("SELECT CURRENT_USER()", None, None, None)
        .await?;

    if response.success() {
        println!("rows: {:?}", response.rows_as_maps());
    }

    client.disconnect().await;
    Ok(())
}
```

--------------------------------

### Install KalamDB CLI with install.sh

Source: https://kalamdb.org/docs/cli/setup

Installs the KalamDB CLI using a shell script. This is a common method for quick setup.

```bash
curl -fsSL https://kalamdb.org/install.sh | sh
```

--------------------------------

### Running the Live Inbox Example

Source: https://kalamdb.org/docs/rust-sdk/examples/live-inbox

Navigate to the example directory, set necessary environment variables for the KalamDB server, and run the Rust example using Cargo.

```bash
1cd link/sdks/rust/examples/live-inbox
2export KALAMDB_SERVER_URL=http://localhost:29003
3export KALAMDB_ROOT_PASSWORD=kalamdb1234
4cargo run -p live-inbox
```

--------------------------------

### Run KalamDB Summarizer Agent

Source: https://kalamdb.org/docs/ts-sdk/examples

Example of how to install, set up, and start a worker-only KalamDB summarizer agent. This is useful when a browser is not needed.

```bash
1cd examples/summarizer-agent2npm install3npm run setup4npm run start
```

--------------------------------

### Quick Start Project Initialization

Source: https://kalamdb.org/docs/cli/init

Initializes a new KalamDB project and starts the development server. Assumes you are in the desired project directory.

```bash
1mkdir my-app && cd my-app2kalam init3kalam dev
```

--------------------------------

### Run Topic Consumer Example

Source: https://kalamdb.org/docs/rust-sdk/examples/topic-consumer

Commands to navigate to the example directory, set environment variables, and run the topic consumer application.

```bash
1cd link/sdks/rust
2export KALAMDB_SERVER_URL=http://localhost:29003
3export KALAMDB_ROOT_PASSWORD=kalamdb1234
4cargo run -p topic-consumer
```

--------------------------------

### Linux (x86_64) Installation and Setup

Source: https://kalamdb.org/docs/server/getting-started

Steps to download, verify, extract, and configure KalamDB server and CLI on Linux x86_64. Includes creating symlinks and a minimal server.toml configuration.

```bash
1# 1. Download both archives and SHA256SUMS from the release page, then verify:2sha256sum -c SHA256SUMS --ignore-missing3 
4# 2. Extract (creates versioned binary names in the current directory)5mkdir -p kalamdb-bin && cd kalamdb-bin6tar -xzf ../kalamdb-server-0.5.4-rc.1-linux-x86_64.tar.gz7tar -xzf ../kalamcli-0.5.4-rc.1-linux-x86_64.tar.gz8 
9# 3. Optional convenience symlinks10ln -sf kalamdb-server-0.5.4-rc.1-linux-x86_64 kalamdb-server11ln -sf kalamcli-0.5.4-rc.1-linux-x86_64 kalam12 
13# 4. Create a minimal local config14cat > server.toml <<'EOF'15[server]16host = "127.0.0.1"17port = 290018 
19[storage]20data_path = "./data"21 
22[limits]23 
24[logging]25logs_path = "./logs"26log_to_console = true27 
28[performance]29 
30[auth]31jwt_secret = "local-binary-test-secret-32chars-min"32root_password = "kalamdb123"33EOF34 
35# 5. Start the server36./kalamdb-server-0.5.4-rc.1-linux-x86_64 server.toml
```

--------------------------------

### Enable First-Run Setup Feature

Source: https://kalamdb.org/docs/rust-sdk/health-setup

Enable the 'setup' feature in Cargo.toml to manage initial server configuration.

```toml
kalam-client = { version = "0.5", features = ["native-sdk", "setup"] }
```

--------------------------------

### App Setup with KalamProvider

Source: https://kalamdb.org/docs/ts-sdk/react

Set up your React application by creating a KalamDB client and wrapping your app with KalamProvider to make the client available in context. This example demonstrates basic client creation with authentication.

```tsx
import { Auth, createClient } from '@kalamdb/client';
import { KalamProvider } from '@kalamdb/react';
import { MessagesPane } from './MessagesPane';

const client = createClient({
  url: 'http://localhost:2900',
  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),
});

export function App() {
  return (
    <KalamProvider client={client}>
      <MessagesPane roomId="main" />
    </KalamProvider>
  );
}
```

--------------------------------

### macOS (Apple Silicon) Installation and Setup

Source: https://kalamdb.org/docs/server/getting-started

Steps to download, verify, extract, and configure KalamDB server and CLI on macOS Apple Silicon. Includes creating symlinks and a minimal server.toml configuration.

```bash
shasum -a 256 -c SHA256SUMS

mkdir -p kalamdb-bin && cd kalamdb-bin
tar -xzf ../kalamdb-server-0.5.4-rc.1-macos-aarch64.tar.gz
tar -xzf ../kalamcli-0.5.4-rc.1-macos-aarch64.tar.gz
ln -sf kalamdb-server-0.5.4-rc.1-macos-aarch64 kalamdb-server
ln -sf kalamcli-0.5.4-rc.1-macos-aarch64 kalam

cat > server.toml <<'EOF'
[server]
host = "127.0.0.1"
port = 2900

[storage]
data_path = "./data"

[limits]

[logging]
logs_path = "./logs"
log_to_console = true

[performance]

[auth]
jwt_secret = "local-binary-test-secret-32chars-min"
root_password = "kalamdb123"
EOF

./kalamdb-server-0.5.4-rc.1-macos-aarch64 server.toml
```

--------------------------------

### Get Setup Status

Source: https://kalamdb.org/docs/server/api/http-reference

Checks the current setup status of the server, indicating whether initial setup is required.

```APIDOC
## GET /v1/api/auth/status

### Description
Returns the server's setup status, indicating if initial configuration is needed.

### Method
GET

### Endpoint
/v1/api/auth/status

### Response
#### Success Response
- **needs_setup** (boolean) - True if the server requires initial setup, false otherwise.
- **message** (string) - A message describing the setup status.

### Response Example
```json
{
  "needs_setup": true,
  "message": "Server requires initial setup..."
}
```
```

--------------------------------

### Run Example Projects

Source: https://kalamdb.org/docs/rust-sdk/setup

Execute example projects from the KalamDB repository using environment variables for server URL and root password.

```bash
1cd link/sdks/rust2export KALAMDB_SERVER_URL=http://localhost:29003export KALAMDB_ROOT_PASSWORD=kalamdb1234cargo run -p quickstart5cargo run -p live-inbox6cargo run -p topic-consumer   # requires consumer feature in the example crate

```

--------------------------------

### Basic Client Setup and Query

Source: https://kalamdb.org/docs/ts-sdk/setup

Set up the KalamDB client and execute a basic SQL query. This example uses HTTP and basic authentication, which automatically switches to JWT for subsequent requests.

```typescript
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();
```

--------------------------------

### Install @kalamdb/client

Source: https://kalamdb.org/docs/ts-sdk/setup

Install the core client package for UI, services, or scripts that run SQL.

```bash
1npm i @kalamdb/client
```

--------------------------------

### Download Docker Compose and Configure Server

Source: https://kalamdb.org/docs/server/getting-started/docker

This snippet downloads the Docker Compose file and creates a server.toml configuration file for a single-node KalamDB setup. It then starts the KalamDB service using Docker Compose.

```bash
mkdir kalamdb-docker && cd kalamdb-docker
curl -fsSL https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/single/docker-compose.yml -o docker-compose.yml

cat > server.toml <<'EOF'
[server]
host = "0.0.0.0"
port = 2900

[storage]
data_path = "/data"

[limits]

[logging]
level = "info"
logs_path = "/data/logs"
log_to_console = true
format = "json"

[performance]

[auth]
jwt_secret = "docker-compose-placeholder-secret-32c"

[security.cors]
allowed_origins = ["*"]

[rate_limit]
max_queries_per_sec = 1000000
max_messages_per_sec = 10000000
max_subscriptions_per_user = 100000
max_auth_requests_per_ip_per_sec = 20000000
max_connections_per_ip = 100000
max_requests_per_ip_per_sec = 20000000
request_body_limit_bytes = 104857600
ban_duration_seconds = 300
enable_connection_protection = true
EOF

KALAMDB_JWT_SECRET="$(openssl rand -base64 32)" KALAMDB_PORT=2900 docker compose up -d
```

--------------------------------

### Install @kalamdb/client and @kalamdb/consumer

Source: https://kalamdb.org/docs/ts-sdk/setup

Install the client package along with the consumer package for background workers or agents.

```bash
1npm i @kalamdb/client @kalamdb/consumer
```

--------------------------------

### KalamDB Vector Search SQL Setup

Source: https://kalamdb.org/docs/ts-sdk/examples

SQL example for setting up tables and indexes for vector search in KalamDB. It includes creating a table with an EMBEDDING column and creating a cosine index.

```sql
1CREATE TABLE rag.documents_vectors (2  id BIGINT PRIMARY KEY,3  doc_embedding EMBEDDING(384)4) WITH (TYPE = 'USER');5 6ALTER TABLE rag.documents_vectors7  CREATE INDEX doc_embedding USING COSINE;
```

--------------------------------

### Setup Status Response

Source: https://kalamdb.org/docs/server/api/http-reference

This endpoint returns the server's setup status, indicating whether initial configuration is required.

```json
{
  "needs_setup": true,
  "message": "Server requires initial setup..."
}
```

--------------------------------

### Setup Initial Authentication

Source: https://kalamdb.org/docs/server/api/http-reference

Performs the initial server bootstrap by setting the root password and creating the DBA user. This endpoint is intended for first-time setup only.

```APIDOC
## POST /v1/api/auth/setup

### Description
Initializes the server by setting the root password and creating the DBA user. This endpoint should only be called once during the initial setup. It does not automatically log in the user.

### Method
POST

### Endpoint
/v1/api/auth/setup

### Parameters
#### Request Body
- **user** (string) - Required - The username for the DBA user.
- **password** (string) - Required - The password for the DBA user.
- **root_password** (string) - Required - The password for the root user.
- **email** (string) - Required - The email address for the DBA user.

### Request Example
```json
{
  "user": "admin",
  "password": "AdminPass123!",
  "root_password": "RootPass123!",
  "email": "admin@example.com"
}
```
```

--------------------------------

### Example: Export All Your Data

Source: https://kalamdb.org/docs/server/sql-reference/user-data

A commented example demonstrating how to export all of your data using the EXPORT USER DATA command.

```SQL
1-- Export all your data
2EXPORT USER DATA;
```

--------------------------------

### Create User Table Example

Source: https://kalamdb.org/docs/server/sql-reference/tables

Example of creating a 'USER' table for isolated, per-user data storage. Includes options for storage, flushing, and compression.

```SQL
CREATE TABLE app.messages (
  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  conversation_id BIGINT NOT NULL,
  sender TEXT NOT NULL,
  role TEXT NOT NULL DEFAULT 'user',
  content TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
) WITH (
  TYPE = 'USER',
  STORAGE_ID = 'local',
  USE_USER_STORAGE = false,
  FLUSH_POLICY = 'rows:1000,interval:60',
  COMPRESSION = 'snappy'
);
```

--------------------------------

### Install ORM Package

Source: https://kalamdb.org/docs/ts-sdk

Install the ORM package along with the client and Drizzle ORM.

```bash
npm i @kalamdb/client @kalamdb/orm drizzle-orm
```

--------------------------------

### Create Shared Table Example

Source: https://kalamdb.org/docs/server/sql-reference/tables

Example of creating a 'SHARED' table for global access. Demonstrates setting access level and compression.

```SQL
CREATE SHARED TABLE app.config (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL,
  updated_at TIMESTAMP DEFAULT NOW()
) WITH (
  ACCESS_LEVEL = 'PUBLIC',
  COMPRESSION = 'zstd'
);
```

--------------------------------

### Create Stream Table Example

Source: https://kalamdb.org/docs/server/sql-reference/tables

Example of creating a 'STREAM' table for ephemeral data with a Time-To-Live (TTL) and eviction strategy.

```SQL
CREATE STREAM TABLE app.events (
  event_id TEXT PRIMARY KEY,
  payload TEXT,
  created_at TIMESTAMP DEFAULT NOW()
) WITH (
  TTL_SECONDS = 30,
  EVICTION_STRATEGY = 'hybrid',
  MAX_STREAM_SIZE_BYTES = 10485769
);
```

--------------------------------

### Start Kalam Dev Server

Source: https://kalamdb.org/docs/use-cases/live-okf-context-sync

Starts the Kalam development server. This is typically used to initialize the environment and begin the synchronization process.

```bash
1kalam dev

```

--------------------------------

### Install pg-kalam Extension

Source: https://kalamdb.org/docs/pg-kalam/getting-started

After connecting to your PostgreSQL instance, run this SQL command to install the pg-kalam extension if it hasn't been done by initialization scripts.

```sql
CREATE EXTENSION IF NOT EXISTS pg_kalam;
```

--------------------------------

### Run File Attachments Example

Source: https://kalamdb.org/docs/rust-sdk/examples/file-attachments

Execute the Rust file attachments example. Ensure the KalamDB server is running and the necessary environment variables are set.

```bash
1cd link/sdks/rust
2export KALAMDB_SERVER_URL=http://localhost:29003
3export KALAMDB_ROOT_PASSWORD=kalamdb1234
4cargo run -p file-attachments
```

--------------------------------

### Quick Example: Create Namespace, Table, Insert, and Select

Source: https://kalamdb.org/docs/server/sql-reference

Illustrates the creation of a namespace, a table with specific configurations, insertion of data, and a query to retrieve data.

```sql
1CREATE NAMESPACE IF NOT EXISTS chat;2 3CREATE TABLE chat.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');
9 10INSERT INTO chat.messages (sender, content)
11VALUES ('alice', 'Hello world!');
12 
13SELECT * FROM chat.messages ORDER BY created_at DESC LIMIT 20;
```

--------------------------------

### Re-run Setup Script

Source: https://kalamdb.org/docs/use-cases/chat-with-ai

Command to re-execute the setup script, which is useful if the agent is running but not producing replies, potentially due to missing topic routes.

```bash
npm run setup
```

--------------------------------

### Install Dependencies for React Live Queries

Source: https://kalamdb.org/docs/ts-sdk

Install the necessary KalamDB packages and React dependencies. This includes the client, react bindings, and Drizzle ORM for typed table definitions.

```bash
1npm i @kalamdb/client @kalamdb/react react react-dom2npm i @kalamdb/orm drizzle-orm
```

--------------------------------

### Example: Create Namespaces

Source: https://kalamdb.org/docs/server/sql-reference/namespaces

Demonstrates creating multiple namespaces, ensuring they do not already exist.

```SQL
CREATE NAMESPACE IF NOT EXISTS chat;
CREATE NAMESPACE IF NOT EXISTS analytics;
```

--------------------------------

### Download Full Sample Configuration

Source: https://kalamdb.org/docs/server/configurations

Use this command to download the complete server configuration file with inline comments. This is useful for understanding all available options.

```bash
curl -L https://raw.githubusercontent.com/kalamdb/KalamDB/refs/heads/main/backend/server.example.toml -o server.sample.toml
```

--------------------------------

### Set KalamDB Environment Variables

Source: https://kalamdb.org/docs/rust-sdk/examples

Configure the KalamDB server URL and root password for the Rust SDK examples. Ensure these match your local KalamDB setup.

```bash
1cd link/sdks/rust
2export KALAMDB_SERVER_URL=http://localhost:2900
3export KALAMDB_ROOT_PASSWORD=kalamdb123
```

--------------------------------

### Drizzle Driver Quick Start with KalamDB

Source: https://kalamdb.org/docs/ts-sdk/orm

Set up the Drizzle driver for KalamDB after generating your schema.ts file. This example demonstrates connecting to the client and querying data.

```typescript
1import { Auth, createClient } from '@kalamdb/client';
2import { kalamDriver } from '@kalamdb/orm';
3import { drizzle } from 'drizzle-orm/pg-proxy';
4import { messages } from './schema';
5 
6const client = createClient({
7  url: 'http://localhost:2900',
8  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),
9});
10 
11const db = drizzle(kalamDriver(client));
12const recent = await db.select().from(messages).limit(20);
```

--------------------------------

### Run a single KalamDB node with Docker and bootstrap

Source: https://kalamdb.org/docs/server/getting-started/docker

This PowerShell command runs a single KalamDB instance in a Docker container, mapping ports, setting environment variables for security and remote setup, and mounting a volume for data persistence. It then waits for the server to start and verifies its status and performs initial setup.

```powershell
1docker run -d --name kalamdb -p 2900:2900 \
2  -e KALAMDB_SERVER_HOST=0.0.0.0 \
3  -e KALAMDB_JWT_SECRET="$([Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 })))" \
4  -e KALAMDB_ALLOW_REMOTE_SETUP=true \
5  -v kalamdb_data:/data \
6  jamals86/kalamdb:latest
7 
8Start-Sleep -Seconds 5
9Invoke-RestMethod http://127.0.0.1:2900/v1/api/auth/status
10 
11Invoke-RestMethod -Method Post http://127.0.0.1:2900/v1/api/auth/setup \
12  -ContentType "application/json" \
13  -Body '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}'
```

--------------------------------

### Setup Topic Route

Source: https://kalamdb.org/docs/use-cases/chat-with-ai

SQL commands to create the 'chat_demo.ai_inbox' topic and link it to inserts on the 'chat_demo.messages' table.

```sql
CREATE TOPIC chat_demo.ai_inbox;
ALTER TOPIC chat_demo.ai_inbox ADD SOURCE chat_demo.messages ON INSERT;
```

--------------------------------

### Rate Limiting Configuration Example

Source: https://kalamdb.org/docs/server/security/rate-limits

A TOML configuration snippet demonstrating how to set various rate limiting parameters. This serves as a practical starting point for configuring security thresholds.

```TOML
1[rate_limit]
2max_queries_per_sec = 100
3max_messages_per_sec = 50
4max_subscriptions_per_user = 10
5max_auth_requests_per_ip_per_sec = 20
6max_connections_per_ip = 100
7max_requests_per_ip_per_sec = 200
8request_body_limit_bytes = 10485760
9ban_duration_seconds = 300
10enable_connection_protection = true
11cache_max_entries = 100000
12cache_ttl_seconds = 600
```

--------------------------------

### Consumer Client Setup and Topic Consumption

Source: https://kalamdb.org/docs/ts-sdk/setup

Set up a consumer client for Node.js worker processes to poll topics. This example configures topic, group ID, auto-acknowledgment, and batch size.

```typescript
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',
  group_id: 'billing',
  auto_ack: true,
  batch_size: 10,
});

await handle.run(async (ctx) => {
  console.log(ctx.message.offset, ctx.message.value);
});
```

--------------------------------

### Start Live Subscription Interactively

Source: https://kalamdb.org/docs/cli/subscriptions

Initiate live subscriptions using the \live or \subscribe commands in the interactive CLI, optionally with SQL OPTIONS.

```text
1kalam> \live SELECT * FROM app.messages OPTIONS (batch_size=5);
```

```text
2kalam> \subscribe SELECT * FROM app.messages OPTIONS (last_rows=20);
```

```text
3kalam> \live SELECT * FROM app.messages OPTIONS (last_rows=20, batch_size=5, from_seq_id=1234);
```

--------------------------------

### Bootstrap Server with Initial Credentials

Source: https://kalamdb.org/docs/server/getting-started/authentication

Create the initial DBA and root password for the KalamDB server. This command sends a POST request to the /v1/api/auth/setup endpoint with user, password, root_password, and email details in JSON format. The setup is localhost-only by default and does not return tokens.

```bash
curl -X POST http://127.0.0.1:2900/v1/api/auth/setup \
  -H 'Content-Type: application/json' \
  -d @- <<'JSON'
{
  "user": "admin",
  "password": "AdminPass123!",
  "root_password": "RootPass123!",
  "email": "admin@example.com"
}
JSON
```

--------------------------------

### Create Single-Partition Topic

Source: https://kalamdb.org/docs/server/topic-pubsub/sql-topics

Recommended starting point for development: create a topic with a single partition.

```SQL
1CREATE TOPIC app.user_events PARTITIONS 1;
```

--------------------------------

### Show All Storage Configurations

Source: https://kalamdb.org/docs/server/sql-reference/storage

List all configured storage backends and their details.

```SQL
SHOW STORAGES;
```

--------------------------------

### Set up KalamDB single-node with Docker Compose

Source: https://kalamdb.org/docs/server/getting-started/docker

This PowerShell snippet sets the JWT secret and port environment variables, downloads the Docker Compose file for a single-node setup, and starts the KalamDB service using Docker Compose.

```powershell
$env:KALAMDB_JWT_SECRET = [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))
$env:KALAMDB_PORT = "2900"
Invoke-WebRequest https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/single/docker-compose.yml -UseBasicParsing -OutFile docker-compose.yml
docker compose up -d
```

--------------------------------

### Example: Back up the entire database

Source: https://kalamdb.org/docs/server/sql-reference/backup

Demonstrates backing up the database to a specific timestamped archive or a date-named path. Ensure the path ends with .tar.gz and is quoted.

```sql
-- Back up the entire database to a timestamped archive
BACKUP DATABASE TO '/backups/kalamdb_20260224.tar.gz';

-- Store to a date-named path
BACKUP DATABASE TO '/var/backups/kalamdb/2026-02-24.tar.gz';
```

--------------------------------

### Baseline Security Configuration Example

Source: https://kalamdb.org/docs/server/security

This TOML configuration sets essential security parameters for KalamDB, including JWT secrets, CORS, and WebSocket origins. Ensure 'jwt_secret' is a strong, randomly generated string and 'allow_remote_setup' is false after initial setup.

```toml
[auth]
jwt_secret = "replace-with-strong-random-secret-32-plus-chars"
cookie_secure = true
allow_remote_setup = false

[rate_limit]
enable_connection_protection = true
max_auth_requests_per_ip_per_sec = 20
max_requests_per_ip_per_sec = 200
max_connections_per_ip = 100

[security]
max_request_body_size = 10485760
max_ws_message_size = 1048576
strict_ws_origin_check = true
allowed_ws_origins = ["https://app.example.com"]

[security.cors]
allowed_origins = ["https://app.example.com", "https://admin.example.com"]
allow_credentials = true
```

--------------------------------

### Run Single-Node KalamDB Server and Authenticate

Source: https://kalamdb.org/docs/server/getting-started/docker

This command runs a KalamDB server in Docker, publishes port 2900, sets up authentication with a JWT secret and remote setup enabled, and mounts a volume for data persistence. It then waits for the server to start and proceeds to set up the admin user and log in.

```bash
docker run -d --name kalamdb -p 2900:2900 \
  -e KALAMDB_SERVER_HOST=0.0.0.0 \
  -e KALAMDB_JWT_SECRET="$(openssl rand -base64 32)" \
  -e KALAMDB_ALLOW_REMOTE_SETUP=true \
  -v kalamdb_data:/data \
  jamals86/kalamdb:latest

sleep 5
curl -sS http://127.0.0.1:2900/v1/api/auth/status

curl -sS -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!"}'

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

--------------------------------

### Install and Verify pg_kalam Extension

Source: https://kalamdb.org/docs/pg-kalam/sql-syntax

Installs the pg_kalam extension if it's not already present and then verifies its installation by calling version and mode functions.

```SQL
CREATE EXTENSION IF NOT EXISTS pg_kalam;

SELECT kalam_version(), kalam_compiled_mode();
```

--------------------------------

### Download and Start KalamDB Server (Linux)

Source: https://kalamdb.org/docs/server/getting-started/binaries

Download and extract KalamDB server and CLI binaries, create a configuration file, and start the server. Ensure you have downloaded both archives into the same directory.

```bash
cd kalamdb-bin
ln -sf kalamdb-server-0.5.4-rc.1-linux-x86_64 kalamdb-server
ln -sf kalamcli-0.5.4-rc.1-linux-x86_64 kalam

cat > server.toml <<'EOF'
[server]
host = "127.0.0.1"
port = 2900

[storage]
data_path = "./data"

[limits]

[logging]
logs_path = "./logs"
log_to_console = true

[performance]

[auth]
jwt_secret = "local-binary-test-secret-32chars-min"
root_password = "kalamdb123"
EOF

./kalamdb-server-0.5.4-rc.1-linux-x86_64 server.toml
```

--------------------------------

### Enable Remote Setup Endpoint Temporarily

Source: https://kalamdb.org/docs/server/security/production-checklist

Temporarily enable the remote setup endpoint for initial configuration. Ensure it is flipped back to false immediately after setup to prevent unauthorized access.

```toml
[auth]
allow_remote_setup = true   # flip back to false immediately after setup
```

--------------------------------

### Error Response Example

Source: https://kalamdb.org/docs/server/topic-pubsub/http-topic-api

Example of an error response shape from the HTTP Topic API.

```json
{
  "error": "...",
  "code": "FORBIDDEN|NOT_FOUND|INTERNAL_ERROR"
}
```

--------------------------------

### Quick Start Kalam Dev

Source: https://kalamdb.org/docs/cli/dev

Initiates the local development environment. Navigate to your project directory and run `kalam dev`.

```bash
1cd my-app2kalam dev
```

--------------------------------

### Cluster Peer Override Example

Source: https://kalamdb.org/docs/server/getting-started/configuration

An example demonstrating the format for specifying cluster peers.

```text
2@kalamdb-node2:2910@http://kalamdb-node2:2900;3@kalamdb-node3:2910@http://kalamdb-node3:2900
```

--------------------------------

### Run KalamDB Server with Configuration File

Source: https://kalamdb.org/docs/server/getting-started/configuration

Start the KalamDB server using a specified configuration file.

```bash
kalamdb-server --config /path/to/server.toml
```

--------------------------------

### Install KalamDB Packages

Source: https://kalamdb.org/docs/ts-sdk/chat-quickstart

Install the necessary KalamDB client and consumer packages for your Node.js project.

```bash
npm i @kalamdb/client @kalamdb/consumer
```

--------------------------------

### Acknowledge Response Example

Source: https://kalamdb.org/docs/server/topic-pubsub/http-topic-api

Example response from an acknowledge request, confirming successful commit of the offset.

```json
{
  "success": true,
  "acknowledged_offset": 10
}
```

--------------------------------

### Download Sample Configuration

Source: https://kalamdb.org/docs/server/getting-started/configuration

Download the full commented sample configuration file for KalamDB.

```bash
curl -L https://raw.githubusercontent.com/kalamdb/KalamDB/refs/heads/main/backend/server.example.toml -o server.example.toml
```

--------------------------------

### Consume Response Example

Source: https://kalamdb.org/docs/server/topic-pubsub/http-topic-api

Example response from a consume request, containing a batch of messages with their metadata.

```json
{
  "messages": [
    {
      "topic_id": "app.user_events",
      "partition_id": 0,
      "offset": 10,
      "payload": "<base64>",
      "key": "optional-key",
      "timestamp_ms": 1730000000000,
      "user": "user_123",
      "op": "Insert"
    }
  ],
  "next_offset": 11,
  "has_more": false
}
```

--------------------------------

### Create Local Filesystem Storage

Source: https://kalamdb.org/docs/server/sql-reference/storage

Example of creating a storage backend of type 'filesystem'. Ensure the PATH is correctly specified.

```SQL
CREATE STORAGE local
  TYPE 'filesystem'
  PATH './data';
```

--------------------------------

### Verify KalamDB CLI Installation

Source: https://kalamdb.org/docs/cli/setup

Commands to verify the KalamDB CLI installation and check its version and status.

```bash
kalam --help
```

```bash
kalam version
```

```bash
kalam doctor
```

--------------------------------

### Create Storage Backend

Source: https://kalamdb.org/docs/server/sql-reference/storage

Use this command to define a new storage backend. Specify the type, and optionally provide a name, description, path, bucket, region, base directory, templates, credentials, and configuration.

```SQL
CREATE STORAGE <storage_id>
  TYPE '<filesystem|s3|gcs|azure>'
  [NAME '<storage_name>']
  [DESCRIPTION '<description>']
  [PATH '<path>']
  [BUCKET '<bucket_or_s3_url>']
  [REGION '<region>']
  [BASE_DIRECTORY '<path_or_url>']
  [SHARED_TABLES_TEMPLATE '<template>']
  [USER_TABLES_TEMPLATE '<template>']
  [CREDENTIALS '<json_credentials>']
  [CONFIG '<json_config>'];
```

--------------------------------

### Testing the React AI Chat Example

Source: https://kalamdb.org/docs/ts-sdk/examples

Command to run tests for the React AI Chat example.

```bash
npm test
```

--------------------------------

### Create Regular User with Password

Source: https://kalamdb.org/docs/server/sql-reference/users

Example of creating a standard user with a password and email address.

```SQL
-- Create a regular user with password
CREATE USER 'alice'
  WITH PASSWORD 'SecurePass123!'
  ROLE user
  EMAIL 'alice@example.com';
```

--------------------------------

### Get Current Timestamp

Source: https://kalamdb.org/docs/server/sql-reference/functions

Use NOW() to get the current timestamp. This is commonly used as a default for timestamp columns.

```SQL
SELECT NOW();
-- Returns: 2026-02-18T10:30:00.000Z
```

```SQL
CREATE TABLE app.events (
  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  event_type TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
```

--------------------------------

### Install KalamDB TypeScript SDK

Source: https://kalamdb.org/docs/server/getting-started

Install the @kalamdb/client package using npm to integrate KalamDB with your TypeScript projects.

```bash
npm install @kalamdb/client
```

--------------------------------

### Create USER Table with Unified Syntax

Source: https://kalamdb.org/docs/server/architecture/table-types

Demonstrates the recommended unified SQL syntax for creating a USER table, specifying its type and other parameters.

```sql
CREATE TABLE app.messages (
  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
) WITH (TYPE = 'USER');
```

--------------------------------

### Verify Kalam CLI Installation

Source: https://kalamdb.org/docs/server/getting-started

Checks if the Kalam CLI is installed correctly and runs a diagnostic check on your environment.

```bash
kalam --version
kalam doctor
```

--------------------------------

### Acknowledge Request Example

Source: https://kalamdb.org/docs/server/topic-pubsub/http-topic-api

Example of a request to acknowledge messages up to a specific offset. This commits progress for the consumer group.

```json
{
  "topic_id": "app.user_events",
  "group_id": "ai-worker",
  "partition_id": 0,
  "upto_offset": 10
}
```

--------------------------------

### Setup Request

Source: https://kalamdb.org/docs/server/api/http-reference

Initial bootstrap endpoint to set the root password and create the DBA user. This endpoint is only available when no root password is set. It does not auto-login.

```json
{
  "user": "admin",
  "password": "AdminPass123!",
  "root_password": "RootPass123!",
  "email": "admin@example.com"
}
```

--------------------------------

### Example: Check Latest Export Status

Source: https://kalamdb.org/docs/server/sql-reference/user-data

A commented example for checking the status of your most recent data export job.

```SQL
1-- Check status of your latest export
2SHOW EXPORT;
```
Tokens:
Raw