Apache Kvrocks: a Redis-compatible database that keeps its data on disk

The memory bill that Kvrocks is trying to cut

Redis keeps the working set in RAM, and RAM is the most expensive tier of storage you can buy. The README states the intent plainly: Kvrocks "intends to decrease the cost of memory and increase the capacity while compared to Redis." That single sentence defines the audience. If your dataset fits comfortably in memory and your latency budget is measured in tens of microseconds, you are not the target user, and nothing in the repository suggests otherwise.

The target user is the team that has a Redis-shaped workload (counters, session state, feature flags, sorted-set leaderboards, hash-heavy objects) whose dataset has grown past the point where the memory bill is defensible, and who does not want to rewrite the application layer. Kvrocks keeps the protocol and moves the bytes. The design of the replication and storage layers is credited in the README to rocksplicator and blackwidow, both of which are disk-backed systems, so the lineage is consistent with the stated goal.

RocksDB underneath, Redis on the wire

The architecture has two halves that are worth separating. On the wire, Kvrocks is a Redis server: the README says users "can access Apache Kvrocks via any Redis client," and the connect example uses redis-cli against port 6666. On disk, RocksDB is the storage engine, and Redis data structures are encoded into it. The project publishes a design document titled "Design Complex Structure on RocksDB," which is where the encoding details live; the README itself does not describe them, so anyone who needs to reason about key layout or compaction behaviour should read that page rather than the repository front page.

Replication is asynchronous and binlog-based, which the README compares to MySQL. That comparison matters for failure semantics. An asynchronous replica is behind the master by however much binlog has not yet shipped, so a failover can lose the tail. High availability is handled by Redis sentinel rather than by a consensus protocol inside Kvrocks, which means the failover decision is made by an external process that watches the master. The cluster mode is described as "proxyless centralized": clients connect through Redis cluster SDKs, but membership and slot management are centralized rather than gossip-based, and the controller that performs that central management is a separate project, kvrocks-controller.

Building Kvrocks from source and running a first instance

The repository builds with a Python driver script, x.py, rather than by invoking CMake directly. The README lists prerequisites per distribution; on Ubuntu or Debian the package set is git, build-essential, cmake, libtool, python3 and libssl-dev. Clone, then build:

git clone https://github.com/apache/kvrocks.git
cd kvrocks
./x.py build

The build script accepts extra CMake flags. The README documents three: TLS support, Lua instead of LuaJIT, and a debug build type. They compose, so a TLS-enabled debug build is a single invocation.

./x.py build -DENABLE_OPENSSL=ON
./x.py build -DENABLE_LUAJIT=OFF
./x.py build -DCMAKE_BUILD_TYPE=Debug

The default build type is RelWithDebInfo with optimization around -O2, which is worth knowing before you assume a debug binary is what you got. Once the build finishes, the binary is at build/kvrocks and takes a configuration file:

./build/kvrocks -c kvrocks.conf

If you would rather not build at all, the README gives a Docker path with the port published on 6666 and the bind address overridden on the command line:

docker run -it -p 6666:6666 apache/kvrocks --bind 0.0.0.0

A nightly tag, apache/kvrocks:nightly, is also documented. The repository Dockerfile shows the image runs as a non-root user with uid 999, declares /var/lib/kvrocks as a volume, and installs redis-tools inside the image, so redis-cli is available for a smoke test from a container shell. Connecting from the host is the same as any Redis server:

redis-cli -p 6666
127.0.0.1:6666> get a
(nil)

The nil reply is the expected result on a fresh instance.

Namespaces replace SELECT, and the admin token is the gate

The most consequential deviation from Redis is the namespace model. Redis databases are numbered and any client that authenticates can reach them. Kvrocks gives each namespace its own token. The README states that requirepass is treated as the admin token, and that only the admin token may issue the namespace command plus administrative commands such as config, slaveof and bgsave.

That is a real operational difference, not a cosmetic one. Your provisioning tooling has to create namespaces and hand out per-namespace tokens, and your application clients authenticate with those tokens rather than with a shared password. The command set is small and the README shows all of it:

127.0.0.1:6666> namespace add ns1 my_token
OK
127.0.0.1:6666> namespace set ns1 new_token
OK
127.0.0.1:6666> namespace get *
1) "ns1"
2) "new_token"
3) "__namespace"
4) "foobared"
127.0.0.1:6666> namespace del ns1
OK

