ToplingDB support for kvrocks

ToplingDB is compatible with RocksDB and provide higher performance, WebView, native support to prometheus, secondary instance on shared storage ...

ToplingDB distributed compaction can not be supported since kvrocks CompactionFilter need to access DB and calling DB::Get.

1. Build with ToplingDB

By default ToplingDB is not enabled, to compile kvrocks with ToplingDB, following instructions below:

1.1 Build ToplingDB

git clone https://github.com/topling/toplingdb
cd toplingdb
make -j`nproc` DEBUG_LEVEL=0 INSTALL_LIBDIR=/path/to/toplingdb/lib install

1.2 Build kvrocks with ToplingDB

# build with ToplingDB, you should build and install ToplingDB first
env TOPLINGDB_HOME=/path/to/toplingdb-repo TOPLINGDB_LIBDIR=/path/to/toplingdb/lib \
    ./x.py build -j`nproc` -DCMAKE_BUILD_TYPE=Release

# copy html files to kvrocks's ToplingDB document root, this makes webview pretty
cp /path/to/toplingdb-repo/sideplugin/rockside/src/topling/web/{index.html,style.css} \
   /path/to/kvrocks/toplingdb/document-root

2. Run with ToplingDB

env var TOPLING_CONF specifies ToplingDB json/yaml config which instructs kvrocks to run with ToplingDB.

If env var TOPLING_CONF is not specified, kvrocks will run without ToplingDB sideplugin and WebView...

User should change datadir in json config.

$ env TOPLING_CONF=kvtopling-community.json ./build/kvrocks -c kvrocks.conf

When run with ToplingDB, RocksDB options(rocksdb.*) in kvrocks.conf are ignored.

3. Run with ToplingDB shared storage secondary instance

Secondary instance on shared storage sharing same files of primary instance and keep catch up with primary.

$ env TOPLING_CONF=kvtopling-community-2nd.json ./build/kvrocks -c kvrocks.conf

4. ToplingDB config files

Primary Node	Secondary Node	ToplingZipTable
kvtopling-community.json	kvtopling-community-2nd.json	No
kvtopling-enterprise.json	kvtopling-enterprise-2nd.json	Yes

Databases created by community version can be smoothly upgraded to enterprise version.

---

---

---

---

• Slack Channel
• Mailing List (how to subscribe)

Apache Kvrocks(Incubating) is a distributed key value NoSQL database that uses RocksDB as storage engine and is compatible with Redis protocol. Kvrocks intends to decrease the cost of memory and increase the capacity while compared to Redis. The design of replication and storage was inspired by rocksplicator and blackwidow.

Kvrocks has the following key features:

• Redis Compatible: Users can access Apache Kvrocks via any Redis client.
• Namespace: Similar to Redis SELECT but equipped with token per namespace.
• Replication: Async replication using binlog like MySQL.
• High Available: Support Redis sentinel to failover when master or slave was failed.
• Cluster: Centralized management but accessible via any Redis cluster client.

Thanks to designers Lingyu Tian and Shili Fan for contributing the logo of Kvrocks.

Who uses Kvrocks

You can find Kvrocks users at the Users page.

Users are encouraged to add themselves to the Users page. Either leave a comment on the "Who is using Kvrocks" issue, or directly send a pull request to add company or organization information and logo.

Build and run Kvrocks

Prerequisite

# CentOS / RedHat
sudo yum install -y epel-release
sudo yum install -y git gcc gcc-c++ make cmake autoconf automake libtool libstdc++-static python3 which openssl-devel

# Ubuntu / Debian
sudo apt update
sudo apt install -y git gcc g++ make cmake autoconf automake libtool python3 libssl-dev

# macOS
brew install autoconf automake libtool cmake openssl

# Please force linking the openssl if still can't find after installing openssl
brew link --force openssl

Build

It is as simple as:

$ git clone https://github.com/apache/incubator-kvrocks.git
$ cd incubator-kvrocks

# build with ToplingDB, you should build and install ToplingDB first
env TOPLINGDB_HOME=../toplingdb TOPLINGDB_LIBDIR=/path/to/toplingdb/lib \
    ./x.py build -j`nproc` -DCMAKE_BUILD_TYPE=Release

# copy html files to kvrocks's ToplingDB document root, this makes webview pretty
cp /path/to/toplingdb-repo/sideplugin/rockside/src/topling/web/{index.html,style.css} \
   /path/to/kvrocks/toplingdb/document-root

# default build with rocksdb
$ ./x.py build # `./x.py build -h` to check more options;
               # especially, `./x.py build --ghproxy` will fetch dependencies via ghproxy.com.

To build with TLS support, you'll need OpenSSL development libraries (e.g. libssl-dev on Debian/Ubuntu) and run:

$ ./x.py build -DENABLE_OPENSSL=ON

To build with lua instead of luaJIT, run:

$ ./x.py build -DUSE_LUAJIT=OFF

Running Kvrocks

# env TOPLING_CONF instructs kvrocks to run with ToplingDB
$ env TOPLING_CONF=kvtopling-community.json ./build/kvrocks -c kvrocks.conf

Running Kvrocks using Docker

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

Connect Kvrocks service

$ redis-cli -p 6666

127.0.0.1:6666> get a
(nil)

Running test cases

$ ./x.py build --unittest
$ ./x.py test cpp # run C++ unit tests
$ ./x.py test go # run Golang (unit and integration) test cases

Supported platforms

• Linux
• macOS

Namespace

Namespace is used to isolate data between users. Unlike all the Redis databases can be visited by requirepass, we use one token per namespace. requirepass is regraded as admin token, and only admin token allows to access the namespace command, as well as some commands like config, slaveof, bgsave, etc. See the Namespace page for more details.

# 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

Cluster

Kvrocks implements a proxyless centralized cluster solution but its accessing method is completely compatible with the Redis cluster client. You can use Redis cluster SDKs to access the kvrocks cluster. More details, please see: Kvrocks Cluster Introduction

Documents

Documents are hosted at the official website.

• Supported Commands
• Design Complex Structure on RocksDB
• Replication Design

Tools

• Export the Kvrocks monitor metrics, please use kvrocks_exporter
• Migrate from redis to kvrocks, use redis-migrate-tool which was developed by vipshop
• Migrate from kvrocks to redis, use kvrocks2redis in the build directory

Contributing

Kvrocks community welcomes all forms of contribution and you can find out how to get involved on the Community and How to Contribute pages.

Performance

Hardware

• CPU: 48 cores Intel(R) Xeon(R) CPU E5-2650 v4 @ 2.20GHz
• Memory: 32 GiB
• NET: Intel Corporation I350 Gigabit Network Connection
• DISK: 2TB NVMe Intel SSD DC P4600

Benchmark Client: multi-thread redis-benchmark(unstable branch)

1. Commands QPS

kvrocks: workers = 16, benchmark: 8 threads/ 512 conns / 128 payload

latency: 99.9% < 10ms

2. QPS on different payloads

kvrocks: workers = 16, benchmark: 8 threads/ 512 conns

latency: 99.9% < 10ms

3. QPS on different workers

kvrocks: workers = 16, benchmark: 8 threads/ 512 conns / 128 payload

latency: 99.9% < 10ms

License

Kvrocks is under the Apache License Version 2.0. See the LICENSE file for details.

Social Media

• Medium
• Zhihu (in Chinese)
• WeChat Official Account (in Chinese, scan the QR code to follow)