HeroDB is a Redis-compatible database built with Rust, offering a flexible and secure storage solution. It supports two primary storage backends: redb (default) and sled, both with full encryption capabilities. HeroDB aims to provide a robust and performant key-value store with advanced features like data-at-rest encryption, hash operations, list operations, and cursor-based scanning.

Purpose

The main purpose of HeroDB is to offer a lightweight, embeddable, and Redis-compatible database that prioritizes data security through transparent encryption. It's designed for applications that require fast, reliable data storage with the option for strong cryptographic protection, without the overhead of a full-fledged Redis server.

Features

Redis Compatibility: Supports a subset of Redis commands over RESP (Redis Serialization Protocol) via TCP.
Dual Backend Support:
- redb (default): Optimized for concurrent access and high-throughput scenarios.
- sled: A lock-free, log-structured database, excellent for specific workloads.
Data-at-Rest Encryption: Transparent encryption for both backends using the age encryption library.
Key-Value Operations: Full support for basic string, hash, and list operations.
Expiration: Time-to-live (TTL) functionality for keys.
Scanning: Cursor-based iteration for keys and hash fields (SCAN, HSCAN).
AGE Cryptography Commands: HeroDB-specific extensions for cryptographic operations.
Symmetric Encryption: Stateless symmetric encryption using XChaCha20-Poly1305.
Admin Database 0: Centralized control for database management, access control, and per-database encryption.

Quick Start

Building HeroDB

To build HeroDB, navigate to the project root and run:

cargo build --release

Running HeroDB

Launch HeroDB with the required --admin-secret flag, which encrypts the admin database (DB 0) and authorizes admin access. Optional flags include --dir for the database directory, --port for the TCP port (default 6379), --sled for the sled backend, and --enable-rpc to start the JSON-RPC management server on port 8080.

Example:

./target/release/herodb --dir /tmp/herodb --admin-secret myadminsecret --port 6379 --enable-rpc

For detailed launch options, see Basics.

Usage with Redis Clients

HeroDB can be interacted with using any standard Redis client, such as redis-cli, redis-py (Python), or ioredis (Node.js).

Example with `redis-cli`

redis-cli -p 6379 SET mykey "Hello from HeroDB!"
redis-cli -p 6379 GET mykey
# → "Hello from HeroDB!"

redis-cli -p 6379 HSET user:1 name "Alice" age "30"
redis-cli -p 6379 HGET user:1 name
# → "Alice"

redis-cli -p 6379 SCAN 0 MATCH user:* COUNT 10
# → 1) "0"
#    2) 1) "user:1"

Cryptography

HeroDB supports asymmetric encryption/signatures via AGE commands (X25519 for encryption, Ed25519 for signatures) in stateless or key-managed modes, and symmetric encryption via SYM commands. Keys are persisted in the admin database (DB 0) for managed modes.

For details, see AGE Cryptography and Basics.

Database Management

Databases are managed via JSON-RPC API, with metadata stored in the encrypted admin database (DB 0). Databases are public by default upon creation; use RPC to set them private, requiring access keys for SELECT operations (read or readwrite based on permissions). This includes per-database encryption keys, access control, and lifecycle management.

For examples, see JSON-RPC Examples and Admin DB 0 Model.

Documentation

For more detailed information on commands, features, and advanced usage, please refer to the documentation:

README.md

HeroDB