Notice that namespace get * also lists __namespace, which holds the admin token. Any code that enumerates namespaces and prints the result will print that token. Treat the output of that command as a secret. The README points to a dedicated Namespace page for the rest of the semantics; it does not cover token rotation policy, expiry, or what happens to data in a namespace after deletion, so those questions need the documentation site or the source.

Where Kvrocks is the wrong tool

The README publishes a Supported Commands page as a separate document, which is itself the warning. Kvrocks is protocol-compatible, not command-compatible. If your application calls a Redis command that is not on that list, you find out at runtime, and the README does not offer a compatibility shim or an emulation layer for missing commands. Audit your command usage before you plan a migration, not after.

Latency is the second boundary. RocksDB reads may come from block cache, from an SST file, or from a compaction in progress, and the tail of that distribution is not the tail of an in-memory store. Nothing in the README claims parity with Redis latency, and it explicitly frames the trade as cost and capacity against Redis. A workload with a hard p99 budget in the low hundreds of microseconds, on a dataset that fits in RAM anyway, gains nothing here and takes on compaction behaviour it did not have before.

The third boundary is the failover path. Sentinel-based HA with asynchronous binlog replication means the system is eventually consistent across a failover, and the cluster's central controller is a separate repository. If you need a single binary that manages its own membership, this is not that. The README also does not document rollback, downgrade, or on-disk format compatibility between releases, so a version upgrade path is something to establish from the release notes and the documentation site rather than from the repository front page.

Kvrocks against Redis and against RocksDB itself

The comparison people search for is kvrocks vs redis, and the honest difference is one sentence: same protocol, different storage tier. Redis holds the dataset in memory and is the reference implementation of that protocol. Kvrocks holds the dataset in RocksDB and implements enough of the protocol to let existing clients connect. Choosing between them is choosing between paying for RAM and paying for disk plus compaction. There is no configuration flag that turns one into the other, and the README does not present Kvrocks as a Redis replacement in the sense of identical semantics under failure.

The other comparison, kvrocks vs rocksdb, is a category error worth clearing up. RocksDB is an embedded storage library with no network protocol, no authentication, and no replication. Kvrocks is a server that uses RocksDB as its engine and adds the Redis wire protocol, namespaces with tokens, binlog replication, sentinel-based failover, and a cluster mode with a central controller. If you are embedding a key-value store inside a single process, RocksDB is the right layer and Kvrocks is overhead. If you need multiple clients over a network with access control, RocksDB alone gives you none of that. The migration tooling reflects the same split: the README points to RedisShake for moving data from Redis to Kvrocks, and lists a tool for the reverse direction as well.

Licence, tooling and the cost of staying current

Kvrocks is an Apache Software Foundation project under the Apache-2.0 licence, and the repository carries the standard ASF NOTICE and LICENSE files plus a licenses/ directory for bundled dependencies. Apache-2.0 includes an express patent grant and permits commercial use and modification; it also requires that you preserve notices. That is a summary of the licence text, not legal advice, and the licenses/ directory is where to check what the bundled components add.

The surrounding tooling is split across repositories, which is the practical maintenance cost. Cluster failover and scaling are handled by kvrocks-controller. Metrics export is handled by kvrocks_exporter, which is not under the apache organization. Migration in both directions uses RedisShake. Each of those is a separate project with its own release cadence, so a Kvrocks deployment is really a small constellation of components that you track independently. The project itself is not archived, and the last push to the unstable branch was on 2026-09-22, with v2.17.0 released on 2026-09-19. Upgrades mean rebuilding from source or pulling a new image tag, and the README does not describe a rolling upgrade procedure, so the release notes are the place to look for format changes between v2.15.0, v2.16.0 and v2.17.0.

Editorial conclusion

Adopt Kvrocks when your dataset has outgrown what you are willing to pay for in RAM and your application already talks to a Redis client, because the README states that any Redis client can connect and the project ships a Docker image plus a kvrocks-controller for cluster management. Do not adopt it as a drop-in for a workload that depends on Redis commands outside the supported list, or on a single-node in-memory latency profile, since the storage engine is RocksDB and the supported command set is published separately. Before committing, verify three things against your own workload: that every command you call appears in the supported commands page, that your client handles the namespace token model rather than plain SELECT, and that your deployment path (bare binary, Docker, or kvrocks-controller) matches what the project documents for your platform.

Frequently asked questions

Official sources

1. apache/kvrocks on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases