Open-source project
apache/kvrocks avatar
apache/kvrocks

Kvrocks: Redis protocol over RocksDB, with a token on every namespace

Apache Kvrocks is a distributed key value NoSQL database that uses RocksDB as storage engine and is compatible with Redis protocol.

4,503 stars687 forksC++Apache-2.0

At a glance

What is it?
Kvrocks answers the Redis protocol from RocksDB, so ordinary Redis clients talk to a disk based engine, and each namespace carries its own token instead of sharing one requirepass password across every database.
Who is it for?
Kvrocks fits teams that already run Redis clients and want key value storage to stop competing with the process for memory, provided they accept a disk based write path in exchange. It does not fit anyone who needs synchronous replication semantics or who wants one binary to run, because failover and cluster operations sit in `kvrocks-controller` and metrics sit in `kvrocks_exporter`, two separate repositories.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
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 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • apache/kvrocks4,503 ★ · +64
Star history
Repository2026-09-232026-11-15
apache/kvrocks4.4k4.5k

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

Editorial analysis

RocksDB under the Redis wire protocol

Kvrocks is a distributed key value database written in C++, and it keeps every key in RocksDB while answering the Redis wire protocol. That pairing is the whole design, since nothing in the connection tells a client that a disk based engine sits underneath. Every example here uses port 6666, and a client attaches with `redis-cli -p 6666`, gets a normal prompt back, and sees `(nil)` for a key that was never written. Memory stops being the ceiling on dataset size, because durability belongs to RocksDB rather than to the resident set of the server process. Replication and storage layout were inspired by rocksplicator and blackwidow, and both ancestors are named in the repository instead of being left as vague credit. Supported platforms are Linux and macOS, on x86_64, ARM and RISC-V architectures.

One token per namespace, requirepass held back for admins

Kvrocks keeps the idea of Redis SELECT and attaches a token to each namespace. `requirepass` acts as the admin token, and only the admin token may run the namespace command or reach commands such as `config`, `slaveof` and `bgsave`. Adding, rotating, listing and removing a namespace all go through one command family, driven from the same prompt on port 6666.

sh
# add token
127.0.0.1:6666> namespace add ns1 my_token
OK

# update token
127.0.0.1:6666> namespace set ns1 new_token
OK

# list namespace
127.0.0.1:6666> namespace get *
1) "ns1"
2) "new_token"
3) "__namespace"
4) "foobared"

# delete namespace
127.0.0.1:6666> namespace del ns1
OK

A wildcard listing returns names and their tokens in one reply, and the captured output pairs `__namespace` with `foobared`. That token column holds a credential rather than decoration, so any caller holding the admin token collects every namespace token in a single response. The README does not document a rotation workflow beyond `namespace set`, and it does not say what happens to the keys held inside a namespace once a delete succeeds.

The default branch is named unstable

The default branch of the repository is `unstable`, so a plain clone lands on a branch whose name promises instability. Nothing in the README explains what promotion looks like or how a patch reaches an already running node, which means a repeatable build has to pin a version tag or a commit instead of trusting the branch name. Operators reading the top of the tree will also find `THREAT_MODEL.md` and `SECURITY.md`, which give the project a written threat model and a reporting channel with no further description in the README. Alongside them sit `.clang-format`, `.clang-tidy`, `AGENTS.md`, `kvrocks.conf`, `CMakeLists.txt` and a `.devcontainer/` directory, so formatting rules and editor defaults live inside the tree. No upgrade notes sit at that level, where a team moving an existing deployment forward has to diff configuration by hand.

x.py hides the TLS, LuaJIT and debug switches

Every build runs through one script, `x.py`, and its flags pass straight through to CMake. TLS is off by default and comes from `-DENABLE_OPENSSL=ON`, with the OpenSSL development packages already named in the prerequisites. LuaJIT is the default scripting engine, and `-DENABLE_LUAJIT=OFF` swaps it for plain lua. Debug builds take `-DCMAKE_BUILD_TYPE=Debug`, and the comment beside that line says the default type is RelWithDebInfo at -O2, dropping to -O0 in debug mode. Tests hang off the same script: `./x.py build --unittest` compiles them, `./x.py test cpp` runs the C++ suite, and `./x.py test go` runs Golang unit and integration cases. A Go integration layer inside a project whose primary language is C++ is a detail worth planning around, because the two suites carry different runtimes and different build flags.

The CentOS block names cmake.org and then fetches GitHub

