MiniOB: a small C++ database for learning how a database engine works

What MiniOB is, and the warning the README opens with

The README opens with a statement in bold: the project is for learning purposes only, does not promise code security or stability, and should not be used directly in a production environment. That sentence sets the frame for everything else. MiniOB is a compact database written in C++, developed by the OceanBase team on top of a database course prototype from Huazhong University of Science and Technology, with several universities involved. The stated audience is students with no prior background, database practitioners, hobbyists, and anyone curious about foundational technology.

The design follows from that audience. The README says MiniOB simplifies many modules, and names concurrency, security features, and complex transaction management as things it does not consider, so that the principles of database implementation are easier to study. The goal is that a learner comes away knowing how the kernel modules function and cooperate, and picks up engineering skills such as memory management, network communication, and disk I/O handling.

That is a different product category from a storage engine you would pick for an application. The value is the code itself: a full path from a client request through parsing, resolution, planning, execution, and storage, small enough to hold in your head.

The module layout you will be reading

The README publishes an architecture diagram and a list of the components it contains. The network service handles interaction with clients, sending and receiving requests and responses. The parser turns SQL text into a syntax tree. The resolver converts that tree into internal database data structures. The optimizer adjusts or rewrites the syntax tree according to rules and statistics, and the README marks it as partially implemented. The executor walks the tree, executes it, and produces results. The storage engine stores and retrieves data.

Below that sit the pieces most courses only describe in the abstract. The record manager handles where records live inside a table's data file. The B+ tree is the index storage structure. Metadata management tracks the current databases, tables, fields, and index metadata. Session management handles user connections and per-connection parameters. Transaction management is listed under MVCC, and the README notes that only the MVCC mode is implemented, which is why the diagram shows it that way. Redo log management records database operation logs. A client program acts as a test tool, taking user requests and issuing them to the server.

Because the list is explicit about what is only partially implemented, it doubles as a map of where the interesting work is. If you want to understand query optimization, the README is telling you the optimizer is not a finished reference implementation.

Building MiniOB and running your first SQL statement

The README does not inline build commands. It points to a documentation site, and the entry for building the source is the how_to_build page under oceanbase.github.io/miniob. Treat that page as the authority for toolchain versions and flags rather than copying commands from a blog post. The repository does carry a build.sh at the top level and a deps directory, which is where the build documentation's expectations live.

The documented path from a fresh checkout is to follow the build page, then the how_to_run page. The repository also ships a .gitpod.yml and a .devcontainer directory, and the README lists a GitPod development page, so there is a hosted route that avoids assembling the toolchain yourself. For people who would rather not prepare a local environment at all, the README recommends the open-source classroom online programming environment, documented under docs/docs/dev-env/cloudlab_setup.md, which it says already provides an environment ready for MiniOB work.

Once a server is running, the client is the tool you talk to it with. The README describes the client as a test tool that receives user requests and sends them to the server, so the shape of a session is the familiar one: start the server, start the client, type SQL. The exact invocation belongs to the how_to_run page, which the README links rather than reproduces.

If you are working toward the competition, the README points at a separate submission path: the training camp usage instructions at oceanbase.github.io/miniob/dev-env/how_to_submit_for_testing, which is where code goes to be tested before submission.

Where MiniOB stops being the right tool

The README's own disclaimer is the first limitation, and it is not boilerplate. A database that does not consider concurrency, security features, or complex transaction management cannot back an application that has more than one writer or stores anything worth protecting. The MVCC-only transaction implementation and the partially implemented optimizer mean that even the query behaviour you observe may not match what a mature engine would do with the same SQL.

The second limitation is documentation drift, and the project says so itself. In the section about the video tutorial series, the README notes that because MiniOB is a continuously evolving product, some content in the videos conflicts with the latest code, and advises viewers to follow the reasoning in the explanation rather than the literal code. That is an honest warning, but it means a learner following older material will hit mismatches between what a video shows and what the tree contains.

The third is scope. MiniOB is not a SQLite replacement, not an embedded analytics engine, and not a way to add a query layer to a C++ application. Nothing in the README positions it as any of those. If your goal is to ship a feature, the time you spend inside MiniOB is time not spent on the feature. If your goal is to understand what happens between a client sending a statement and a B+ tree page being read, the small codebase is the point.

MiniOB against a production embedded database

The natural comparison is with SQLite, because both are small C databases you can read. The difference is intent. SQLite is engineered for deployment: it is embedded in applications, it has a documented file format and stability guarantees, and its test suite exists to protect users. MiniOB is engineered for study: the README explicitly simplifies modules and drops concurrency and security so that the implementation principles stay visible.

That shows up in what each project asks of you. With SQLite you read the documentation and call an API. With MiniOB you read the source and change it, because the repository is organized around exercises: the README says a series of problems of increasing difficulty were designed to take students from zero background into the database kernel, and the topics list on the repository includes classroom, education, and training. The competition is the clearest expression of that, with the preliminary round running on MiniOB and a training camp for submitting code to be tested.

A second comparison is with the full OceanBase database, from the same team. OceanBase is the production system; MiniOB is the teaching artifact built alongside it. If you want to understand the architecture of the real thing at a smaller scale, that lineage is the reason MiniOB exists.

Maintenance, releases, and the MulanPSL-2.0 licence

The repository is not archived, and its last push was on 2026-06-25. The most recent release listed is tagged oceanbase-competition-2022 and is dated 2023-04-20, so the release channel is not where activity shows up. If you are pinning to a version, that competition tag is the only named release in the record, and it is old enough that the main branch has moved well past it.

For a learner this matters less than it would for a dependency. You are reading a tree, not tracking a version for a build pipeline. But it does mean that tutorial content, including the video series the README links, can describe code that no longer matches, which the README acknowledges.

The licence is MulanPSL-2.0, the Mulan Permissive Software License, version 2. The README states that you may freely copy and use the source code, and that when you modify or distribute it you must comply with the same licence. It also asks that you follow the licence when distributing. That is a permissive licence in the same family as Apache-2.0 and MIT, but the text is its own document and it is not identical to either. If you plan to redistribute a modified MiniOB, read the licence text itself at the link the README gives rather than assuming the terms of a more familiar licence apply. This is a description of what the README says, not legal advice.

Upgrade cost is low in the ordinary sense because there is no dependency to upgrade. The cost is in re-syncing your own changes when you pull the main branch, which is the normal cost of working on a fork of a teaching repository.

Editorial conclusion

Adopt MiniOB if you want to read and modify a complete database kernel in C++, or if you are preparing for the OceanBase competition whose preliminary round runs on it. Do not adopt it as a storage layer for an application: the README states the project is for learning purposes and does not promise code safety or reliability, and it says not to use it directly in production. Before you start, verify that the build toolchain the build documentation lists matches what your machine has, and open the architecture page so you know which module you are editing.

Frequently asked questions

Official sources

1. License: MulanPSL-2.0
2. oceanbase/miniob on GitHub
3. Project website
4. README
5. Releases