TopGit tracks erikgrinaker/toydb on GitHub as part of the Data family. The project has 7.3k stars. Distributed SQL database in Rust, written as an educational project
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Distributed SQL database in Rust, built from scratch as an educational project. Main features:
Raft distributed consensus for linearizable state machine replication.
ACID transactions with MVCC-based snapshot isolation.
Pluggable storage engine with BitCask and in-memory backends.
Iterator-based query engine with heuristic optimization and time-travel
support.
SQL interface including joins, aggregates, and transactions.
toyDB is intended to be simple and understandable, and also functional and correct. Other aspects
like performance, scalability, and availability are non-goals -- these are major sources of
complexity in production-grade databases, and obscure the basic underlying concepts. Shortcuts have
been taken where possible.
I originally wrote toyDB in 2020 to learn more about database internals. Since then, I've spent
several years building real distributed SQL databases at
CockroachDB and
Neon. Based on this experience, I've rewritten toyDB as a
simple illustration of the architecture and concepts behind distributed SQL databases.
Documentation
Architecture guide: a guided tour of toyDB's code and architecture.
SQL examples: walkthrough of toyDB's SQL features.
SQL reference: reference documentation for toyDB's SQL dialect.
References: research materials used while building toyDB.
Usage
With a Rust compiler installed, a local five-node
cluster can be built and started as:
$ ./cluster/run.sh
Starting 5 nodes on ports 9601-9605 with data under cluster/*/data/.
To connect to node 1, run: cargo run --release --bin toysql
toydb4 21:03:55 [INFO] Listening on [::1]:9604 (SQL) and [::1]:9704 (Raft)
toydb1 21:03:55 [INFO] Listening on [::1]:9601 (SQL) and [::1]:9701 (Raft)
toydb2 21:03:55 [INFO] Listening on [::1]:9602 (SQL) and [::1]:9702 (Raft)
toydb3 21:03:55 [INFO] Listening on [::1]:9603 (SQL) and [::1]:9703 (Raft)
toydb5 21:03:55 [INFO] Listening on [::1]:9605 (SQL) and [::1]:9705 (Raft)
toydb2 21:03:56 [INFO] Starting new election for term 1
[...]
toydb2 21:03:56 [INFO] Won election for term 1, becoming leader
A command-line client can be built and used with node 1 on localhost:9601:
$ cargo run --release --bin toysql
Connected to toyDB node n1. Enter !help for instructions.
toydb> CREATE TABLE movies (id INTEGER PRIMARY KEY, title VARCHAR NOT NULL);
toydb> INSERT INTO movies VALUES (1, 'Sicario'), (2, 'Stalker'), (3, 'Her');
toydb> SELECT * FROM movies;
1, 'Sicario'
2, 'Stalker'
3, 'Her'
toyDB supports most common SQL features, including joins, aggregates, and transactions. Below is an
EXPLAIN query plan of a more complex query (fetches all movies from studios that have released any
movie with an IMDb rating of 8 or more):
toydb> EXPLAIN SELECT m.title, g.name AS genre, s.name AS studio, m.rating
FROM movies m JOIN genres g ON m.genre_id = g.id,
studios s JOIN movies good ON good.studio_id = s.id AND good.rating >= 8
WHERE m.studio_id = s.id
GROUP BY m.title, g.name, s.name, m.rating, m.released
ORDER BY m.rating DESC, m.released ASC, m.title ASC;
Remap: m.title, genre, studio, m.rating (dropped: m.released)
└─ Order: m.rating desc, m.released asc, m.title asc
└─ Projection: m.title, g.name as genre, s.name as studio, m.rating, m.released
└─ Aggregate: m.title, g.name, s.name, m.rating, m.released
└─ HashJoin: inner on m.studio_id = s.id
├─ HashJoin: inner on m.genre_id = g.id
│ ├─ Scan: movies as m
│ └─ Scan: genres as g
└─ HashJoin: inner on s.id = good.studio_id
├─ Scan: studios as s
└─ Scan: movies as good (good.rating > 8 OR good.rating = 8)
Architecture
toyDB's architecture is fairly typical for a distributed SQL database: a transactional
key/value store managed by a Raft cluster with a SQL query engine on top. See the
architecture guide for more details.
Tests
toyDB mainly uses Goldenscripts for tests. These
script various scenarios, capture events and output, and later assert that the behavior remains the
same. See e.g.:
Raft cluster tests
MVCC transaction tests
SQL execution tests
End-to-end tests
Run tests with cargo test, or have a look at the latest
CI run.
Benchmarks
toyDB is not optimized for performance, but comes with a workload benchmark tool that can run
various workloads against a toyDB cluster. For example:
write: single-row inserts to sequential primary keys.
bank: bank transfers between various customers and accounts. To make things interesting, this
includes joins, secondary indexes, sorting, and conflicts.
For more information about workloads and parameters, run cargo run --bin workload -- --help.
Example workload results are listed below. Write performance is atrocious, due to
fsync and a lack of write batching in the Raft layer.
Disabling fsync, or using the in-memory engine, significantly improves write performance (at the
expense of durability).
Workload
BitCask
BitCask w/o fsync
Memory
read
14163 txn/s
13941 txn/s
13949 txn/s
write
35 txn/s
4719 txn/s
7781 txn/s
bank
21 txn/s
1120 txn/s
1346 txn/s
Debugging
VSCode and the CodeLLDB
extension can be used to debug toyDB, with the debug configuration under .vscode/launch.json.
Under the "Run and Debug" tab, select e.g. "Debug executable 'toydb'" or "Debug unit tests in
library 'toydb'".
The most recent commit recorded on erikgrinaker/toydb was 3 months ago, based on the GitHub push timestamp. The repository has 623 forks — one of the better signals of community interest.
How many stars does erikgrinaker/toydb have?
erikgrinaker/toydb has 7.3k GitHub stars — refresh the page for the live number, or check github.com/erikgrinaker/toydb. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What else is in the Data space?
erikgrinaker/toydb is tracked by TopGit under the Data category, alongside 6 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What language is erikgrinaker/toydb written in?
erikgrinaker/toydb is written primarily in Rust. GitHub's language field is based on the largest share of bytes in the default branch.
What topics is erikgrinaker/toydb associated with?
GitHub's repository topics for erikgrinaker/toydb: "database", "distributed", "mvcc", "raft", "rust", "sql". TopGit's editorial category is Data.
Where do I read more about erikgrinaker/toydb?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/erikgrinaker/toydb is the definitive source.
Why is erikgrinaker/toydb categorized under Data?
TopGit places erikgrinaker/toydb in the Data category based on its GitHub topics and description (tagged: "database", "distributed", "mvcc"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Want a second opinion on toydb?
Ask an AI that can read this page — one click and you get its take on toydb.