herodb/README.md

HeroDB

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.

Quick Start

Building HeroDB

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

cargo build --release

Running HeroDB

You can start HeroDB with different backends and encryption options:

Default redb Backend

./target/release/herodb --dir /tmp/herodb_redb --port 6379

sled Backend

./target/release/herodb --dir /tmp/herodb_sled --port 6379 --sled

redb with Encryption

./target/release/herodb --dir /tmp/herodb_encrypted --port 6379 --encrypt --key mysecretkey

sled with Encryption

./target/release/herodb --dir /tmp/herodb_sled_encrypted --port 6379 --sled --encrypt --key mysecretkey

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"

Documentation

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

• Basics
• Supported Commands
• AGE Cryptography