Welcome to KalamDB documentation! This folder is organized into the following sections:
Quick start guides for new users and contributors.
- quick-start.md – Build and run your first query
- cli.md – Using the
kalamcommand-line client
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
HTTP and WebSocket API documentation.
- api.md – Quick API overview
- api-reference.md – Complete REST API reference
- websocket-protocol.md – WebSocket subscription protocol
Client SDK documentation.
- sdk.md – TypeScript/JavaScript SDK guide
System architecture and design decisions.
- decisions/ – Architecture Decision Records (ADRs)
- manifest.md – Manifest file format
- 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
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
Decision-complete implementation plans for major initiatives.
- 2026-02-14-flatbuffers-flexbuffers-vortex-migration-plan.md – Migration plan for FlatBuffers/FlexBuffers with Vortex serde learnings
Bruno API collection for testing endpoints.
- Quick Start – Get KalamDB running
- SQL Reference – Learn the SQL syntax
- CLI Guide – Use the command-line client
- API Reference – REST endpoints
- WebSocket Protocol – Real-time subscriptions
- SDK Guide – TypeScript/JavaScript client
- Build Guide – Build the project
- Development Setup – Full environment setup
- Architecture Decisions – Understand design choices
- Plans – Execution-ready project plans
Follow the Quick Start Guide for your platform. If you encounter issues, see the Troubleshooting section in the full setup guide.
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.
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.
- AGENTS.md – AI/Agent coding guidelines
- Backend README – Backend project structure
- Main README – Project overview
Last Updated: February 2026
KalamDB Version: 0.1.x