KiteSQL is a lightweight, embedded OLTP-oriented relational database written entirely in Rust. Inspired by MyRocks and SQLite, it is designed to function both as a standard SQL engine and as a Rust-native data API/ORM surface README.md30-32 It eliminates the need for external service layers by storing all metadata and actual data directly in Key-Value (KV) storage README.md39-40
KiteSQL follows a traditional database architecture optimized for embedding. Queries enter through the Database API, are transformed into logical plans, optimized, and finally executed via a volcano-style execution engine that interacts with a pluggable storage layer.
The following diagram traces the flow from a SQL string or ORM builder call to the storage layer, mapping system concepts to specific code entities.
Diagram: Request Flow and Code Entities
Sources: src/lib.rs105-126 src/db.rs1-100 README.md30-40
The project is structured as a Cargo workspace with the main logic residing in the kite_sql crate, supplemented by specialized crates for macros and benchmarking Cargo.toml91-96
| Component | Path | Description |
|---|---|---|
| Core Engine | src/ | Main database logic including parser, binder, planner, and executors. |
| Public API | src/db.rs, src/lib.rs | Entry points: Database and DataBaseBuilder src/db.rs26-50 |
| ORM Macros | kite_sql_serde_macros/ | Procedural macros for #[derive(Model)] Cargo.toml56 |
| Storage | src/storage/ | Traits and implementations for RocksDB, LMDB, and In-Memory. |
| Benchmarks | tpcc/ | TPC-C implementation for performance and correctness testing tpcc/README.md1-5 |
| Tests | tests/ | SQL logic tests (SLT) and macro integration tests Cargo.toml91-96 |
Sources: Cargo.toml91-96 src/lib.rs105-128
KiteSQL is highly modular, allowing users to toggle storage backends and frontend capabilities via Cargo features Cargo.toml26-44
rocksdb (default), lmdb (optional), and in-memory (always available) README.md134-144parser feature, utilizing sqlparser-rs Cargo.toml33orm feature, providing typed models and migrations README.md47-53shell for an interactive CLI, wasm for JavaScript environments, and python for PyO3 bindings Cargo.toml38-44Detailed documentation for each subsystem is available in the following child pages:
Covers the Database and DataBaseBuilder structures in src/db.rs. It explains how to configure storage, manage transactions, and register User-Defined Functions (UDFs) src/lib.rs24-54
Documents the transformation of SQL strings into bound statements. This includes semantic analysis, catalog lookups in src/catalog, and expression binding src/lib.rs105-120
Explains the LogicalPlan structure and the PlanArena used for memory-efficient plan management src/lib.rs121 This section also introduces the Optimizer and Statistics, which handle rule-based optimization (RBO) and cost-based physical selection docs/features.md80-83
Details the volcano-style execution model where Executor nodes pull tuples from their children. It covers DDL application, DML operations, and complex joins docs/features.md84-86
The core of KiteSQL's persistence layer. It defines the Storage and Transaction traits and explains the table_codec used to map relational data to KV pairs src/lib.rs125
Covers the type system (LogicalType, DataValue), the system catalog for metadata persistence, and the expression evaluation framework src/lib.rs106-126
Documents the #[derive(Model)] macro and the typed query builder that allows interacting with the database using Rust structs instead of raw SQL strings README.md47-53
Instructions for using the kitesql-shell and integrating KiteSQL into non-Rust environments like Node.js or Python README.md151-157
Explains the Makefile-driven workflow (make test, make test-slt) and the use of the TPC-C benchmark for validating performance and transactional correctness tpcc/README.md1-5
Guidelines for contributors, emphasizing simplicity, low dependency counts, and a correctness-first approach to storage changes.
Diagram: Storage Implementation Mapping
Sources: src/lib.rs125 README.md134-144
Refresh this wiki