Repolode
Submit
erikgrinaker

erikgrinaker/toydb

A distributed SQL database written in Rust as an educational project, with Raft consensus, MVCC transactions and a SQL interface.

View on GitHub
Stars
7,304
Forks
625
Open issues
0
Last commit
last month

What is it?

toyDB is a distributed SQL database built from scratch in Rust to illustrate how distributed SQL systems work. It replicates state across a cluster using Raft consensus for linearizable state machine replication, and provides ACID transactions with MVCC-based snapshot isolation.

The storage layer is pluggable, with a BitCask backend and an in-memory backend. On top of the key/value store sits an iterator-based query engine that applies heuristic optimization and supports time-travel reads, along with a SQL interface covering joins, aggregates and transactions. A command-line client, toysql, connects to nodes, and EXPLAIN shows query plans.

The project prioritizes simplicity and correctness over performance, scalability and availability, so its code is meant to be read. Its tests are largely Goldenscript-based scenario tests, and the repository includes an architecture guide and a workload benchmark tool.

Key features

  • 01Raft consensus for linearizable replication across a cluster
  • 02ACID transactions with MVCC snapshot isolation
  • 03Pluggable storage with BitCask and in-memory engines
  • 04SQL support for joins, aggregates and transactions
  • 05EXPLAIN output showing query plans after heuristic optimization

Use cases

  • Learning how distributed SQL databases are structured internally
  • Studying Raft consensus and MVCC transactions through a readable Rust codebase
  • Experimenting with a small multi-node SQL cluster on a local machine

Quick start

  1. 1

    Install a Rust compiler (see the Rust installation page)

  2. 2

    Start a local five-node cluster

    ./cluster/run.sh
  3. 3

    Build and run the command-line client to connect to node 1

    cargo run --release --bin toysql

Things to know

  • Explicitly not optimized for performance, scalability, or availability.
  • Write performance is very poor due to fsync and lack of write batching.
  • Built as an educational project rather than for production use.

In collections

Databases & SQL toolsMicroservice frameworks & service infrastructure

Topics

#database#distributed-systems#raft#mvcc#sql#rust#transactions#distributed

FAQ

What is toydb?
A distributed SQL database written in Rust as an educational project, with Raft consensus, MVCC transactions and a SQL interface. toyDB is a distributed SQL database built from scratch in Rust to illustrate how distributed SQL systems work. It replicates state across a cluster using Raft consensus for linearizable state machine replication, and provides ACID transactions with MVCC-based snapshot isolation.
Is toydb free to use? What license does it have?
toydb is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is toydb still maintained?
Updated within 6 months. The last commit to toydb was on Oct 2, 2026.
What can I use toydb for?
Learning how distributed SQL databases are structured internally Studying Raft consensus and MVCC transactions through a readable Rust codebase Experimenting with a small multi-node SQL cluster on a local machine
How do I install toydb?
Install a Rust compiler (see the Rust installation page) Start a local five-node cluster: ./cluster/run.sh Build and run the command-line client to connect to node 1: cargo run --release --bin toysql
Where can I get toydb?
The source code and installation instructions are on GitHub: https://github.com/erikgrinaker/toydb

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects