BlueBase

This repository is used to maintain the official documentation and the complete test suite. The actual assignments are completed through Qlass.

BlueBase is a Python-based DBMS designed for educational purposes. It was developed with reference to Stanford's RedBase.

By implementing each component of BlueBase, the goal is to build a DBMS from scratch.

Created by: @theeluwin

For the sake of future students and their enjoyment of learning, please refrain from sharing solution code.

For more information, see the official documentation.

Environment Setup

uv is used to manage the Python environment.

uv sync

To use Docker:

docker build -t bluebase .

Testing

Tests are run using PyTest.

The default test configuration (pytest.ini) also measures source code coverage. After running the tests, open the generated htmlcov/index.html file to view the detailed coverage report.

Running All Tests

uv run pytest

Testing Individual Components

For example, to test the PF component:

uv run pytest bluebase/pf

To test the manager of the PF component:

uv run pytest bluebase/pf/tests/test_manager.py

Experiments

Experiments require additional dependencies:

uv sync --group exps

Then run an experiment as a module:

uv run -m exps.pf.replacer

Alternatively, Docker includes all additional dependencies. For example, the exps/ix/basic.py experiment requires graphviz.

docker build -t bluebase .
docker run --rm -v ./debug:/workdir/debug bluebase -m exps.ix.basic

Building the Documentation

Building the documentation requires additional dependencies:

uv sync --group docs

Then build the documentation using Sphinx:

make docs

After the build completes, open docs.build/index.html to view the generated documentation.

Usage

Running

uv run bluebase test.db

Installation

pip install -e .

Or, depending on the environment:

python -m pip install -e .

CLI Usage

bluebase test.db

API Usage

from pathlib import Path
from bluebase import BlueBase

bb = BlueBase(Path("test.db"))

result = bb.execute("SELECT * FROM table_cat;")
for row in result:
    print(row)