Small code can expose the machine
ExplainDB is teaching material from Saarland University's database systems course. The repository combines Jupyter notebooks with a Python package that implements storage models, indexes, versioned stores, query operators, sorting, and join-order planning.[1]
The project says the database is written for reading, not speed. That choice matters. Production systems compress their history into optimized code, compatibility layers, and operational limits. A teaching system can keep the parts far enough apart for a reader to follow one decision.
The useful unit is not a source file. It is a path through a decision.
Interfaces give the reader a seam
The DBMS interface defines how the database wraps an indexed transaction store and adds query processing. The implementation then shows prepared-query IDs, parameter binding, optimizer calls, and execution as a short sequence.[2]
That split gives a reader two different facts. The interface names the contract. The implementation shows one route through it. Neither replaces the notebook or the tests. A type signature can hide the algorithm. A working implementation can hide why the algorithm was chosen.
The notebook has to meet the source
The tutorial orders the material by storage, indexing, query processing, query optimization, and multidimensional indexing. Each topic points to both a notebook and the code that implements it. The notebooks include B+ trees, bitmap indexes, query pipelines, code generation, external merge sort, and plan enumeration.[3]
This is the part worth stealing for agent-written systems. If a generated change adds a cache, retry loop, planner rule, or permission gate, keep one tiny example that lets a maintainer watch the rule operate. Link that example to the interface and the exact implementation.
A passing suite proves a narrower thing
The repository documents one unit-test command. On the pinned commit, that command ran 103 tests and passed. This proves that the checked-out test suite passed in this environment. It does not prove production readiness, complete database semantics, benchmark performance, or lesson quality.
The GitHub repository has no published release at the time of this inspection. Use the commit hash if you want to repeat the result. The public Binder route is a temporary teaching environment. The project warns users not to upload private data or enter passwords there.[1]
Build a maintenance reading route
- Start at the public contract. Name the inputs, outputs, errors, and state.
- Follow one implementation path. Mark each dependency and state change.
- Run a small example that makes the mechanism visible.
- Read the tests that can reject your explanation.
- Write down the gap between the teaching example and production behavior.
Do this before asking an agent to extend the subsystem. The reading route becomes the review route after the patch.