{"id":36344345,"url":"https://github.com/feichai0017/QuillSQL","last_synced_at":"2026-01-11T18:00:48.509Z","repository":{"id":288526875,"uuid":"957960956","full_name":"feichai0017/QuillSQL","owner":"feichai0017","description":"An educational Rust relational database (RDBMS) inspired by CMU 15445","archived":false,"fork":false,"pushed_at":"2025-12-04T04:02:16.000Z","size":3836,"stargazers_count":154,"open_issues_count":0,"forks_count":13,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-12-05T14:35:21.835Z","etag":null,"topics":["bustub","cmu15445","database","oltp","rust"],"latest_commit_sha":null,"homepage":"https://quillsql.fly.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/feichai0017.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-31T12:17:45.000Z","updated_at":"2025-12-04T04:20:37.000Z","dependencies_parsed_at":"2025-04-18T16:14:12.834Z","dependency_job_id":"d4212db5-eab0-494f-9f69-ea0b79557663","html_url":"https://github.com/feichai0017/QuillSQL","commit_stats":null,"previous_names":["feichai0017/quillsql"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/feichai0017/QuillSQL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feichai0017%2FQuillSQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feichai0017%2FQuillSQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feichai0017%2FQuillSQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feichai0017%2FQuillSQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/feichai0017","download_url":"https://codeload.github.com/feichai0017/QuillSQL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feichai0017%2FQuillSQL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28316919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T14:58:17.114Z","status":"ssl_error","status_checked_at":"2026-01-11T14:55:53.580Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bustub","cmu15445","database","oltp","rust"],"created_at":"2026-01-11T13:00:32.117Z","updated_at":"2026-01-11T18:00:48.493Z","avatar_url":"https://github.com/feichai0017.png","language":"Rust","funding_links":[],"categories":["Applications"],"sub_categories":["Database"],"readme":"# QuillSQL\n\n[![Crates.io](https://img.shields.io/crates/v/quill-sql.svg)](https://crates.io/crates/quill-sql)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Discord](https://img.shields.io/discord/1458041939587764247?label=Discord\u0026logo=discord\u0026logoColor=white)](https://discord.gg/dJqa4RYW65)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/feichai0017/QuillSQL)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"/public/rust-db.png\" alt=\"QuillSQL Architecture\" width=\"720\"/\u003e\n  \u003cp\u003e\u003cem\u003eAn educational Rust RDBMS for cmu15445-style teaching (BusTub-inspired)\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n## ✨ Highlights\n\n- **Clean architecture**: SQL → Logical Plan → Physical Plan → Volcano executor\n- **Transaction control**: `BEGIN/COMMIT/ROLLBACK`, `SET TRANSACTION`, `SET SESSION TRANSACTION`, enforced `READ ONLY`, row/table locks\n- **B+Tree index**: OLC readers, B-link pages, latch crabbing, range scan iterator\n- **Buffer manager**: LRU-K + TinyLFU, WAL-aware dirty tracking, prefetch API, background writer\n- **Asynchronous storage**: Dispatcher + io_uring worker pool for data pages, plus a buffered WAL runtime with cached segment handles for sequential log I/O\n- **Streaming / Prefetch**: Large sequential scans bypass the cache via a small direct I/O ring buffer; targeted prefetch warms hot paths without pins\n- **WAL \u0026 Recovery (ARIES-inspired)**: FPW, logical heap/index records, DPT, chained CLR, per-transaction undo chains, idempotent replays\n- **Information schema**: `information_schema.schemas`, `tables`, `columns`, `indexes`\n- **Docs**: 📖 **[Read the Book Online](https://feichai0017.github.io/QuillSQL/)** \n\n---\n\n## Demo\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"/public/terminal-preview.svg\" alt=\"QuillSQL Web Terminal\" width=\"720\"/\u003e\n  \u003cp\u003e\u003cem\u003eBuilt-in web TTY — commands mirror our SQL test suite.\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\n- Run `cargo run --bin server` and open http://127.0.0.1:8080\n- Commands: `help`, `docs`, `doc \u003cname\u003e`, `examples`, `example \u003cname\u003e`, `github`, `profile`\n- Example scripts are pulled straight from `src/tests/sql_example/`\n\n---\n\n## 🎓 Teaching \u0026 Research Friendly\n\n- Clear module boundaries, suitable for classroom assignments and research prototypes. Inspired by CMU 15-445 BusTub with strengthened WAL/Recovery, observability, and centralized configuration.\n- Pluggable pieces: buffer pool, index, WAL, and recovery are decoupled for side-by-side experiments.\n- Readability-first: simple, pragmatic code with minimal hot-path allocations.\n\n## 🚀 Quick Start\n\n```bash\ncargo run --bin client\n\n# or open a persistent DB file\ncargo run --bin client -- --file my.db\n\n# start web server (http://127.0.0.1:8080)\ncargo run --bin server\n\n# specify data file and listening addr\nQUILL_DB_FILE=my.db QUILL_HTTP_ADDR=0.0.0.0:8080 cargo run --bin server --release\n\n# batch API (optional)\ncurl -XPOST http://127.0.0.1:8080/api/sql_batch -H 'content-type: application/json' \\\n     -d '{\"sql\": \"SHOW TABLES; EXPLAIN SELECT 1;\"}'\n```\n\nSample session:\n```sql\nCREATE TABLE t(id INT, v INT DEFAULT 0);\nINSERT INTO t(id, v) VALUES (1, 10), (2, 20), (3, 30);\n\nSELECT id, v FROM t WHERE v \u003e 10 ORDER BY id DESC LIMIT 1;\n\nSHOW DATABASES;\nSHOW TABLES;\n\nEXPLAIN SELECT id, COUNT(*) FROM t GROUP BY id ORDER BY id;\n```\n\n## 🧱 Supported SQL\n\n- **Data types**\n  - `BOOLEAN`, `INT8/16/32/64`, `UINT8/16/32/64`, `FLOAT32/64`, `VARCHAR(n)`\n\n- **CREATE TABLE**\n  - Column options: `NOT NULL` | `DEFAULT \u003cliteral\u003e`\n  - Example:\n    ```sql\n    CREATE TABLE t(\n      id INT64 NOT NULL,\n      v  INT32 DEFAULT 0\n    );\n    ```\n\n- **CREATE INDEX**\n  - Example:\n    ```sql\n    CREATE INDEX idx_t_id ON t(id);\n    ```\n\n- **DROP**\n  - `DROP TABLE [IF EXISTS] \u003cname\u003e`\n  - `DROP INDEX [IF EXISTS] \u003cname\u003e`\n  - Example:\n    ```sql\n    DROP INDEX IF EXISTS idx_orders_user_id;\n    DROP TABLE orders;\n    ```\n\n- **INSERT**\n  - `INSERT INTO ... VALUES (...)` and `INSERT INTO ... SELECT ...`\n\n- **SELECT**\n- Projection: columns, literals, aliases\n- FROM: table | subquery (`FROM (SELECT ...)`) — alias not yet supported\n- WHERE: comparison/logical operators `= != \u003e \u003e= \u003c \u003c= AND OR`\n- GROUP BY: aggregates `COUNT(expr|*)`, `AVG(expr)`\n- ORDER BY: `ASC|DESC`, supports `NULLS FIRST|LAST`\n- LIMIT/OFFSET\n- JOIN: `INNER JOIN` (with `ON` condition), `CROSS JOIN`\n\n- **UPDATE**\n  - `UPDATE t SET col = expr [, ...] [WHERE predicate]`\n- **DELETE**\n  - `DELETE FROM t [WHERE predicate]`\n\n- **SHOW**\n- `SHOW DATABASES;` (rewritten to `SELECT schema FROM information_schema.schemas`)\n- `SHOW TABLES;` (rewritten to `SELECT table_name FROM information_schema.tables`)\n\n- **EXPLAIN**\n  - `EXPLAIN \u003cstatement\u003e` returns a single column named `plan` with multiple lines showing the logical plan tree\n\n## ⚠️ Current Limitations\n\n- Not yet supported: `ALTER`, predicate locking.\n- Not implemented: outer joins (Left/Right/Full), arithmetic expressions, table/subquery aliases\n- `ORDER BY` `DESC` / `NULLS FIRST|LAST` currently affects sorting only (not storage layout)\n\n## 🧪 Testing\n\n```bash\ncargo test -q\n```\n\n## ⚙️ Configuration\n\nMinimal environment variables (runtime only)\n- PORT: bind port (overrides the port of `QUILL_HTTP_ADDR`)\n- QUILL_HTTP_ADDR: listen address (default `0.0.0.0:8080`)\n- QUILL_DB_FILE: path to database file (uses a temp DB if unset)\n- QUILL_DEFAULT_ISOLATION: default session isolation (`read-uncommitted`, `read-committed`, `repeatable-read`, `serializable`)\n- RUST_LOG: log level (e.g., info, debug)\n\nProgrammatic 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.\n\n## 📦 Docker\n\n```bash\n# build\ndocker build -t quillsql:latest .\n\n# run (ephemeral in-memory DB)\ndocker run --rm -p 8080:8080 quillsql:latest\n\n# run with persistent file mounted\ndocker run --rm -p 8080:8080 -e QUILL_DB_FILE=/data/my.db -v $(pwd)/data:/data quillsql:latest\n```\n\nIncludes sqllogictest-based cases:\n\n- `src/tests/sql_example/create_table.slt`\n- `src/tests/sql_example/create_index.slt`\n- `src/tests/sql_example/insert.slt`\n- `src/tests/sql_example/show_explain.slt`\n- `src/tests/sql_example/delete.slt`\n\n## 📚 Acknowledgements\n\n- [BustubX](https://github.com/systemxlabs/bustubx)\n- [CMU 15-445/645 Database Systems](https://15445.courses.cs.cmu.edu/)\n\n## \u003cimg src=\"https://cdn.simpleicons.org/discord/5865F2\" height=\"20\" /\u003e Community\n\n**Build. Break. Benchmark. Repeat.**  \nQuillSQL has a Discord server for discussions, support, and *experimental* DB hacking.\n\n**What you can do here:**\n- 🧩 **Design discussions** — parser / executor / storage architecture\n- 🧪 **Experiments \u0026 prototypes** — new operators, indexes, optimizer ideas, wild hacks\n- 📈 **Benchmarks \u0026 profiling** — perf numbers, flamegraphs, regression hunts\n- 📚 **Research notes** — papers, learning resources, implementation notes\n- 🤝 **Contributing help** — “good first issue”, PR reviews, roadmap brainstorming\n\n**Join:** https://discord.gg/dJqa4RYW65\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeichai0017%2FQuillSQL","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffeichai0017%2FQuillSQL","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeichai0017%2FQuillSQL/lists"}