erikgrinaker/toydb

toyDB is a distributed SQL database implemented in Rust that provides fault-tolerant replication via a Raft consensus protocol and supports transactional SQL operations with snapshot isolation. It features a modular architecture with a pluggable storage layer (including MVCC and BitCask) and a query engine capable of parsing, planning, and executing complex SQL statements with hash joins and aggregations. The system includes CLI tools for interactive querying, debugging, and benchmarking, along with comprehensive testing infrastructure to verify correctness across local and clustered deployments.

10 changes.

This period marks the initial release of toyDB, establishing the foundational Rust codebase, build configuration, and Apache 2.0 licensing. It introduces the core distributed SQL database components, including the Raft consensus protocol, SQL parsing and planning engines, and the server-client architecture with transaction support.

17 changes.

This period focused on building the core SQL execution engine with hash joins and aggregation, alongside a modular storage layer featuring MVCC support for snapshot isolation. Extensive golden-script testing was introduced across the Raft consensus, storage, and SQL layers to verify correctness, transaction isolation, and query optimization.

This change introduces the core Raft distributed consensus module, providing fault-tolerant, linearizable replication for the database's state machine. It includes a persistent log store (\src/raft/log.rs\) backed by a configurable storage engine, a message protocol (\src/raft/message.rs\) for leader election, log replication, and client request handling, and a synchronous node driver (\src/raft/node.rs\) that manages role transitions (follower, candidate, leader) and state machine application via the \State\ trait. The implementation supports single-node clusters, handles log splicing and conflict resolution, and ensures durability through configurable fsync policies.

src/raft · high confidence

This change introduces the core SQL execution engine, enabling users to submit SQL statements (such as SELECT, UPDATE, and schema operations) which are parsed, planned, optimized, and executed against the storage layer. It includes the necessary modules for parsing, planning, optimization, and execution, along with a comprehensive goldenscript-based test suite to verify query correctness, optimizer behavior, and transaction handling.

src/sql · high confidence

This change introduces the foundational SQL parsing infrastructure, including a lexer, an Abstract Syntax Tree (AST) definition, and a recursive-descent parser. Users can now parse raw SQL strings into structured statements (such as SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, and transaction controls) and expressions, which are then passed to the planner for validation and execution planning.

src/sql/parser · high confidence

This entry marks the initial commit of the toyDB distributed SQL database. The repository now includes the core Rust source code, a \rust-toolchain\ file pinning the compiler to version 1.96.0, and configuration files for \rustfmt\. The project is released under the Apache License 2.0, and the \README.md\ has been updated to document the architecture, SQL features, and usage instructions for the local cluster and \toysql\ client. Additionally, a \.gitignore\ file has been added to exclude build artifacts and local data directories.

(repo-wide) · high confidence

This change introduces the core toyDB binaries: the \toydb\ server, which manages configuration (via YAML or environment variables), initializes Raft and SQL storage engines (defaulting to BitCask), and listens for SQL (port 9601) and Raft (port 9701) connections; the \toysql\ interactive client for executing SQL statements and managing transactions; the \toydump\ debug tool for inspecting BitCask database files; and the \workload\ benchmark runner for testing cluster performance with read, write, and bank transaction patterns.

src/bin · high confidence

This change introduces the core toyDB library, providing a TCP-based SQL client that supports automatic retry logic for serialization and abort errors, and a server that routes SQL requests through a Raft consensus node. The implementation includes a new error handling system with specific variants for serialization conflicts and read-only violations, and exposes basic SQL operations like table listing and schema retrieval through the client interface.

src · high confidence

The \src/sql/types\ module now defines the core SQL data model, including the \Expression\ enum for evaluating logical, comparison, and mathematical operations (such as \IS NULL\, \IS NAN\, and \LIKE\), and the \Value\ type which handles SQL-specific semantics for \NULL\ and \NaN\ equality and ordering. It also introduces the \Table\ and \Column\ schema structures, enabling users to define tables with primary keys, default values, unique constraints, and foreign key references, all validated against the catalog before execution.

src/sql/types · high confidence

