ToplingDB: a RocksDB fork built around pluggable components

A fork that treats its own parts as replaceable plugins

ToplingDB is developed and maintained by Topling Inc, and it is forked from RocksDB. The documentation is direct about the difference: it has much more key features than RocksDB, and the first of those is SidePlugin, which enables users to write a json or yaml to define DB configs.

The component model is described under the heading for ToplingDB Components. With SidePlugin mechanics, plugins and components can be physically separated from the core ToplingDB. They can be compiled to a separated dynamic lib and loaded at runtime. User code need not any changes, just change json/yaml files. And Topling's non-open-source enterprise plugins and components are delivered in this way.

That last point explains the architecture. The plugin mechanism is not only an extension point, it is the distribution channel for the company's own closed components. The same mechanism that lets you swap a TableFactory lets Topling ship an enhanced one.

The repository structure shows how the parts are split. Under the main tree there is a `sideplugin` directory containing `rockside`, which is a submodule and holds the SidePlugin core and framework, and then a series of directories that are auto cloned: `topling-zip`, `cspp-memtable`, `cspp-wbwi`, `topling-sst`, `topling-rocks`, `topling-zip_table_reader`, `toplingdb-fs` and `topling-dcompact`, the last of which contains the dcompact-worker binary application.

The table of repositories makes the public and private split explicit. The ToplingDB repository is public and is the top repository, forked from RocksDB with the fixes, refactories and enhancements. The `rockside` submodule is public and contains the SidePlugin framework and built-in SidePlugins, the embedded HTTP server and the Prometheus metrics. The `cspp-wbwi` repository, named for WriteBatchWithIndex, is public and the documentation claims it is 20x faster than the RocksDB SkipList based WBWI, with CSPP and carefully coding.

That is a substantial amount of machinery to maintain, and it is the price of the flexibility.

Building it, and the trial component that downloads itself

The quick start is short on requirements and long on consequences. ToplingDB requires C++17, gcc 8.3 or newer is recommended, and clang also works.

sudo yum -y install git libaio-devel gcc-c++ gflags-devel zlib-devel bzip2-devel libcurl-devel liburing-devel snappy-devel jemalloc-devel
#sudo apt-get update -y && sudo apt-get install -y libjemalloc-dev libaio-dev libgflags-dev zlib1g-dev libbz2-dev libcurl4-gnutls-dev liburing-dev libsnappy-dev libbz2-dev liblz4-dev libzstd-dev
git clone https://github.com/topling/toplingdb
cd toplingdb
make -j`nproc` db_bench DEBUG_LEVEL=0
sudo make install-dev-shared DEBUG_LEVEL=0 PREFIX=/some/path # installs shared library and headers; install-shared alone installs only the library

Note the last line's comment, which is a practical detail: `install-dev-shared` installs the shared library and the headers, while `install-shared` alone installs only the library.

Then there is the part worth reading twice. During compilation, a precompiled ToplingZipTable with a 90-day trial may be downloaded automatically. If you need to disable the ZipTable Builder trial, pass `WITH_TOPLING_ROCKS=0 WITH_CSPP_MEMTABLE=0` to make, and the Makefile requires CSPP to be disabled when Topling Rocks is disabled, or you contact the company. CSPPMemTable is also distributed this way.

So a build may fetch binaries from the vendor, and turning that off requires two specific flags plus a constraint that the flags interact. For a build in a reproducible or air-gapped environment that is the first thing to resolve, and it is the kind of detail that a package manager would normally hide from you and this build system does not.

For running, the documentation says you can run the bundled `db_bench.sh`, which needs port 2011, and then use ToplingDB in C++, in Java through the SidePlugin Java binding bundled in the repository, or in Rust through a separate `rust-toplingdb` repository. There is also a downloadable enterprise tarball for those who would rather not build.

The memtable-as-log-index idea and what it changes

The feature list contains one design change that is worth understanding on its own, because it changes what the write path does.

ToplingDB has a memtable as wal log index, and the summary is given twice, as a feature and again in the list: it omits the memtable flush to L0, reduces write amplification, and further improves for a large memtable.

In stock RocksDB, the memtable holds recent writes and is flushed to L0 when it fills, and the write-ahead log is a separate record of the same writes. If the memtable is kept in the log instead, the flush step disappears, which removes one write amplification and one I/O path from every write that eventually leaves the memtable.

The other named improvements follow a pattern. Topling zero copy for point search, meaning Get and MultiGet, and for Iterator. MultiGet with concurrent IO by fiber or coroutine plus io_uring, which the documentation says is much faster than RocksDB's async MultiGet. Topling de-virtualization, which de-virtualizes hotspot virtual functions and adds key prefix caches. Topling transaction lock management, which the documentation claims is 5x faster than RocksDB. And many improvements and refactories on RocksDB aimed at performance and extendibility, plus built-in Prometheus metrics support based on the embedded HTTP server.

The embedded HTTP server is worth singling out, because it changes the operational profile. It enables users to view almost all DB info on the web, and it enables online change of db and cf options and all db meta objects, such as MemTabFactory, TableFactory and WriteBufferManager, without restarting the running process. In effect you get a live inspector and a live configuration surface for a running database.

That is a double-edged capability. It is exactly what you want when diagnosing a production issue at three in the morning, and it is also a live control surface for a database, which raises the question of who can reach it and what they can change. The documentation does not describe the authentication or exposure model, so that is worth asking about directly.

There is a related note on crash safety. The documentation points to a crash-safe recovery guide for the recovery mechanism, configuration and limitations, and to a page on the isomorphism between wait-free reads and crash safety for the underlying data-structure principles. `DB::Open` after an abnormal exit is timed in a separate benchmark document. The existence of a dedicated benchmark for the recovery path is a good sign, since the interesting number in a database is not the steady-state throughput but the time to reopen after a crash.

Version naming and the branch structure that comes with it

The version and branch conventions are unusual, and they are documented separately, which is itself a signal.

The default branch of the repository is `memtable_as_log_index`, which is a feature name rather than a release name, and that is a direct consequence of the plugin architecture. When components are separate and loadable, the interesting work is often in a component rather than in the core, so a branch named after a component can be where the work happens.

The single listed release is `topling-8.10.2-frocks-1.0`, whose description is topling flink frocksdbjni with distributed compact, and it was published on 2026-03-31. The version string carries three pieces of information at once: the RocksDB base version, a flag for the Topling Rocks component, and the distributed compaction feature.

That naming convention is the cost of the plugin model made visible. A single artefact version has to pin the base database, the set of components in use and the features they enable, and any of those can move independently.

The repository also carries the RocksDB project's own machinery, which tells you how much of the fork is upstream and how much is new. There is a `db/` directory, `cache/`, `common.mk`, `db_bench.sh`, `db_stress_tool/`, `tools/`, `java/`, `env/`, `file/`, `logging/`, `memory/`, `memtable/`, `monitoring/` and `options/`, plus `TARGETS`, `DUMP_FORMAT.md`, `HISTORY.md`, `INSTALL.md`, `PLUGINS.md`, `USERS.md` and `WINDOWS_PORT.md`.

The presence of `USERS.md` is worth a note. A fork of a database that keeps a list of who is using it is a fork that expects to be adopted, and the `PLUGINS.md` file next to it suggests the plugin set is treated as a documented catalogue rather than an implementation detail.

The licence files show the same layering. The root holds `COPYING`, `LICENSE.Apache` and `LICENSE.leveldb`, so the Apache-2.0 terms and the inherited LevelDB BSD-style terms coexist, and the top-level repository is reported as GPL-2.0. The `AUTHORS` file is present, which is the LevelDB convention.

Editorial conclusion

ToplingDB fits a team that has to tune RocksDB internals per workload, that wants to change database options and component factories while the process is running, and that is prepared to build and hold the plugin set itself rather than depend on upstream defaults. It does not fit a team that wants to use RocksDB unchanged, and it does not fit a project without the engineering capacity to own a fork with a moving component set. Verify first that the component set you need is available for the release you are considering, that the SidePlugin configuration format your deployment expects matches the one in the version you build, and that the trial components the build may download are acceptable in your environment, since the documentation says a precompiled ToplingZipTable may be fetched automatically during compilation.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. topling/toplingdb on GitHub