On CentOS and RedHat the prerequisites need a compiler collection from a software collection repository, and the block enables that collection before pulling in `devtoolset-11` with autoconf, automake, libtool, python3 and openssl-devel. The cmake line is where a careful reader stops. A comment says to download and install cmake via `https://cmake.org/download`, and the next two lines actually fetch an installer for version 3.26.4 from GitHub and run it into /usr, after which `source /opt/rh/devtoolset-11/enable` turns on gcc and make. The same block closes with an `# openSUSE / SUSE Linux Enterpr` comment and nothing underneath it, so openSUSE and SUSE Linux Enterprise users get no package line to copy. By comparison the Ubuntu and Debian path is one apt command: `sudo apt install -y git build-essential cmake libtool python3 libssl-dev`.

Docker runs as uid 999 with redis-tools in the image

The container build starts from `debian:trixie-slim`, adds clang to the usual toolchain, and compiles with flags the README never mentions: `--compiler=clang`, `-DENABLE_OPENSSL=ON`, `-DPORTABLE=1`, `-DCMAKE_BUILD_TYPE=Release`, `-DCMAKE_EXE_LINKER_FLAGS="-latomic"`, and `-j $(nproc)` for the job count. The runtime stage keeps openssl, ca-certificates, `redis-tools` and binutils, then creates a dedicated account with uid 999 and gid 999, hands it `/var/lib/kvrocks` and `/var/run/kvrocks`, and switches to `USER 999` with `VOLUME /var/lib/kvrocks` declared for data.

shell
$ docker run -it -p 127.0.0.1:6666:6666 apache/kvrocks --bind 0.0.0.0
# or get the nightly image:
$ docker run -it -p 127.0.0.1:6666:6666 apache/kvrocks:nightly

Two details matter for anyone running this in production. The image ships `redis-tools`, so the client example works with nothing else installed, and these examples publish port 6666 on the host loopback address for local testing. Before production, configure authentication and appropriate network controls; Docker versions older than 28 have a documented same-network caveat for localhost publishing. A `HEALTHCHECK --interval=30s` line sits near the end of the container file.

Binlog replication leaves failover to a controller

Replication is asynchronous and uses a binlog the way MySQL does. Failover rides on Redis sentinel, so a promotion can be driven by tooling that already speaks Redis. Cluster mode is a proxyless, centralized design whose access method stays compatible with Redis cluster clients, and any Redis cluster SDK is meant to work against it. What the server itself does not provide is the decision about when to promote. `kvrocks-controller` is named for managing clusters through failover and scaling up or down, and `kvrocks_exporter` is named for exporting monitor metrics. Both live in separate repositories and neither ships inside this one, so a multi node deployment assembles three pieces and has to match their versions by hand, because no compatible set is pinned anywhere in the README. A client that already speaks the Redis protocol to port 6666 needs nothing else in front of a single node.

Data moves both ways, through two named tools

Data written by Redis can be brought across by RedisShake, and data held by Kvrocks can be pushed back to Redis with `kvrocks2redis`. That second tool is not a download but another target of the same build script, which means a reverse migration needs the same C++ toolchain as the server, and on CentOS that means the devtoolset-11 path described earlier. Both directions have a named tool, and neither is called out as lossless anywhere in the README, so field coverage has to be checked against the supported commands page before any cutover. A single node evaluation needs none of that, since `./build/kvrocks -c kvrocks.conf` starts one server against one configuration file with no external service and no second port beyond 6666. Readers who care about the data model rather than the wire protocol are pointed to a page on designing complex structures on RocksDB and a separate page on replication design.

Editorial conclusion

Kvrocks fits teams that already run Redis clients and want key value storage to stop competing with the process for memory, provided they accept a disk based write path in exchange. It does not fit anyone who needs synchronous replication semantics or who wants one binary to run, because failover and cluster operations sit in `kvrocks-controller` and metrics sit in `kvrocks_exporter`, two separate repositories. Before adopting it, check the supported commands page against your own workload and pin a version tag rather than tracking the default branch.

Frequently asked questions

What is Kvrocks?

Kvrocks is a distributed key value NoSQL database written in C++ that uses RocksDB as its storage engine and is compatible with the Redis protocol, so any Redis client can reach it. Its replication and storage design were inspired by rocksplicator and blackwidow.

Apache Kvrocks vs Redis

Kvrocks keeps the Redis protocol but moves storage to RocksDB, and its stated intent is to decrease memory cost and increase capacity compared to Redis. On top of that it adds a token per namespace, binlog style async replication, sentinel based failover and a proxyless centralized cluster that Redis cluster clients can still drive.

Kvrocks alternative

The repository names no alternative to Kvrocks itself. For moving data it names RedisShake to migrate from Redis to Kvrocks, and `kvrocks2redis`, built through `./x.py build`, to migrate in the other direction.

Official sources

  1. apache/kvrocks on GitHub
  2. License: Apache-2.0
  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/apache-kvrocks.svg)](https://hysenlabs.com/projects/apache-kvrocks)

Star history chart for your README

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

Was this useful?