The storage layer has been restructured into distinct modules: a generic \Engine\ trait defines the key-value interface, \BitCask\ provides a simple log-structured persistent implementation, \Memory\ offers an in-memory engine for testing, and \Mvcc\ adds a Multi-Version Concurrency Control layer on top of the engine. This change introduces snapshot isolation for transactions, supports time-travel queries by preserving historical versions, and implements garbage collection thresholds for the BitCask engine. The \Engine\ trait now includes \scan\_prefix\ and \status\ methods, and the \Status\ struct tracks live and garbage disk sizes.

src/storage · high confidence

The SQL execution layer has been rewritten to support advanced query processing capabilities. Users can now execute queries using Hash Joins for improved performance on large datasets, alongside the existing Nested Loop Joins. The engine also supports GROUP BY clauses with aggregate functions (COUNT, SUM, AVG, MIN, MAX) and allows for EXPLAIN plans to inspect query execution strategies. Transaction handling has been refined to support read-only and read-write modes, including point-in-time reads via \AS OF\ clauses.

src/sql/execution · high confidence

The SQL engine now uses a dedicated planner module to build and optimize execution plans from the parsed AST. This introduces a structured plan representation (Plan/Node) supporting SELECT, INSERT, UPDATE, DELETE, and schema operations, along with an optimizer pipeline that applies constant folding, filter pushdown, index lookups, hash joins, and short-circuiting to improve query performance.

src/sql/planner · high confidence

The \src/encoding\ module has been introduced to centralize binary data handling. It provides \Keycode\ for lexicographically ordered key serialization and \Bincode\ for value serialization, exposed via \Key\ and \Value\ traits that allow automatic encode/decode methods on application types. A new \format\ module adds human-readable formatting for keys and values across Raft, MVCC, and SQL contexts, supporting debugging and log inspection.

src/encoding · high confidence

The SQL engine has been restructured into a modular design located in \src/sql/engine\, introducing a unified \Engine\ trait that supports both local and distributed execution. The \Local\ engine provides node-level SQL storage backed by MVCC, handling row CRUD, schema catalog operations, and secondary index lookups. The \Raft\ engine wraps this local implementation to provide distributed consensus, serializing read and write commands via Bincode and dispatching them through the Raft client. This change establishes the foundational interface for transactional SQL sessions, snapshot isolation, and schema management across both single-node and clustered deployments.

src/sql/engine · high confidence

The local cluster setup script and node configurations have been updated to bind all services to localhost. SQL listeners are now on ports 9601–9605 and Raft listeners on 9701–9705, replacing any previous default ports. The run.sh script also includes improved Ctrl-C handling to ensure all background node processes are properly terminated when the script exits.

cluster · high confidence

Add goldenscript-based tests for BitCask and Memory storage engines; Add test scripts for storage engine key and scan operations; Added comprehensive MVCC transaction and isolation test scripts; Added comprehensive expression evaluation tests; Added comprehensive golden tests for SQL query execution; Added end-to-end test scripts for SQL and transaction behavior; Added goldenscript tests for Raft node append and election behaviors; Added schema golden tests for CREATE TABLE and DROP TABLE; Added test scripts for SQL optimizer behaviors; Added transaction isolation and lifecycle test scripts; Goldenscript tests for SQL write operations; Goldenscript-based unit tests for Raft Log operations; New end-to-end test harness using Goldenscript.

This change introduces the initial Cargo manifests and lockfiles for the ToyDB project, establishing the build environment for a simple distributed SQL database. The project is configured to use the Rust 2024 edition and includes core dependencies such as Bincode 2.0 for serialization, Clap 4.5 for command-line argument parsing, and Tokio-based networking libraries. A separate documentation crate is also added with version 1.0.1.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 78 → 77 (-0.6)
• Rubric changed (rubric-2026.09.9 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 92 → 92 (+0.1)
• Architecture 100 → 100 (+0.0)
• Maturity 84 → 84 (+0.0)
• Readiness 64 → 65 (+1.1)
• Security 99 → 91 (-7.5)

• Documentation: no installation or build instructions
• Documentation: no project overview (docs/architecture/index.md)

• Documentation: no installation or build instructions (docs/architecture/storage.md)
• End-of-life runtime: Rust 1.96
• Flaky test: toydb::tests.anomalies
• Outdated: clap
• Outdated: config
• Outdated: crossbeam
• Outdated: log
• Outdated: petname
• Outdated: rand
• Outdated: uuid

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

erikgrinaker/toydb was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.