Your First Live Query

This tutorial uses the released KalamDB 0.8 server, Docker, and the built-in Admin UI. You will insert a row, subscribe to it, then change it in a second tab to see the first tab update without refreshing.

You need Docker and a terminal. No Node.js app, SDK or Rust compiler is required.

1. Start the server

1docker run -d --name kalamdb -p 2900:2900 \2  -e KALAMDB_SERVER_HOST=0.0.0.0 \3  -e KALAMDB_JWT_SECRET="$(openssl rand -base64 32)" \4  -e KALAMDB_ALLOW_REMOTE_SETUP=true \5  -v kalamdb_data:/data kalamdb/kalamdb:0.8.0

Check that the server responds:

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

If you already have a container named kalamdb, reuse it or stop/remove it before repeating the command. The named Docker volume persists data between container replacements.

2. Set up local authentication

If the status response says "needs_setup": true, create the initial account:

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

These example passwords are for an isolated local tutorial only. Change them for any real deployment. Do not expose a remotely accessible setup endpoint on an untrusted network.

If setup reports that the server is already configured, use the credentials from that existing installation instead of repeating setup.

3. Create a private table

Open KalamDB Admin UI and sign in with admin and the password you used in step 2.

In SQL Studio, run:

1CREATE SCHEMA IF NOT EXISTS app;2 3CREATE TABLE app.todos (4  id BIGSERIAL PRIMARY KEY,5  title TEXT NOT NULL,6  completed BOOLEAN NOT NULL DEFAULT FALSE7) WITH (TYPE = 'USER');8 9INSERT INTO app.todos (title) VALUES ('Try live queries');10 11SELECT id, title, completed FROM app.todos;

You should see a todo row. TYPE = 'USER' means the table’s rows belong to the authenticated user. Another user will not see these private rows even when running the same SQL.

4. Watch the query update live

In one SQL Studio tab, enter only this query, turn on Live query mode and run it:

1SELECT id, title, completed2FROM app.todos3WHERE completed = FALSE;

Keep that tab open. In another browser tab, sign in with the same account, open SQL Studio, and run:

1UPDATE app.todos2SET completed = TRUE3WHERE title = 'Try live queries';

The row should disappear from the filtered live result in the first tab without manually refreshing it. That is the core KalamDB live-query workflow.

Live SQL is intentionally narrower than general SQL: start with a single table and supported WHERE predicates. Avoid joins, aggregates, ORDER BY or LIMIT in the subscription query.

What you just used

Build a real application next

Connect with the TypeScript SDK, Rust SDK, or Dart / Flutter SDK. For a complete application architecture, see how KalamDB works and topics and server functions.

0.8 SDK template note: The published CLI-generated TypeScript starters still reference older 0.7-beta SDK versions. Do not assume kalam init --template chat-with-ai or simple-live runs against 0.8 as generated. Use the 0.8 CLI compatibility notes before using those templates.

Next: Choose your table type → · Connect an application →.