KalamDB Documentation

Welcome to KalamDB documentation! This folder is organized into the following sections:

📖 Documentation Structure

getting-started/

Quick start guides for new users and contributors.

• quick-start.md – Build and run your first query
• cli.md – Using the kalam command-line client

reference/

Core reference documentation for SQL syntax and behavior.

• sql.md – Complete SQL syntax reference
• identifiers.md – Case sensitivity and naming rules
• timestamp-formatting.md – Timestamp handling

api/

HTTP and WebSocket API documentation.

• api.md – Quick API overview
• api-reference.md – Complete REST API reference
• websocket-protocol.md – WebSocket subscription protocol

sdk/

Client SDK documentation.

• sdk.md – TypeScript/JavaScript SDK guide

architecture/

System architecture and design decisions.

• decisions/ – Architecture Decision Records (ADRs)
• manifest.md – Manifest file format and flush architecture
• hot-cold-storage-unification.md – Hot/cold tiers, DataFusion provider scan path, and MVCC merge
• release-downloads.md – CLI update, installer, and managed local server release download flow
• conversion-architecture.md – Data type conversion
• pg-extension-grpc-connectivity.md – PostgreSQL extension gRPC transport, session lifecycle, liveness, and improvement path
• vector-search-architecture.md – Vector index hot staging, cold snapshots, and query path

development/

Contributor guides for building and developing KalamDB.

• build.md – Build guide (start here)
• development-setup.md – Full development setup
• macos.md / linux.md / windows.md – Platform guides
• testing-strategy.md – Testing approach
• how-to-add-sql-statement.md – Adding new SQL statements
• docker-idle-resource-baseline.md – Why idle Docker CPU/memory is non-zero and how to tune it

plans/

Decision-complete implementation plans for major initiatives.

• 2026-09-01-kalamdb-0.7.md – 0.7 program: implement serialization, scalar secondary indexes, and functions V1 together
• 2026-02-14-flatbuffers-flexbuffers-vortex-migration-plan.md – One kalamdb-serialization crate; nested STRUCT/List; Vortex as design reference only
• 2026-08-30-scalar-secondary-indexes.md – Unified indexing core (optional kalamdb-index crate); scalar USER/SHARED indexes; vector search extends the core; system.schemas + CLI schema-diff
• functions-v1-implementation.md – SQL procedures, generated SDKs, typed CALL, topic triggers (design)

API-Kalam/

Bruno API collection for testing endpoints.

---

🎯 Quick Links by Role

New Users

1. Quick Start – Get KalamDB running
2. SQL Reference – Learn the SQL syntax
3. CLI Guide – Use the command-line client

API Developers

1. API Reference – REST endpoints
2. WebSocket Protocol – Real-time subscriptions
3. SDK Guide – TypeScript/JavaScript client

Contributors

1. Build Guide – Build the project
2. Development Setup – Full environment setup
3. Architecture Decisions – Understand design choices
4. Plans – Execution-ready project plans

---

💡 Common Questions

How do I get started with development?

Follow the Quick Start Guide for your platform. If you encounter issues, see the Troubleshooting section in the full setup guide.

Why do I need LLVM/Clang?

KalamDB depends on native libraries (RocksDB, Arrow, Parquet) written in C++. The Rust build process needs LLVM/Clang to compile these dependencies. See the Build Guide for details.

What's the table-per-user architecture?

KalamDB stores each user's messages in isolated storage partitions instead of a shared table. This enables massive scalability for real-time subscriptions. Read more in the Main README.

---

📚 Related Documentation

• AGENTS.md – AI/Agent coding guidelines
• Backend README – Backend project structure
• Main README – Project overview

---

Last Updated: September 2026
KalamDB Version: 0.6.x (0.7 program: serialization + scalar indexes + functions V1)