# BusTub: the CMU teaching database you build yourself, not deploy

> BusTub is the relational database management system written for CMU's 15-445/645 course. It ships an interactive SQL shell, but the README says it plainly: educational purposes only, not for production.

**cmu-db/bustub** — The BusTub Relational Database Management System (Educational)

- Repository: https://github.com/cmu-db/bustub
- Website: https://15445.courses.cs.cmu.edu
- Stars: 5,116 · Forks: 2,070
- Language: C++
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/cmu-db-bustub

## What BusTub is for, and who it is not for

BusTub is a relational database management system built at Carnegie Mellon University for the Introduction to Database Systems course, 15-445/645. The README is unusually direct about the audience: the system was developed for educational purposes and should not be used in production environments. That single sentence should decide most adoption questions.

The people who get value from it are students and self-learners who want to implement database internals in C++ rather than read about them. The repository layout reflects that: src/ holds the engine, test/ holds the test suite, third_party/ holds dependencies, and tools/ holds the shell and utilities. A course project slots into that structure, so the work is code inside a working system rather than a toy written from scratch.

Everyone else should look elsewhere. If you need a database to store application data, BusTub is the wrong tool, and the project says so itself. The interesting question is not whether it is production ready. It is whether the teaching value justifies the setup cost, and for the intended audience it usually does.

## The engine layout and where your code goes

The repository is organized as a conventional C++ CMake project. CMakeLists.txt at the top level drives the build, .clang-format and .clang-tidy define the code style and static checks, and build_support/ contains the packaging script. The src/ tree holds the database itself, test/ holds the tests that exercise it, and tools/ contains the shell binary. A course assignment typically asks you to replace or complete a component inside src/ and then pass the matching tests.

The README states that BusTub supports basic SQL and comes with an interactive shell, and that you can get it running after finishing all the course projects. Read that second clause carefully. The shell is the end state of the course, not a starting point. A fresh clone is a skeleton with components to implement, so a student who expects to type SQL on day one will be disappointed.

Two build-time switches matter. Debug mode enables AddressSanitizer by default, and the CMake variable BUSTUB_SANITIZER selects a different sanitizer such as thread. Those options exist because the failures this codebase produces are memory and concurrency failures, and they are far easier to diagnose with instrumentation than with print statements.

## Building BusTub on Ubuntu 24.04 or macOS

The README recommends Ubuntu 24.04, or macOS on M1, M2 or Intel. It states that no other environments are supported, that WSL is not supported, and that the grading environment runs Ubuntu 24.04. Take that boundary seriously: if your machine runs Windows, the documented path is a Linux VM, not WSL.

Start by installing the required packages. On Linux the script is run with sudo; on macOS it is run without.

```bash
# Linux
sudo build_support/packages.sh
# macOS
build_support/packages.sh
```

Then configure and build. The README gives this sequence, with the build directory created first.

```bash
mkdir build
cd build
cmake ..
make
```

For development work, configure a debug build instead. The README notes that this enables AddressSanitizer by default, which turns silent memory corruption into a hard failure at the point it happens.

```bash
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j`nproc`
```

If you want a different sanitizer, the README shows the thread sanitizer selected through a CMake variable at configure time.

```bash
cmake -DCMAKE_BUILD_TYPE=Debug -DBUSTUB_SANITIZER=thread ..
make -j`nproc`
```

What you should see is a completed build in build/. After that, the interactive shell is the payoff, and the README ties a running shell to having finished the course projects. If your shell does not come up or does not answer queries, that is the expected state of an unfinished implementation, not a broken install.

## Cloning it the way the course intends

The README does not tell you to fork the public repository. It walks through duplicating it into a private repository instead, and the reason is academic integrity. The README carries a warning in capitals for students in the class: do not directly fork the repo, and do not push project solutions publicly. It calls that an academic integrity violation that can lead to a degree being revoked, even after graduation. A second warning addresses students outside CMU: do not make solutions publicly available, or you will be banned from the autograder.

The documented procedure is a bare clone followed by a mirror push into your own private repository, then a clone of that private repository, then adding the public repository as a second remote named public. The README gives the remote setup and a verification command that prints fetch and push URLs for both origin and public.

```bash
git clone --bare https://github.com/cmu-db/bustub.git bustub-public
cd bustub-public
git push https://github.com/student/bustub-private.git master
cd ..
rm -rf bustub-public
git clone https://github.com/student/bustub-private.git
cd bustub-private
git remote add public https://github.com/cmu-db/bustub.git
git remote -v
```

The README also tells you to pull in changes from the public repository as the semester goes on with git pull public master, and to disable GitHub Actions in the private repository's settings so you do not exhaust your Actions quota. That last step is a practical one: the upstream workflow file is copied along with everything else, and it will run on your account otherwise.

## The autograder is the only real feedback loop

For anyone outside CMU, the interesting part of the workflow is the autograder. The README states that the autograder for each assignment is made available to non-CMU students on Gradescope after the due date for CMU students, and that in exchange you are asked not to publish your implementations. Before submitting, you run a signing script.

```bash
python3 gradescope_sign.py
```

