From 0336cac04ef22b45364f6e0cb304fb489481dde0 Mon Sep 17 00:00:00 2001 From: Erik Grinaker Date: Wed, 24 Jul 2024 14:08:31 +0200 Subject: [PATCH] README.md: more tweaks --- README.md | 53 +++++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e02acb8d9..ded02e31d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![CI](https://github.com/erikgrinaker/toydb/actions/workflows/ci.yml/badge.svg)](https://github.com/erikgrinaker/toydb/actions/workflows/ci.yml) -Distributed SQL database in Rust, written as an educational project. Built from scratch, including: +Distributed SQL database in Rust, built from scratch as an educational project. Main features: * [Raft distributed consensus engine][raft] for linearizable state machine replication. @@ -15,12 +15,12 @@ Distributed SQL database in Rust, written as an educational project. Built from * [SQL interface][sql] including joins, aggregates, and transactions. -Originally written to teach myself more about database iternals, toyDB is intended to illustrate -the basic architecture and concepts of distributed SQL databases. It should be functional and -correct, but focuses on simplicity and understandability. In particular, performance, scalability, -and availability are explicit non-goals -- these are major sources of complexity in -production-grade databases, which obscure the basic underlying concepts. Shortcuts have been taken -wherever possible. +Originally written to learn more about database internals, toyDB is intended to illustrate the basic +architecture and concepts of distributed SQL databases. It focuses on simplicity and +understandability, and should be functional and correct. Other aspects like performance, +scalability, and availability are explicit non-goals -- these are major sources of complexity in +production-grade databases, which obscure the basic underlying concepts. Shortcuts have been taken +where possible. [raft]: https://github.com/erikgrinaker/toydb/blob/master/src/raft/mod.rs [txn]: https://github.com/erikgrinaker/toydb/blob/master/src/storage/mvcc.rs @@ -39,12 +39,12 @@ wherever possible. * [SQL reference](docs/sql.md): toyDB SQL reference documentation. -* [References](docs/references.md): books and other material used while building toyDB. +* [References](docs/references.md): books and other materials used while building toyDB. ## Usage With a [Rust compiler](https://www.rust-lang.org/tools/install) installed, a local five-node -cluster can be started on `localhost` ports `9601` to `9605`, with data under `cluster/*/data`: +cluster can be built and started as: ``` $ ./cluster/run.sh @@ -74,22 +74,23 @@ toydb> SELECT * FROM movies; 3, 'Her' ``` -toyDB supports most common SQL features, including joins, aggregates, and ACID transactions. -Here is an `EXPLAIN` query plan of a more complex query, fetching movies from studios that -have released movies with an IMDb rating of 8 or more: +toyDB supports most common SQL features, including joins, aggregates, and transactions. + +Below is an `EXPLAIN` query plan of a more complex query, fetching movies from studios that have +released movies with an IMDb rating of 8 or more: ``` -toydb> EXPLAIN SELECT m.id, m.title, g.name AS genre, s.name AS studio, m.rating +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.id, m.title, g.name, s.name, m.rating, m.released - ORDER BY m.rating DESC, m.released ASC, m.id ASC; + 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.id, m.title, genre, studio, m.rating (dropped: m.released) -└─ Order: m.rating desc, m.released asc, m.id asc - └─ Projection: m.id, m.title, g.name as genre, s.name as studio, m.rating, m.released - └─ Aggregate: m.id, m.title, g.name, s.name, m.rating, m.released +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 @@ -101,17 +102,17 @@ Remap: m.id, m.title, genre, studio, m.rating (dropped: m.released) ## Architecture -[![toyDB architecture](./docs/images/architecture.svg)](./docs/architecture.md) - 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](./docs/architecture.md) for more details. +[![toyDB architecture](./docs/images/architecture.svg)](./docs/architecture.md) + ## Tests -toyDB mostly uses [Goldenscripts](https://github.com/erikgrinaker/goldenscript) for tests. These -are used to script various scenarios, capture events and output, and later assert that the -behavior remains the same. See e.g.: +toyDB mainly uses [Goldenscripts](https://github.com/erikgrinaker/goldenscript) 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](https://github.com/erikgrinaker/toydb/tree/master/src/raft/testscripts/node) * [MVCC transaction tests](https://github.com/erikgrinaker/toydb/tree/master/src/storage/testscripts/mvcc) @@ -154,8 +155,8 @@ The available workloads are: * `read`: single-row primary key lookups. * `write`: single-row inserts to sequential primary keys. -* `bank`: makes bank transfers between various customers and accounts. To make things interesting, - this includes joins, secondary indexes, sorting, and conflicts. +* `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`.