Skip to Content
Setup & Quick Start

Setup & Quick Start

Status: Beta — the API may still change between releases.

The Rust SDK is the kalam-client crate on crates.io. One crate covers SQL, live rows, auth, optional file uploads, and optional topic consumers behind Cargo features.

Install

BASH
cargo add kalam-clientcargo add tokio --features macros,rt-multi-thread
TOML
[dependencies]kalam-client = "0.5"tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

MSRV: Rust 1.92+

You need a running KalamDB server. Quick Docker start:

BASH
docker run -d --name kalamdb -p 2900:2900 \  -e KALAMDB_SERVER_HOST=0.0.0.0 \  -e KALAMDB_ROOT_PASSWORD=kalamdb123 \  -e KALAMDB_JWT_SECRET=local-dev-secret-please-change-32chars \  -v kalamdb_data:/data jamals86/kalamdb:latest

Verify: curl http://127.0.0.1:2900/health

Create a client

KalamLinkClient::builder() requires base_url. Prefer AuthProvider::basic_auth(...) or AuthProvider::jwt_token(...) for normal apps.

RUST
use std::time::Duration;use kalam_client::{AuthProvider, KalamLinkClient}; let client = KalamLinkClient::builder()    .base_url("http://localhost:2900")    .auth(AuthProvider::basic_auth("admin".into(), "kalamdb123".into()))    .timeout(Duration::from_secs(30))    .build()?;

For local tooling against a root password:

RUST
let auth = AuthProvider::system_user_auth(    std::env::var("KALAMDB_ROOT_PASSWORD").unwrap_or_else(|_| "kalamdb123".into()),);

system_user_auth logs in as the root system user.

If auth is disabled locally, you can omit .auth(...) and use AuthProvider::none().

By default, ConnectionOptions::ws_lazy_connect is true, so the WebSocket opens on the first live subscription rather than at build time.

First query

RUST
let response = client    .execute_query("SELECT CURRENT_USER()", None, None, None)    .await?; if !response.success() {    if let Some(err) = &response.error {        eprintln!("query failed: {} ({})", err.message, err.code);    }    return Ok(());} for row in response.rows_as_maps() {    println!("{row:?}");}

QueryResponse can contain multiple QueryResult values when you send multiple statements. rows_as_maps() reads the first result set.

Rows are HashMap<String, KalamCellValue>. Use typed accessors such as as_text() instead of assuming raw JSON shapes.

First live stream

Call connect() before subscriptions. Prefer live() when you want materialized rows.

RUST
use kalam_client::{    LiveRowsConfig, LiveRowsEvent, SubscriptionConfig, SubscriptionOptions,}; client.connect().await?; let mut config = SubscriptionConfig::new(    "inbox",    "SELECT * FROM app.messages WHERE room = 'main'",);config.options = Some(SubscriptionOptions::new().with_last_rows(20)); let mut live = client    .live_with_config(        config,        LiveRowsConfig {            limit: Some(20),            ..LiveRowsConfig::default()        },    )    .await?; while let Some(event) = live.next().await {    if let LiveRowsEvent::Rows { rows, .. } = event? {        println!("{} rows", rows.len());        break;    }} live.close().await?;

Live SQL must be SELECT ... FROM ... WHERE ... only.

Cleanup

RUST
client.disconnect().await;

Runnable examples

From the KalamDB repository:

BASH
cd link/sdks/rustexport KALAMDB_SERVER_URL=http://localhost:2900export KALAMDB_ROOT_PASSWORD=kalamdb123cargo run -p quickstartcargo run -p live-inboxcargo run -p topic-consumer   # requires consumer feature in the example crate

Runnable walkthroughs: Examples — Quickstart, Live Inbox, Topic Consumer.

Develop from source

TOML
kalam-client = { path = "../KalamDB/link/kalam-client", features = ["native-sdk", "consumer"] }

Next

Last updated on
OverviewAuthentication