That script signs an agreement, and the README points to the course FAQ for how to use the autograder. This is the mechanism that separates BusTub from a repository of exercises you grade yourself. You get a real verdict on your implementation.

The trade-off is that the feedback is gated. Availability depends on the CMU due date having passed, and access depends on keeping your work private. There is also a file in the repository root named GRADESCOPE.md.template, which suggests the submission documentation is meant to be filled in per assignment. The README does not document what happens if you break the agreement beyond the ban it states, and it does not describe the autograder's internal scoring.

## Platform drift and the WSL exclusion

The most concrete limitation in the README is environmental. Ubuntu 24.04 is the recommended and graded platform. macOS is described as development only, and the README notes that differences between macOS and Linux, mutex behavior among them, might cause test cases to produce different results on different platforms. It recommends a Linux VM for running test cases and reproducing errors whenever possible.

That is a real failure mode, not a disclaimer. A concurrency bug that reproduces on Linux may not reproduce on macOS, so a student who develops on a Mac and submits to an Ubuntu grader can pass locally and fail remotely. The README's own suggestion, a Linux VM for test runs, is the mitigation.

The WSL exclusion is the sharper edge. WSL is a common way to get Linux tooling on a Windows machine, and the README states outright that it is not supported, with the further instruction not to open issues or come to office hours to debug unsupported environments. If Windows is your only machine, the documented route is a VM. That is a setup cost the README does not try to hide.

## BusTub against a production embedded database

The natural comparison is an embedded C++ database such as SQLite. Both are relational, both are written in C or C++, and both can be built from source. The difference is what each one gives you.

SQLite is a finished engine. You link it, you get correct SQL, and you never see the buffer pool. BusTub is the opposite: the value is in the unimplemented parts. The README ties the working shell to finishing the course projects, which means the interesting code is the code you write. Choosing BusTub for an application is choosing an engine whose completeness depends on your own progress.

There is a second difference in feedback. SQLite answers correctness questions through its own test suite and documentation. BusTub answers them through the course autograder on Gradescope, subject to the availability rules above. If you are not enrolled and not willing to work within those rules, you lose the strongest signal the project offers.

The README also states that BusTub supports basic SQL, which is a narrower claim than a general-purpose database makes. If your interest is SQL surface area, neither the README nor the repository layout suggests BusTub competes there.

## Maintenance, licence and what a semester costs

The repository is not archived, and the last push was on 2026-09-22. Releases are tagged by course term: v20251119-2025fall for Fall 2025, v20250414-2025spring for Spring 2025, and v20241207-2024fall for Fall 2024. That naming tells you how the project is maintained. It tracks the course calendar, so change arrives in term-sized batches rather than as a steady stream of fixes.

For a student, the upgrade cost is real. The README's cloning procedure exists precisely so you can merge upstream changes into your private repository with git pull public master while you work. That is convenient when the changes touch files you have not modified, and painful when they touch the component you are implementing. The README's advice to work on separate branches is aimed at this, and it warns that failing to do so means you might lose work with nobody able to help.

BusTub is MIT licensed, and the LICENSE file sits at the repository root. The licence is permissive, but it is not the constraint that matters here. The academic integrity terms in the README are separate from the licence and carry their own consequences for publishing solutions. Read both before you push anything to a public remote. Nothing here is legal advice; the README's warnings are the operative text.

## Conclusion

Adopt BusTub if you are working through 15-445/645, or if you want a C++ codebase where a storage engine, buffer pool, query executor and shell are all present and hackable. Do not adopt it as a database for an application: the README states it was developed for educational purposes and should not be used in production environments. Before you invest time, verify three things. First, that your platform is Ubuntu 24.04 or macOS, since the README says other environments, including WSL, are unsupported. Second, that the shell actually answers after your build, because the README ties a working shell to finishing all the course projects. Third, that you have followed the repository's own cloning procedure into a private repository, because the academic integrity warnings apply to public forks of solutions.

## FAQ

### What is BusTub?

BusTub is a relational database management system built at Carnegie Mellon University for the Introduction to Database Systems course, 15-445/645. The README states it supports basic SQL and comes with an interactive shell, and that it was developed for educational purposes and should not be used in production environments.

### How do I build and run BusTub?

On Ubuntu 24.04 or macOS, run the package script in build_support/, then create a build directory, run cmake .. and make. The README states that you can get the interactive shell running after finishing all the course projects, so a fresh clone will not answer SQL queries.

### Does BusTub support Windows or WSL?

No. The README recommends Ubuntu 24.04 or macOS, states that no other environments are supported, and explicitly says WSL is not supported. It also says not to open issues or come to office hours to debug unsupported environments, and suggests a Linux VM for running test cases.

## Sources

- [cmu-db/bustub on GitHub](https://github.com/cmu-db/bustub)
- [License: MIT](https://github.com/cmu-db/bustub/blob/master/LICENSE)
- [Project website](https://15445.courses.cs.cmu.edu)
- [README](https://github.com/cmu-db/bustub/blob/master/README.md)
- [Releases](https://github.com/cmu-db/bustub/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cmu-db-bustub