https://github.com/feichai0017/QuillSQL

An educational Rust relational database (RDBMS) inspired by CMU 15445
https://github.com/feichai0017/QuillSQL

bustub cmu15445 database oltp rust

Last synced: 3 months ago
JSON representation

An educational Rust relational database (RDBMS) inspired by CMU 15445

Host: GitHub
URL: https://github.com/feichai0017/QuillSQL
Owner: feichai0017
License: mit
Created: 2025-03-31T12:17:45.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2025-12-04T04:02:16.000Z (4 months ago)
Last Synced: 2025-12-05T14:35:21.835Z (4 months ago)
Topics: bustub, cmu15445, database, oltp, rust
Language: Rust
Homepage: https://quillsql.fly.dev
Size: 3.66 MB
Stars: 154
Watchers: 10
Forks: 13
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

fucking-awesome-rust - QuillSQL - An educational Rust relational database (RDBMS) inspired by CMU 15445 (Applications / Database)
awesome-rust - QuillSQL - An educational Rust relational database (RDBMS) inspired by CMU 15445 (Applications / Database)
awesome-rust-with-stars - QuillSQL - 01-19 | (Applications / Database)

README

          # QuillSQL

[![Crates.io](https://img.shields.io/crates/v/quill-sql.svg)](https://crates.io/crates/quill-sql)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[![Discord](https://img.shields.io/discord/1458041939587764247?label=Discord&logo=discord&logoColor=white)](https://discord.gg/dJqa4RYW65)

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/feichai0017/QuillSQL)



  

  An educational Rust RDBMS for cmu15445-style teaching (BusTub-inspired)



## ✨ Highlights

- **Clean architecture**: SQL → Logical Plan → Physical Plan → Volcano executor

- **Transaction control**: `BEGIN/COMMIT/ROLLBACK`, `SET TRANSACTION`, `SET SESSION TRANSACTION`, enforced `READ ONLY`, row/table locks

- **B+Tree index**: OLC readers, B-link pages, latch crabbing, range scan iterator

- **Buffer manager**: LRU-K + TinyLFU, WAL-aware dirty tracking, prefetch API, background writer

- **Asynchronous storage**: Dispatcher + io_uring worker pool for data pages, plus a buffered WAL runtime with cached segment handles for sequential log I/O

- **Streaming / Prefetch**: Large sequential scans bypass the cache via a small direct I/O ring buffer; targeted prefetch warms hot paths without pins

- **WAL & Recovery (ARIES-inspired)**: FPW, logical heap/index records, DPT, chained CLR, per-transaction undo chains, idempotent replays

- **Information schema**: `information_schema.schemas`, `tables`, `columns`, `indexes`

- **Docs**: 📖 **[Read the Book Online](https://feichai0017.github.io/QuillSQL/)** 

---

## Demo



  

  Built-in web TTY — commands mirror our SQL test suite.



- Run `cargo run --bin server` and open http://127.0.0.1:8080

- Commands: `help`, `docs`, `doc `, `examples`, `example `, `github`, `profile`

- Example scripts are pulled straight from `src/tests/sql_example/`

---

## 🎓 Teaching & Research Friendly

- Clear module boundaries, suitable for classroom assignments and research prototypes. Inspired by CMU 15-445 BusTub with strengthened WAL/Recovery, observability, and centralized configuration.

- Pluggable pieces: buffer pool, index, WAL, and recovery are decoupled for side-by-side experiments.

- Readability-first: simple, pragmatic code with minimal hot-path allocations.

## 🚀 Quick Start

```bash

cargo run --bin client

# or open a persistent DB file

cargo run --bin client -- --file my.db

# start web server (http://127.0.0.1:8080)

cargo run --bin server

# specify data file and listening addr

QUILL_DB_FILE=my.db QUILL_HTTP_ADDR=0.0.0.0:8080 cargo run --bin server --release

# batch API (optional)

curl -XPOST http://127.0.0.1:8080/api/sql_batch -H 'content-type: application/json' \

     -d '{"sql": "SHOW TABLES; EXPLAIN SELECT 1;"}'

```

Sample session:

```sql

CREATE TABLE t(id INT, v INT DEFAULT 0);

INSERT INTO t(id, v) VALUES (1, 10), (2, 20), (3, 30);

SELECT id, v FROM t WHERE v > 10 ORDER BY id DESC LIMIT 1;

SHOW DATABASES;

SHOW TABLES;

EXPLAIN SELECT id, COUNT(*) FROM t GROUP BY id ORDER BY id;

```

## 🧱 Supported SQL

- **Data types**

  - `BOOLEAN`, `INT8/16/32/64`, `UINT8/16/32/64`, `FLOAT32/64`, `VARCHAR(n)`

- **CREATE TABLE**

  - Column options: `NOT NULL` | `DEFAULT `

  - Example:

    ```sql

    CREATE TABLE t(

      id INT64 NOT NULL,

      v  INT32 DEFAULT 0

    );

    ```

- **CREATE INDEX**

  - Example:

    ```sql

    CREATE INDEX idx_t_id ON t(id);

    ```

- **DROP**

  - `DROP TABLE [IF EXISTS] `

  - `DROP INDEX [IF EXISTS] `

  - Example:

    ```sql

    DROP INDEX IF EXISTS idx_orders_user_id;

    DROP TABLE orders;

    ```

- **INSERT**

  - `INSERT INTO ... VALUES (...)` and `INSERT INTO ... SELECT ...`

- **SELECT**

- Projection: columns, literals, aliases

- FROM: table | subquery (`FROM (SELECT ...)`) — alias not yet supported

- WHERE: comparison/logical operators `= != > >= < <= AND OR`

- GROUP BY: aggregates `COUNT(expr|*)`, `AVG(expr)`

- ORDER BY: `ASC|DESC`, supports `NULLS FIRST|LAST`

- LIMIT/OFFSET

- JOIN: `INNER JOIN` (with `ON` condition), `CROSS JOIN`

- **UPDATE**

  - `UPDATE t SET col = expr [, ...] [WHERE predicate]`

- **DELETE**

  - `DELETE FROM t [WHERE predicate]`

- **SHOW**

- `SHOW DATABASES;` (rewritten to `SELECT schema FROM information_schema.schemas`)

- `SHOW TABLES;` (rewritten to `SELECT table_name FROM information_schema.tables`)

- **EXPLAIN**

  - `EXPLAIN ` returns a single column named `plan` with multiple lines showing the logical plan tree

## ⚠️ Current Limitations

- Not yet supported: `ALTER`, predicate locking.

- Not implemented: outer joins (Left/Right/Full), arithmetic expressions, table/subquery aliases

- `ORDER BY` `DESC` / `NULLS FIRST|LAST` currently affects sorting only (not storage layout)

## 🧪 Testing

```bash

cargo test -q

```

## ⚙️ Configuration

Minimal environment variables (runtime only)

- PORT: bind port (overrides the port of `QUILL_HTTP_ADDR`)

- QUILL_HTTP_ADDR: listen address (default `0.0.0.0:8080`)

- QUILL_DB_FILE: path to database file (uses a temp DB if unset)

- QUILL_DEFAULT_ISOLATION: default session isolation (`read-uncommitted`, `read-committed`, `repeatable-read`, `serializable`)

- RUST_LOG: log level (e.g., info, debug)

Programmatic options live in `quillsql::config` (see docs) — build `DatabaseOptions` with `WalOptions`, `BufferPoolConfig`, `BTreeConfig`, etc., and pass into `Database::new_*_with_options`. Examples in the docs remain unchanged.

## 📦 Docker

```bash

# build

docker build -t quillsql:latest .

# run (ephemeral in-memory DB)

docker run --rm -p 8080:8080 quillsql:latest

# run with persistent file mounted

docker run --rm -p 8080:8080 -e QUILL_DB_FILE=/data/my.db -v $(pwd)/data:/data quillsql:latest

```

Includes sqllogictest-based cases:

- `src/tests/sql_example/create_table.slt`

- `src/tests/sql_example/create_index.slt`

- `src/tests/sql_example/insert.slt`

- `src/tests/sql_example/show_explain.slt`

- `src/tests/sql_example/delete.slt`

## 📚 Acknowledgements

- [BustubX](https://github.com/systemxlabs/bustubx)

- [CMU 15-445/645 Database Systems](https://15445.courses.cs.cmu.edu/)

##  Community

**Build. Break. Benchmark. Repeat.**  

QuillSQL has a Discord server for discussions, support, and *experimental* DB hacking.

**What you can do here:**

- 🧩 **Design discussions** — parser / executor / storage architecture

- 🧪 **Experiments & prototypes** — new operators, indexes, optimizer ideas, wild hacks

- 📈 **Benchmarks & profiling** — perf numbers, flamegraphs, regression hunts

- 📚 **Research notes** — papers, learning resources, implementation notes

- 🤝 **Contributing help** — “good first issue”, PR reviews, roadmap brainstorming

**Join:** https://discord.gg/dJqa4RYW65

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/feichai0017/QuillSQL

Awesome Lists containing this project

README