toyDB is a distributed SQL database in Rust written as an educational project to illustrate the architecture and concepts behind production distributed SQL databases.
The project addresses the challenge of understanding how distributed SQL databases work by building a functional system from scratch that prioritizes clarity over performance. It implements core database concepts including Raft-based distributed consensus for linearizable state machine replication, ACID transactions using MVCC-based snapshot isolation, a pluggable storage engine with BitCask and in-memory backends, and a query engine supporting joins, aggregates, and time-travel queries. The architecture follows a typical distributed SQL pattern: a transactional key-value store managed by a Raft cluster with a SQL query engine layered on top.
toyDB is suited for developers and students seeking to understand distributed database internals rather than for production use. The README explicitly states that performance, scalability, and availability are non-goals, as these are major sources of complexity that obscure fundamental concepts. The project is most valuable for learning purposes, with comprehensive documentation including an architecture guide, SQL examples, and references to research materials. Anyone considering it should understand that it deliberately takes shortcuts to maintain simplicity and readability.
The project maintains extensive test coverage through Goldenscripts that verify behavior across Raft clustering, MVCC transactions, SQL execution, and end-to-end scenarios. The codebase includes a workload benchmark tool for running various workloads against a cluster, though performance optimization is not a development priority. Documentation is thorough, with guided architecture tours and detailed SQL reference materials provided alongside the code.
