{"id":51716539,"url":"https://github.com/appleweiping/cmu-15445-bustub","last_synced_at":"2026-07-17T03:36:18.725Z","repository":{"id":369939422,"uuid":"1292235810","full_name":"appleweiping/cmu-15445-bustub","owner":"appleweiping","description":"CMU 15-445 BusTub: a disk-oriented DBMS in C++ — buffer pool, B+tree index, query execution, concurrency control","archived":false,"fork":false,"pushed_at":"2026-07-07T15:10:43.000Z","size":6345,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T15:15:31.940Z","etag":null,"topics":["btree","bustub","cmu-15445","cpp","csdiy","database"],"latest_commit_sha":null,"homepage":null,"language":"C++","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/appleweiping.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":"2026-07-07T11:33:22.000Z","updated_at":"2026-07-07T15:14:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/appleweiping/cmu-15445-bustub","commit_stats":null,"previous_names":["appleweiping/cmu-15445-bustub"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/appleweiping/cmu-15445-bustub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appleweiping%2Fcmu-15445-bustub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appleweiping%2Fcmu-15445-bustub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appleweiping%2Fcmu-15445-bustub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appleweiping%2Fcmu-15445-bustub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appleweiping","download_url":"https://codeload.github.com/appleweiping/cmu-15445-bustub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appleweiping%2Fcmu-15445-bustub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35566571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["btree","bustub","cmu-15445","cpp","csdiy","database"],"created_at":"2026-07-17T03:36:16.149Z","updated_at":"2026-07-17T03:36:18.718Z","avatar_url":"https://github.com/appleweiping.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CMU 15-445 BusTub — Disk-Oriented DBMS in C++\n\n\u003e A relational database management system built from the official BusTub skeleton — an independent,\n\u003e from-skeleton implementation of **CMU 15-445/645 — Database Systems** (Carnegie Mellon University,\n\u003e Fall 2023), part of a [csdiy.wiki](https://csdiy.wiki/) full-catalog build.\n\n![status](https://img.shields.io/badge/status-P0--P4%20complete%20(2%20bonus%20partial)-brightgreen)\n![language](https://img.shields.io/badge/C++17-informational)\n![license](https://img.shields.io/badge/license-MIT-blue)\n\n\u003e The original upstream BusTub README is preserved as [`README_BUSTUB.md`](README_BUSTUB.md).\n\n## Overview\n\nBusTub is a disk-oriented relational DBMS used to teach CMU's database systems course. This repo\nimplements every project of the **Fall 2023** semester on top of the official\n[`cmu-db/bustub`](https://github.com/cmu-db/bustub) skeleton (tag `v20231227-2023fall`):\n\n- **P0** — a copy-on-write Trie key-value store, a thread-safe `TrieStore`, and the `upper`/`lower`\n  SQL scalar functions (with planner wiring).\n- **P1** — the storage / buffer-management layer: an LRU-K replacer, a disk scheduler with a\n  background worker thread, and the buffer pool manager.\n- **P2** — a disk-backed **extendible hash index**: RAII page guards, the header/directory/bucket\n  pages, and the full extendible hashing container (grow/split/merge, latch crabbing).\n- **P3** — the **query execution engine**: all access-method, join, aggregation, and sort/limit/topn\n  executors plus the window-function executor, and three optimizer rules.\n- **P4** — **multi-version concurrency control (MVCC)**: timestamps, an O(log N) watermark, tuple\n  reconstruction, MVCC scans, versioned insert/update/delete with undo logs, commit, garbage\n  collection, transaction abort, and primary-key index maintenance.\n\nEvery project is verified against the course's own test harness (the shipped gtest suites and the\n`bustub-sqllogictest` runner). All captured outputs live in [`results/`](results/).\n\n## Results (measured on Ubuntu 24.04 WSL2, g++ 13.3, CMake Release, 12 threads)\n\n| Project | What it implements | Result (measured) |\n|---|---|---|\n| **P0** C++ Primer | COW Trie, TrieStore, upper/lower | `trie_test` 14/14, `trie_noncopy` 1/1, `trie_store` 4/4, `trie_store_noncopy` 2/2, `p0.01-lower-upper.slt` pass |\n| **P1** Buffer Pool Manager | LRU-K replacer, disk scheduler, BPM | `lru_k_replacer_test` 1/1, `disk_scheduler_test` 1/1, `buffer_pool_manager_test` 2/2 |\n| **P2** Extendible Hash Index | page guards, htable pages, extendible hashing | `page_guard_test` 1/1, `extendible_htable_page_test` 2/2, `extendible_htable_test` 3/3, `extendible_htable_concurrent_test` 6/6 |\n| **P3** Query Execution | 12 executors + 3 optimizer rules | **21/21** official `p3.NN-*.slt` sqllogictest files pass |\n| **P4** Concurrency Control | MVCC timestamps/scan/DML/GC/abort/PK-index | `txn_timestamp_test` 2/2, `txn_scan_test` 2/2, `txn_executor_test` 10/10, `txn_index_test` 5/5, concurrent-insert pass |\n\nTotal verified: **P0** 21 gtests + 1 slt, **P1** 4 gtests, **P2** 12 gtests, **P3** 21 slt files,\n**P4** 19 serial gtests + concurrent-insert. See [`results/`](results/) for the raw run logs.\n\n### P3 query execution — all 21 official sqllogictests pass\n\n```\nPASS p3.00-primer      PASS p3.07-simple-agg        PASS p3.14-hash-join\nPASS p3.01-seqscan     PASS p3.08-group-agg-1       PASS p3.15-multi-way-hash-join\nPASS p3.02-insert      PASS p3.09-group-agg-2       PASS p3.16-sort-limit\nPASS p3.03-update      PASS p3.10-simple-join       PASS p3.17-topn\nPASS p3.04-delete      PASS p3.11-multi-way-join    PASS p3.18-integration-1\nPASS p3.05-index-scan  PASS p3.12-repeat-execute    PASS p3.19-integration-2\nPASS p3.06-empty-table PASS p3.13-nested-index-join PASS p3.20-window-function\n```\n\n## Implemented assignments\n\n- [x] **P0 — C++ Primer** — copy-on-write `Trie::Get/Put/Remove` with structural sharing; thread-safe\n  `TrieStore` (snapshot-read, single-writer); `StringExpression` upper/lower + planner `PlanFuncCall`.\n- [x] **P1 — Buffer Pool Manager** — LRU-K replacer (backward k-distance, +inf for \u003ck, LRU tiebreak);\n  disk scheduler (background thread over a request channel); BPM (free-list-first frames, dirty\n  writeback, pin counts, page-guard wrappers).\n- [x] **P2 — Extendible Hash Index** — `BasicPageGuard`/`ReadPageGuard`/`WritePageGuard` (move/drop/\n  upgrade, latch ordering); header/directory/bucket pages; `DiskExtendibleHashTable` insert with\n  directory growth + bucket split + entry migration, get, remove with merge + shrink; latch crabbing.\n- [x] **P3 — Query Execution** — SeqScan, Insert, Update, Delete, IndexScan, Aggregation,\n  NestedLoopJoin, HashJoin, NestedIndexJoin, Sort, Limit, TopN, WindowFunction; optimizer rules\n  SeqScan→IndexScan, NLJ→HashJoin, Sort+Limit→TopN.\n- [x] **P4 — Concurrency Control (MVCC)** — Begin/Commit timestamps, O(log N) watermark,\n  `ReconstructTuple`, MVCC seq/index scan, versioned insert/update/delete with undo logs,\n  garbage collection, transaction abort, primary-key index (dup detection, RID reuse, PK-update\n  delete+insert), atomic version-link CAS on writes.\n- [~] **P4 bonus** — serializable OCC verification and the concurrent delete+reinsert stress test are\n  documented partials (see *Partials* below).\n\n## Project structure\n\n```\ncmu-15445-bustub/\n├── src/\n│   ├── primer/                 # P0: trie, trie_store\n│   ├── buffer/                 # P1: lru_k_replacer, buffer_pool_manager\n│   ├── storage/\n│   │   ├── disk/               # P1: disk_scheduler\n│   │   └── page/               # P2: page_guard, extendible_htable_*_page\n│   ├── container/disk/hash/    # P2: disk_extendible_hash_table\n│   ├── execution/              # P3: *_executor, execution_common (P4 helpers)\n│   ├── optimizer/              # P3: nlj_as_hash_join, sort_limit_as_topn, seqscan_as_indexscan\n│   └── concurrency/            # P4: transaction_manager, watermark\n├── test/                       # course-provided gtest + sqllogictest suites\n├── results/                    # captured, measured test outputs (this build)\n└── third_party/                # vendored deps (fmt, googletest, libpg_query, ...)\n```\n\n## How to run\n\nBusTub is Linux/macOS-oriented; this build uses **WSL2 Ubuntu 24.04**. C: is kept clean by building on\na native ext4 path (git stays on the Windows drive; source is rsync'd to `~/bustub-build` to avoid 9p\nfilesystem slowness).\n\n```bash\n# 1. Install toolchain deps (Ubuntu):\nsudo ./build_support/packages.sh -y   # or: build-essential cmake zlib1g-dev libelf-dev libdwarf-dev\n\n# 2. Configure + build (Release):\nmkdir build \u0026\u0026 cd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\n\n# 3. Run the tests. NOTE: the course ships public tests with a DISABLED_ prefix,\n#    so pass --gtest_also_run_disabled_tests.\nmake trie_test trie_store_test lru_k_replacer_test buffer_pool_manager_test \\\n     disk_scheduler_test page_guard_test extendible_htable_test \\\n     txn_timestamp_test txn_scan_test txn_executor_test txn_index_test -j$(nproc)\n./test/trie_test --gtest_also_run_disabled_tests\n./test/buffer_pool_manager_test --gtest_also_run_disabled_tests\n./test/extendible_htable_test --gtest_also_run_disabled_tests\n./test/txn_executor_test --gtest_also_run_disabled_tests\n\n# 4. P3 query execution is graded by the sqllogictest runner:\nmake sqllogictest -j$(nproc)\nfor f in ../test/sql/p3.[0-9]*.slt; do ./bin/bustub-sqllogictest \"$f\"; done\n```\n\n## Verification\n\nEach project was verified with the course's **own** shipped tests, and the actual output was captured\nto `results/`:\n\n- `results/p0_primer.txt` — trie / trie_store gtests + `p0.01-lower-upper.slt`.\n- `results/p1_buffer_pool.txt` — LRU-K, disk scheduler, buffer pool manager gtests.\n- `results/p2_extendible_hash.txt` — page guard, htable page, htable, and concurrent htable gtests.\n- `results/p3_query_execution.txt` — all 21 `p3.NN-*.slt` sqllogictest files (21 passed, 0 failed).\n- `results/p4_concurrency_control.txt` — timestamp, scan, executor, and index MVCC gtests.\n\n## Partials\n\nPer the build spec, anything not fully passing is documented rather than faked:\n\n- **P4 bonus — Serializable verification (`TxnBonusTest.SerializableTest`)**: `VerifyTxn` returns\n  `true` (no OCC backward validation), so serializable-isolation abort-on-conflict is not enforced.\n  Snapshot-isolation (the default, and everything P4 tasks 1–4 require) is fully implemented.\n- **P4 — `IndexConcurrentUpdateTest`** (the 50-trial × 8-thread delete+reinsert stress test) is not\n  passing. The single-writer serial correctness is complete and every serial P4 test passes; the\n  write path installs new versions with an atomic compare-and-set on the version link, and\n  `IndexConcurrentInsertTest` passes. The delete+reinsert stress path needs additional in-page\n  version-chain locking to fully serialize concurrent reuse of a deleted RID, which is not\n  implemented here. This is a documented partial, not a stub.\n\nEverything else — P0, P1, P2, P3 in full, and P4 tasks 1–4 (timestamps, watermark, tuple\nreconstruction, MVCC scans, versioned DML, commit, garbage collection, abort, primary-key index) —\nis fully implemented and verified.\n\n## Tech stack\n\nC++17, CMake, GoogleTest, the BusTub sqllogictest harness; `fmt`, `libpg_query` (SQL parser),\n`murmur3`, and other vendored `third_party` libraries. Built with g++ 13 on Ubuntu 24.04 (WSL2).\n\n## Key ideas / what I learned\n\n- **Copy-on-write persistent data structures** — the Trie rebuilds only the path to a changed node\n  and shares all untouched subtrees, giving cheap immutable snapshots for lock-free reads.\n- **Buffer management** — LRU-K's backward k-distance approximates access frequency far better than\n  plain LRU; a disk scheduler decouples I/O from the caller via futures and a background thread.\n- **Extendible hashing** — the directory doubles on overflow while buckets split locally; latch\n  crabbing (header→directory→bucket) keeps concurrent operations correct without a global lock.\n- **The Volcano / iterator model** — every operator is a pull-based `Init`/`Next`; the optimizer\n  rewrites the plan tree (NLJ→hash join, sort+limit→top-N, seq-scan→index-scan) before execution.\n- **MVCC** — tuples carry timestamps and a chain of undo logs; a reader reconstructs the version\n  visible at its read timestamp, writers stamp a temporary (transaction-id) timestamp until commit,\n  a watermark bounds what garbage collection may reclaim, and write-write conflicts are detected via\n  an atomic compare-and-set on the version link.\n\n## Credits \u0026 license\n\nBased on the projects of **CMU 15-445/645 Database Systems (Fall 2023)** by Andy Pavlo and the\nCarnegie Mellon University Database Group. This repository is an independent educational\nimplementation built on the official [`cmu-db/bustub`](https://github.com/cmu-db/bustub) skeleton\n(tag `v20231227-2023fall`); all course materials, the skeleton, and the test suites belong to their\noriginal authors and remain under CMU's MIT [`LICENSE`](LICENSE). Original implementation code in\nthis repo is released under the same MIT terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappleweiping%2Fcmu-15445-bustub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappleweiping%2Fcmu-15445-bustub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappleweiping%2Fcmu-15445-bustub/lists"}