Open-source project
oceanbase/miniob avatar
oceanbase/miniob

MiniOB: a C++ database that drops concurrency, security and complex transactions

MiniOB is a compact database that assists developers in understanding the fundamental workings of a database.

4,435 stars1,628 forksC++MulanPSL-2.0

At a glance

What is it?
MiniOB is the OceanBase team's teaching database for students who have never read a query planner. It keeps the B+ tree, the redo log and the socket server and removes the parts a beginner cannot debug, which makes it a good systems reading exercise and a bad production candidate.
Who is it for?
Adopt MiniOB if you are a student working through the database kernel exercises or an instructor who needs a small codebase to walk through a query from SQL text to B+ tree page. Do not adopt it if you need multi user concurrency, access control or durability guarantees, because the project says so in its own first line.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 143 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • oceanbase/miniob4,435 ★ · +12
Star history
Repository2026-09-232026-11-14
oceanbase/miniob4.4k4.4k

12 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A database with the hard parts removed on purpose

MiniOB is a small relational database written in C++ by the OceanBase team, rebuilt from a course prototype at Huazhong University of Science and Technology. Its stated audience is students with no prior database background, plus working developers and hobbyists who want to see how a query travels through a system.

The first thing to understand is what the project takes out. The README says MiniOB ignores concurrency, security features and complex transaction management so that the principles of database implementation stay visible. It also says outright that the code is not promised to be safe or stable and must not be placed in production. That disclaimer is the design brief: this is a codebase you read and modify, not one you deploy.

The payoff is size. A working path from a client socket to SQL text, a syntax tree, a resolved plan, executed operations and B+ tree pages fits in a repository that a learner can hold in their head, and the exercises attached to it run from easy to hard.

The request path from NET Service down to the B+ tree

The module list in the README describes a conventional request path, and it is worth walking it once because it names the files you will end up editing.

NET Service receives client requests and replies. The Parser turns user SQL into a syntax tree. The Resolver converts that tree into the database's internal structures, and the Optimizer adjusts or rewrites the tree using rules and statistics, which the README marks as partially implemented. The Executor runs the plan and produces results.

Below that sits the storage half: a storage engine responsible for storing and retrieving data, a redo log that records database operations, and a record manager that owns where records live inside a table's data file. B+ Tree is the table index structure. Meta Data records databases, tables, columns and indexes, session management holds per connection state, and a Client binary acts as the test client.

Everything above the line is classical and nothing about it is unusual. The unusual part is that each box is small enough to hold in one sitting.

MVCC is the only transaction mode, so the docs show it directly

Here is a contradiction worth noticing early. The README describes MiniOB as ignoring complex transaction management, and yet transaction management is one of the thirteen modules it lists. The reconciliation is in the same sentence: only the MVCC mode is implemented, so the documentation presents transactions as MVCC directly.

What this means for a reader is concrete. The module is described as managing commit, rollback and isolation levels, but MVCC is the only mode implemented.

The same pattern applies to the Optimizer. Marked as partially implemented, it is a place to add work rather than a finished cost based planner. Treat both modules as the natural first contributions, which is consistent with the help wanted issues the project points at for new features.

Getting a build: the docs site carries the commands, not the README

The README contains no build command, no package name and no run command. If you want to compile MiniOB, it sends you to the documentation site published on GitHub Pages at oceanbase.github.io/miniob. There you will find the framework introduction, a page on how to compile the source, a page on how to run MiniOB, a Gitpod based workflow and generated Doxygen output for the code itself.

The repository layout tells you what backs those pages. There is a build.sh at the top level and a CMakeLists.txt next to it, plus deps/, src/, unittest/, test/, benchmark/, tools/, docker/ and a .devcontainer directory. A .gitpod.yml is present, and .vscode and .clang-format point at an IDE workflow and a fixed formatting style.

For beginners there is also an online programming environment described in the docs, offered as an alternative to assembling a local toolchain. The README is blunt about why: setting up a development environment is slow and tedious, especially for someone starting out. Use the cloud environment for the first exercise, and the local build once you need to read the code with a debugger.

