What is SableDB?

SableDB is a key-value NoSQL database that utilizes RocksDB as its storage engine and is compatible with the Valkey protocol. It aims to reduce memory costs and increase capacity compared to Valkey. SableDB features include Valkey-compatible access via any Valkey client, up to 64K databases support, asynchronous replication using transaction log tailing and TLS connectivity support.

Building

SableDB is supported on all major OS: Linux, macOS and Windows

macOS

Make sure you have clang installed and then:

git clone https://github.com/sabledb-io/sabledb.git
cd sabledb
git submodule update --init
cargo build --release
cargo test --release

Linux (Ubuntu)

# RocksDB requires clang
sudo apt install -y clang

git clone https://github.com/sabledb-io/sabledb.git
cd sabledb
git submodule update --init
cargo build --release
cargo test --release

Windows

On Windows, we require MSYS2 terminal for building SableDB.

First, ensure that you have the required toolchain (beside Rust):

pacman -Sy git                                  \
           mingw-w64-clang-x86_64-toolchain     \
           mingw-w64-clang-x86_64-python3       \
           mingw-w64-clang-x86_64-cmake         \
           mingw-w64-clang-x86_64-libffi        \
           unzip                                \
           mingw-w64-clang-x86_64-rust-bindgen  \
           mingw-w64-clang-x86_64-nasm          \
           mingw-w64-clang-x86_64-gcc-compat

git clone https://github.com/sabledb-io/sabledb.git
cd sabledb
git submodule update --init
cargo build --release
cargo test --release

Running SableDB

./target/release/sabledb

Usage:

$target/release/sabledb [sabledb.ini]

Docker

docker build -t sabledb:latest .
docker run -p 6379:6379 sabledb:latest

Docker compose

If you prefer to use docker-compose, you can use the following command:

docker compose up --build

Tail logs

To tail the logs, use the below command:

docker exec -it sabledb-sabledb-1 /bin/bash -c "tail -f /var/lib/sabledb/log/sabledb.log.*"

Note: the container name (in the above example: sabledb-sabledb-1) can be found using the command docker ps

Supported features

• Persistent data using RocksDB - use SableDB as a persistent storage using Valkey's API
• TLS connections
• Replication using tailing of the transaction log
• Highly configurable, but comes with sensible default values
• Use the sb command line utility (target/release/sb) for performance testing
• Transactions ( MULTI / EXEC )
• Auto-failover & recovery
• Append-only audit trails ( AUDIT.APPEND / AUDIT.RANGE )

Benchmark tool - sb

SableDB uses its own benchmarking tool named sb. sb supports the following commands:

• set
• get
• lpush
• lpop
• rpush
• rpop
• incr
• ping
• hset
• setget (a mix between SET:GET commands, the ratio is controlled by the --setget-ratio option. The default is set to 1:4)

Run sb --help to get the full help message.

Below is a simple ( ping ) test conducted locally using WSL2 on Windows 10 (same machine is running both SableDB and sb...):

set test, on the same set-up (local machine, WSL2 on Windows 10):

Supported commands

IMPORTANT

SableDB is under constant development, if you are missing a command, feel free to open an issue and visit this page again in couple of days

---

String commands

List commands

Hash commands

Sorted Set (ZSET) commands

Set commands

Generic commands

Server management commands

Transaction

Connection management commands

Cluster commands

Locking commands

SableDB offers locking capabilities for application that requires it. Locks in SableDB are ephemeral data commands, this means, that the data is not persistent and is not replicated from primary to replica. These commands are marked as readonly so they can be used with replica servers.

Note about the locks:

• Locks are non recursive - if a client attempts to lock an already lock that it owns, it will get the DEADLOCK error
• Lock names are using their own namespace. This is means that you can have a string (or any other type) with name "my-lock" and a lock with the same name
• The LOCK command can be a blocking command if timeout is provided
• If a client terminates while holding a lock, the lock is released automatically by SableDB

The syntax is:

LOCK <LOCK-NAME> [TIMEOUT-MS]
UNLOCK <LOCK-NAME>

AuditLog commands

SableDB provides an append-only, per-key audit trail: a building block for future higher-level features (e.g. a task-coordination layer) that need a persisted, ordered history of events. Entries are never individually deleted or reordered -- delete the whole trail with the generic DEL command, and its entries are reclaimed by the same background eviction mechanism used for overwritten Lists/Hashes/Sets/Zsets.

Alongside each trail, SableDB also maintains a lightweight feed of AuditLog create/delete events across all task-ids, so a client can discover new activity without already knowing which task-ids to look at (e.g. to drive a live "activity feed" table view).

The syntax is:

AUDIT.APPEND <task-id> <event> [<details>]
AUDIT.RANGE <task-id> [FROM <seq>] [LIMIT <n>]
AUDIT.FEED [FROM <seq>] [LIMIT <n>]

• AUDIT.APPEND appends a new entry and returns its sequence number (0-based, per task-id).
• AUDIT.RANGE returns entries in append order, each as [sequence, timestamp_ms, event, details], starting at sequence FROM (default 0) and returning at most LIMIT entries (default 100).
• AUDIT.FEED returns [sequence, timestamp_ms, kind, task-id] rows (kind is created or deleted), oldest first, starting at feed sequence FROM (default 0) and returning at most LIMIT rows (default: unbounded). This feed is shard-local: sequence comes from a per-node counter, so it is only meaningful for paging one shard's feed, not for merging feeds from different nodes -- a client polling a cluster should discover shards via CLUSTER NODES, track a cursor per shard, and merge by timestamp_ms instead. A task's created row is replaced by its deleted row when the trail is deleted (not left alongside it), so the feed only grows without bound for trails that are created and never deleted -- there is still no eviction or retention policy for that portion.
• To delete a trail, use DEL <task-id>. DEL detects when a key holds an AuditLog and routes it through the same path AuditDb::delete() uses internally, so the AUDIT.FEED bookkeeping above (replacing the created row with a deleted row) still happens -- deleting an AuditLog isn't special-cased at the protocol level, just under the hood.

Time complexity

Benchmarks

Benchmark machine

Processor:      AMD Ryzen 9 7950X 16-Core Processor 4.50 GHz
Installed RAM:	64.0 GB (63.2 GB usable)
System type:    64-bit operating system, x64-based processor
Disk:           Crucial T700, 2TB PCIe Gen5 NVMe M.2 SSD

Benchmark setup

• Used 5M unique keys with varying payload size
• 512 clients on multiple threads
• get tests used randomg keys in the range of 0000001 - 5000000 (key size = 7Bytes)
• Before each test, the database was removed complete
• Before each get & setget test:
  • Delete the database
  • Fill the database with 5M unique keys with the test payload size (64/128/256)
  • Run the use case

Command set

Command used:

sb --threads 6 -c 512 -t set -n 5000000 -r 5000000 -d <64|128|256>

Command get

Command used:

sb --threads 6 -c 512 -t set -n 5000000 -r 5000000 -d <64|128|256> -z

Mixed load setget with 1:4 ratio (1 SET for every 4 GET calls)

Command used:

sb --threads 6 -c 512 -t setget -n 5000000 -r 5000000 -d <64|128|256> -z

Network only (ping command)

---