Rust SDK

kalam-client is the official KalamDB client for Rust. It wraps the shared link-common implementation with a Tokio-native API for services, CLIs, and background workers.

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

Current version: 0.5.2-rc.2 · MSRV: Rust 1.92+

What you can do

kalam-client focuses on the core app and worker workflows:

• Execute SQL over HTTP (execute_query, execute_with_files)
• Upload and download FILE column attachments (FileRef, BoundFileRef, download_bound_file)
• Open materialized live rows over WebSocket (live, live_with_config)
• Consume low-level subscription frames (live_events, live_events_with_config)
• Authenticate with JWT, basic login bootstrap, system-user auth, or dynamic providers (AuthProvider, login, refresh_access_token)
• Observe connection lifecycle (EventHandlers)
• Inspect active subscriptions (subscriptions)
• Control the shared WebSocket explicitly (connect, disconnect, is_connected)
• Poll and commit topic records when the consumer feature is enabled (client.consumer())

Optional feature-gated helpers:

• health_check() with the healthcheck feature
• check_setup_status() / server_setup() with the setup feature
• cluster_health_check() with the cluster feature

Installation

1cargo add kalam-client2cargo add tokio --features macros,rt-multi-thread

1[dependencies]2kalam-client = "0.5"3tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Enable optional capabilities as needed:

1# Topic workers2kalam-client = { version = "0.5", features = ["native-sdk", "consumer"] }3 4# Multipart SQL file uploads5kalam-client = { version = "0.5", features = ["native-sdk", "file-uploads"] }

Quick start

1use std::time::Duration;2use kalam_client::{AuthProvider, KalamLinkClient};3 4#[tokio::main]5async fn main() -> Result<(), Box<dyn std::error::Error>> {6    let client = KalamLinkClient::builder()7        .base_url("http://localhost:2900")8        .auth(AuthProvider::basic_auth("admin".into(), "kalamdb123".into()))9        .timeout(Duration::from_secs(30))10        .build()?;11 12    let response = client13        .execute_query("SELECT CURRENT_USER()", None, None, None)14        .await?;15 16    if response.success() {17        println!("rows: {:?}", response.rows_as_maps());18    }19 20    client.disconnect().await;21    Ok(())22}

Runnable examples: Examples.

For live() and live_events(), keep SQL strict: SELECT ... FROM ... WHERE .... Do not put ORDER BY or LIMIT in live subscription SQL.

Recommended reading order

1. Setup & Quick Start
2. Authentication
3. Auth-Aware Client
4. Querying & DML
5. FILE Columns & Uploads
6. Realtime Subscriptions
7. Client Lifecycle
8. Types & Models
9. Cell Values (KalamCellValue)
10. Server Setup & Diagnostics Boundary
11. Transport & Endpoints
12. Examples

Examples

Runnable crates ship under link/sdks/rust/examples/:

See Examples overview for run commands and prerequisites.

Why live() first

Most UIs want the latest reconciled row list, not raw insert/update/delete frames.

• live() / live_with_config() — materialized rows (recommended default)
• live_events() / live_events_with_config() — low-level protocol events

Use SubscriptionOptions::with_last_rows() to rewind recent history. Use LiveRowsConfig { limit: Some(n), .. } to cap the materialized set the client keeps.

Builder options

Notes

• base_url(...) is required on every builder.
• Basic auth is exchanged for JWT before protected SQL or WebSocket work.
• HTTP queries work without connect(). Call connect() before live subscriptions.
• Default ConnectionOptions uses ws_lazy_connect: true — the socket opens on the first subscription.
• Close live streams and consumers with close() during shutdown.