The graded exercises come from the OceanBase competition training camp

MiniOB is the training platform for the preliminary round of the OceanBase database competition, a nationwide contest for university students, and the exercises on it are set from easy to hard. Daily practice runs through the MiniOB training camp, where you submit code for testing, with a submission guide and a competition FAQ linked from the README.

The repository is not archived, and the last push was on 2026-06-25. The README is blunt about what that means for a learner: because MiniOB evolves continuously, some material in the video tutorial conflicts with the current code, and the project advises following the reasoning in the lessons rather than copying them.

That warning is worth taking literally. If you plan to work from the video series, note the revision you start from, because a later pull can silently invalidate a patch written against the tutorial.

Where MiniOB stops and a working engine begins

The honest limit is the list MiniOB itself names. No concurrency means the project sets concurrent operation aside, so it is not the place to study lock managers, deadlock detection or contention. No security means there is nothing to review about grants and authentication. MVCC is the only transaction mode implemented. A partially implemented optimizer means cost based plan selection is unfinished work.

A real alternative for reading a production planner is the OceanBase source tree itself, the database built by the same team, which ships a distributed engine rather than a course skeleton. The difference in approach is scale and intent: MiniOB deliberately omits the modules that make an engine hard, so a single module can be read in an afternoon, while OceanBase spreads the same responsibilities across a distributed storage and compute layer.

Another approach is reading a textbook implementation alongside it. The project links a Database Management System Implementation lecture set from the same university. MiniOB plus that material gives you code and theory; MiniOB alone gives you code.

Where the reference answers live: Doxygen output and two course sets

Design notes sit next to the code rather than in a wiki. The README says the project already generates design documents and code comments into documentation, published through GitHub Pages, and it links a doxygen code index alongside the architecture page. Reading the generated class documentation for the record manager or the B+ tree is faster than grepping a C++ tree of this size.

For theory, the project points at two outside sources. One is a video series and lecture notes called the from zero to one database kernel practical tutorial, whose notes live in a separate kernel-quickstart repository. The other is the Database Management System Implementation lectures from Huazhong University of Science and Technology, the same course the original prototype came from.

Neither replaces reading src/.

Editorial conclusion

Adopt MiniOB if you are a student working through the database kernel exercises or an instructor who needs a small codebase to walk through a query from SQL text to B+ tree page. Do not adopt it if you need multi user concurrency, access control or durability guarantees, because the project says so in its own first line. Before you commit, read the build guide at the documentation site and compare the tutorial material against the current main, since the README warns that tutorial videos already conflict with the latest code.

Frequently asked questions

What is MiniOB in OceanBase?

MiniOB is a compact C++ database the OceanBase team rebuilt from a course prototype for students with no prior database background. It keeps the parser, resolver, executor, storage engine, redo log, record manager, B+ tree index, MVCC transactions and meta data, and drops concurrency, security and complex transaction management.

Is MiniOB safe to use in production?

No. The README states the project is for learning only, makes no promise that the code is safe or stable, and says it must not be used directly in a production environment.

How do I build and run MiniOB?

The README gives no build command of its own. It points to the documentation published on GitHub Pages, which has separate pages on compiling the source and on running MiniOB, plus a Gitpod workflow and an online programming environment. The repository itself carries a top level build.sh and CMakeLists.txt.

Which transaction isolation modes does MiniOB implement?

Only MVCC. The README says the current transaction management implements the MVCC mode alone, which is why the documentation presents transactions directly as MVCC.

Is MiniOB actively maintained?

The repository is not archived and its last push was on 2026-06-25. The README does warn that because the project evolves continuously, some tutorial video material conflicts with the current code.

What licence is MiniOB under?

MiniOB uses the Mulan permissive licence, version 2. The README says the source may be copied and used freely, and that modification or distribution must follow the terms of MulanPSL-2.0.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/oceanbase-miniob.svg)](https://hysenlabs.com/projects/oceanbase-miniob)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/oceanbase-miniob.svg)](https://hysenlabs.com/projects/oceanbase-miniob)

Was this useful?