From eedac6223b05784b17e1615103e645242aa00207 Mon Sep 17 00:00:00 2001 From: All Asmaul Husnain <2263081025@uttarauniversity.edu.bd> Date: Thu, 1 Oct 2026 21:51:10 +0600 Subject: [PATCH] docs: improve project showcase --- README.md | 24 +++++++++++++++++++++++- docs/images/architecture.svg | 9 +++++++++ docs/images/btree.svg | 19 +++++++++++++++++++ docs/images/demo.svg | 19 +++++++++++++++++++ 4 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 docs/images/architecture.svg create mode 100644 docs/images/btree.svg create mode 100644 docs/images/demo.svg diff --git a/README.md b/README.md index 0c49d6a..093d61c 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,15 @@ db > .exit The database is persisted to `build/sqlite.db`, so data can be written, the process closed, and the database reopened later. -For the repository showcase, the most useful visuals are an actual terminal capture of this workflow and a B-tree output capture after inserting enough rows to trigger a leaf split. These should be generated from the current build rather than using mock screenshots. +The repository includes visual documentation for the shell, B tree structure, and storage architecture. The terminal visual shows the supported workflow, while the B tree visual shows the first leaf split. + +![sqlite-c shell demo](docs/images/demo.svg) + +![B tree after the first leaf split](docs/images/btree.svg) + +![sqlite-c architecture](docs/images/architecture.svg) + +These visuals document the current design. Real terminal screenshots from the current build can be added later when benchmark and demonstration captures are collected. ## What is implemented @@ -135,6 +143,20 @@ row count B-tree pages use a compact fixed layout designed to keep the storage implementation understandable. +## Performance + +The benchmark inserts 1,000 rows through the public table API and measures the insertion phase. The benchmark is intended for repeatable local comparisons rather than as a claim of production database performance. + +The current write path keeps modified pages in the pager cache during inserts and persists them during an explicit flush. This avoids performing a file write and fflush for every inserted row. + +Run it with: + +```bash +make benchmark +``` + +Record benchmark results only from the current build and environment. Do not compare numbers across machines without noting the compiler, operating system, and build flags. + ## Testing and verification The test suite covers: diff --git a/docs/images/architecture.svg b/docs/images/architecture.svg new file mode 100644 index 0000000..3d63c49 --- /dev/null +++ b/docs/images/architecture.svg @@ -0,0 +1,9 @@ + + +sqlite-c architecture +Interactive shellSQL parserTable APIB treePagerDatabase file + +ordered leaf pages +internal root routing +fixed 4096 byte pages + \ No newline at end of file diff --git a/docs/images/btree.svg b/docs/images/btree.svg new file mode 100644 index 0000000..f829e08 --- /dev/null +++ b/docs/images/btree.svg @@ -0,0 +1,19 @@ + + +B tree after the first leaf split + +internal +separator 13 + + + +leaf +13 rows +1 2 3 4 5 6 7 +8 9 10 11 12 13 + +leaf +1 row +14 +The leaf chain keeps ordered traversal independent of the root routing structure. + \ No newline at end of file diff --git a/docs/images/demo.svg b/docs/images/demo.svg new file mode 100644 index 0000000..34aa317 --- /dev/null +++ b/docs/images/demo.svg @@ -0,0 +1,19 @@ + + + + +sqlite-c demo +db >INSERT INTO users VALUES (1, 'alice', 'alice@example.com'); +db >INSERT INTO users VALUES (2, 'bob', 'bob@example.com'); +db >SELECT * FROM users; +1 | alice | alice@example.com +2 | bob | bob@example.com +db >SELECT * FROM users WHERE id = 2; +2 | bob | bob@example.com +db >.btree +B tree: +leaf (rows 2) +1 +2 +example session + \ No newline at end of file