Teaching materials for a database systems course: a collection of Jupyter notebooks and a didactic
DBMS implemented in Python (the system/ package). The lecture that uses this code is available on
YouTube: Database Systems 2024/25
(Prof. Dr. Jens Dittrich, Big Data Analytics Group, Saarland University).
Click the badge to open the notebooks in JupyterLab on mybinder.org, with no installation needed. The start can take a few minutes the first time, after a change to the repository, or after a longer pause, while Binder builds the environment. Sessions are temporary: they end after a period of inactivity, or after a few hours at most, and all your changes are lost. Download any notebook you want to keep (File → Download). mybinder.org is a free public service: do not upload private or confidential data, and do not enter passwords in a Binder session.
The notebooks are grouped by the chapters of the tutorial, which explains each topic and points to the code that implements it. The launch badge opens a notebook directly on Binder.
A small DBMS written for reading, not for speed. Interfaces in
system/interfaces/ carry the contracts; the other folders implement them:
- Storage (
storage/): the storage hierarchy (DRAM, caches, SSD, disk) and RAID block assignment (RAID 0/1/4/5) with a reliability and performance cost model. - Indexes (
indexes/): B⁺-tree, bitmap indexes (equality- and range-encoded), Bloom filters, radix tries and the "Christmas tree" (a radix trie with node buffers). - Bit sequences (
bit_sequences.py): plain and WAH-compressed bit sequences used by the bitmap indexes. - Transactional stores (
stores/): a versioned key-value store and MVCC (multi-version concurrency control) with journaling, also with an index. - Query processing (
query_processing/): operators such as scan, filter, hash join, semi-join and count, plus WHERE-clause predicates. - Sorting and queues (
sorting.py,queues/): external merge sort with in-memory and disk-backed queues. - Query optimization (
query_optimization/): join graphs (chain, star, cycle, clique), cardinality estimation, the C_out cost function and plan tables for dynamic-programming join ordering.
DBMS.py ties these parts together: it manages stores, prepared queries and query
optimization. Unit tests for all of this live in system/tests/.
This repository uses uv to manage its Python version and dependencies. uv installs the correct Python interpreter for you, so no separate Python installation is required.
- macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh - Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
See the uv installation docs for alternatives (Homebrew, pipx, etc.).
git clone https://github.com/explaindb/explaindb.git
cd explaindbThis creates a virtual environment in .venv/, installs Python 3.12 if needed, and installs all
required packages from uv.lock.
This opens a browser window listing the files in the current directory. The notebooks live in the
notebooks/ directory; open them from there. Any command can be run inside the project environment by
prefixing it with uv run — no manual environment activation needed.
Alternatively, you may run the notebooks in an IDE like
PyCharm; point its interpreter at the .venv/ created by uv.
uv run python -m unittest discover system/tests/The API documentation, generated from the source docstrings, is available online at https://bigdata.uni-saarland.de/software/explaindb/index.html. How to build it locally is described in CONTRIBUTING.md.
See CONTRIBUTING.md for the code formatting, the docstring conventions, and how dependencies, notebooks and the API documentation are maintained.
ExplainDB is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Copyright (C) 2026 Prof. Dr. Jens Dittrich, Saarland University.
People, in order of number of commits:
With help from Claude, an AI coding assistant by Anthropic, credited as co-author on commits.