herodb/docs/basics.md

HeroDB Basics

Launching HeroDB

To launch HeroDB, use the binary with required and optional flags. The --admin-secret flag is mandatory, encrypting the admin database (DB 0) and authorizing admin access.

Launch Flags

• --dir <path>: Directory for database files (default: current directory).
• --port <port>: TCP port for Redis protocol (default: 6379).
• --debug: Enable debug logging.
• --sled: Use Sled backend (default: Redb).
• --enable-rpc: Start JSON-RPC management server on port 8080.
• --rpc-port <port>: Custom RPC port (default: 8080).
• --admin-secret <secret>: Required secret for DB 0 encryption and admin access.

Example:

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

Deprecated flags (--encrypt, --encryption-key) are ignored for data DBs; per-database encryption is managed via RPC.

Admin Database (DB 0)

DB 0 acts as the administrative database instance, storing metadata for all user databases (IDs >= 1). It controls existence, access control, and per-database encryption. DB 0 is always encrypted with the --admin-secret.

When creating a new database, DB 0 allocates an ID, registers it, and optionally stores a per-database encryption key (write-only). Databases are public by default; use RPC to set them private, requiring access keys for SELECT (read or readwrite based on permissions). Keys are persisted in DB 0 for managed AGE operations.

Access DB 0 with SELECT 0 KEY <admin-secret>.

Symmetric Encryption

HeroDB supports stateless symmetric encryption via SYM commands, using XChaCha20-Poly1305 AEAD.

Commands:

• SYM KEYGEN: Generate 32-byte key. Returns base64-encoded key.
• SYM ENCRYPT <key_b64> <message>: Encrypt message. Returns base64 ciphertext.
• SYM DECRYPT <key_b64> <ciphertext_b64>: Decrypt. Returns plaintext.

Example:

redis-cli SYM KEYGEN
# → base64_key

redis-cli SYM ENCRYPT base64_key "secret"
# → base64_ciphertext

redis-cli SYM DECRYPT base64_key base64_ciphertext
# → "secret"

RPC Options

Enable the JSON-RPC server with --enable-rpc for database management. Methods include creating databases, managing access keys, and setting encryption. See JSON-RPC Examples for payloads.

HeroDB Commands

HeroDB implements a subset of Redis commands over the Redis protocol. This document describes the available commands and their usage.

String Commands

PING

Ping the server to test connectivity.

redis-cli -p $PORT PING
# → PONG

ECHO

Echo the given message.

redis-cli -p $PORT ECHO "hello"
# → hello

SET

Set a key to hold a string value.

redis-cli -p $PORT SET key value
# → OK

Options:

• EX seconds: Set expiration in seconds
• PX milliseconds: Set expiration in milliseconds
• NX: Only set if key doesn't exist
• XX: Only set if key exists
• GET: Return old value

Examples:

redis-cli -p $PORT SET key value EX 60
redis-cli -p $PORT SET key value PX 1000
redis-cli -p $PORT SET key value NX
redis-cli -p $PORT SET key value XX
redis-cli -p $PORT SET key value GET

GET

Get the value of a key.

redis-cli -p $PORT GET key
# → value

MGET

Get values of multiple keys.

redis-cli -p $PORT MGET key1 key2 key3
# → 1) "value1"
#    2) "value2"
#    3) (nil)

MSET

Set multiple key-value pairs.

redis-cli -p $PORT MSET key1 value1 key2 value2
# → OK

INCR

Increment the integer value of a key by 1.

redis-cli -p $PORT SET counter 10
redis-cli -p $PORT INCR counter
# → 11

DEL

Delete a key.

redis-cli -p $PORT DEL key
# → 1

For multiple keys:

redis-cli -p $PORT DEL key1 key2 key3
# → number of keys deleted

TYPE

Determine the type of a key.

redis-cli -p $PORT TYPE key
# → string

EXISTS

Check if a key exists.

redis-cli -p $PORT EXISTS key
# → 1 (exists) or 0 (doesn't exist)

For multiple keys:

redis-cli -p $PORT EXISTS key1 key2 key3
# → count of existing keys

EXPIRE / PEXPIRE

Set expiration time for a key.

redis-cli -p $PORT EXPIRE key 60
# → 1 (timeout set) or 0 (timeout not set)

redis-cli -p $PORT PEXPIRE key 1000
# → 1 (timeout set) or 0 (timeout not set)

EXPIREAT / PEXPIREAT

Set expiration timestamp for a key.

redis-cli -p $PORT EXPIREAT key 1672531200
# → 1 (timeout set) or 0 (timeout not set)

redis-cli -p $PORT PEXPIREAT key 1672531200000
# → 1 (timeout set) or 0 (timeout not set)

TTL

Get the time to live for a key.

redis-cli -p $PORT TTL key
# → remaining time in seconds

PERSIST

Remove expiration from a key.

redis-cli -p $PORT PERSIST key
# → 1 (timeout removed) or 0 (key has no timeout)

Hash Commands

HSET

Set field-value pairs in a hash.

redis-cli -p $PORT HSET hashkey field1 value1 field2 value2
# → number of fields added

HGET

Get value of a field in a hash.

redis-cli -p $PORT HGET hashkey field1
# → value1

HGETALL

Get all field-value pairs in a hash.

redis-cli -p $PORT HGETALL hashkey
# → 1) "field1"
#    2) "value1"
#    3) "field2"
#    4) "value2"

HDEL

Delete fields from a hash.

redis-cli -p $PORT HDEL hashkey field1 field2
# → number of fields deleted

HEXISTS

Check if a field exists in a hash.

redis-cli -p $PORT HEXISTS hashkey field1
# → 1 (exists) or 0 (doesn't exist)

HKEYS

Get all field names in a hash.

redis-cli -p $PORT HKEYS hashkey
# → 1) "field1"
#    2) "field2"

HVALS

Get all values in a hash.

redis-cli -p $PORT HVALS hashkey
# → 1) "value1"
#    2) "value2"

HLEN

Get number of fields in a hash.

redis-cli -p $PORT HLEN hashkey
# → number of fields

HMGET

Get values of multiple fields in a hash.

redis-cli -p $PORT HMGET hashkey field1 field2 field3
# → 1) "value1"
#    2) "value2"
#    3) (nil)

HSETNX

Set field-value pair in hash only if field doesn't exist.

redis-cli -p $PORT HSETNX hashkey field1 value1
# → 1 (field set) or 0 (field not set)

HINCRBY

Increment integer value of a field in a hash.

redis-cli -p $PORT HINCRBY hashkey field1 5
# → new value

HINCRBYFLOAT

Increment float value of a field in a hash.

redis-cli -p $PORT HINCRBYFLOAT hashkey field1 3.14
# → new value

HSCAN

Incrementally iterate over fields in a hash.

redis-cli -p $PORT HSCAN hashkey 0
# → 1) "next_cursor"
#    2) 1) "field1"
#       2) "value1"
#       3) "field2"
#       4) "value2"

Options:

• MATCH pattern: Filter fields by pattern
• COUNT number: Suggest number of fields to return

Examples:

redis-cli -p $PORT HSCAN hashkey 0 MATCH f*
redis-cli -p $PORT HSCAN hashkey 0 COUNT 10
redis-cli -p $PORT HSCAN hashkey 0 MATCH f* COUNT 10

List Commands

LPUSH

Insert elements at the head of a list.

redis-cli -p $PORT LPUSH listkey element1 element2 element3
# → number of elements in the list

RPUSH

Insert elements at the tail of a list.

redis-cli -p $PORT RPUSH listkey element1 element2 element3
# → number of elements in the list

LPOP

Remove and return elements from the head of a list.

redis-cli -p $PORT LPOP listkey
# → element1

With count:

redis-cli -p $PORT LPOP listkey 2
# → 1) "element1"
#    2) "element2"

RPOP

Remove and return elements from the tail of a list.

redis-cli -p $PORT RPOP listkey
# → element3

With count:

redis-cli -p $PORT RPOP listkey 2
# → 1) "element3"
#    2) "element2"

LLEN

Get the length of a list.

redis-cli -p $PORT LLEN listkey
# → number of elements in the list

LINDEX

Get element at index in a list.

redis-cli -p $PORT LINDEX listkey 0
# → first element

Negative indices count from the end:

redis-cli -p $PORT LINDEX listkey -1
# → last element

LRANGE

Get a range of elements from a list.

redis-cli -p $PORT LRANGE listkey 0 -1
# → 1) "element1"
#    2) "element2"
#    3) "element3"

LTRIM

Trim a list to specified range.

redis-cli -p $PORT LTRIM listkey 0 1
# → OK (list now contains only first 2 elements)

LREM

Remove elements from a list.

redis-cli -p $PORT LREM listkey 2 element1
# → number of elements removed

Count values:

• Positive: Remove from head
• Negative: Remove from tail
• Zero: Remove all

LINSERT

Insert element before or after pivot element.

redis-cli -p $PORT LINSERT listkey BEFORE pivot newelement
# → number of elements in the list

BLPOP

Blocking remove and return elements from the head of a list.

redis-cli -p $PORT BLPOP listkey1 listkey2 5
# → 1) "listkey1"
#    2) "element1"

If no elements are available, blocks for specified timeout (in seconds) until an element is pushed to one of the lists.

BRPOP

Blocking remove and return elements from the tail of a list.

redis-cli -p $PORT BRPOP listkey1 listkey2 5
# → 1) "listkey1"
#    2) "element1"

If no elements are available, blocks for specified timeout (in seconds) until an element is pushed to one of the lists.

Keyspace Commands

KEYS

Get all keys matching pattern.

redis-cli -p $PORT KEYS *
# → 1) "key1"
#    2) "key2"

SCAN

Incrementally iterate over keys.

redis-cli -p $PORT SCAN 0
# → 1) "next_cursor"
#    2) 1) "key1"
#       2) "key2"

Options:

• MATCH pattern: Filter keys by pattern
• COUNT number: Suggest number of keys to return

Examples:

redis-cli -p $PORT SCAN 0 MATCH k*
redis-cli -p $PORT SCAN 0 COUNT 10
redis-cli -p $PORT SCAN 0 MATCH k* COUNT 10

DBSIZE

Get number of keys in current database.

redis-cli -p $PORT DBSIZE
# → number of keys

FLUSHDB

Remove all keys from current database.

redis-cli -p $PORT FLUSHDB
# → OK

Configuration Commands

CONFIG GET

Get configuration parameter.

redis-cli -p $PORT CONFIG GET dir
# → 1) "dir"
#    2) "/path/to/db"

redis-cli -p $PORT CONFIG GET dbfilename
# → 1) "dbfilename"
#    2) "0.db"

Client Commands

CLIENT SETNAME

Set current connection name.

redis-cli -p $PORT CLIENT SETNAME myconnection
# → OK

CLIENT GETNAME

Get current connection name.

redis-cli -p $PORT CLIENT GETNAME
# → myconnection

Transaction Commands

MULTI

Start a transaction block.

redis-cli -p $PORT MULTI
# → OK

EXEC

Execute all commands in transaction block.

redis-cli -p $PORT MULTI
redis-cli -p $PORT SET key1 value1
redis-cli -p $PORT SET key2 value2
redis-cli -p $PORT EXEC
# → 1) OK
#    2) OK

DISCARD

Discard all commands in transaction block.

redis-cli -p $PORT MULTI
redis-cli -p $PORT SET key1 value1
redis-cli -p $PORT DISCARD
# → OK

AGE Commands

AGE GENENC

Generate ephemeral encryption keypair.

redis-cli -p $PORT AGE GENENC
# → 1) "recipient_public_key"
#    2) "identity_secret_key"

AGE ENCRYPT

Encrypt message with recipient public key.

redis-cli -p $PORT AGE ENCRYPT recipient_public_key "message"
# → base64_encoded_ciphertext

AGE DECRYPT

Decrypt ciphertext with identity secret key.

redis-cli -p $PORT AGE DECRYPT identity_secret_key base64_encoded_ciphertext
# → decrypted_message

AGE GENSIGN

Generate ephemeral signing keypair.

redis-cli -p $PORT AGE GENSIGN
# → 1) "verify_public_key"
#    2) "sign_secret_key"

AGE SIGN

Sign message with signing secret key.

redis-cli -p $PORT AGE SIGN sign_secret_key "message"
# → base64_encoded_signature

AGE VERIFY

Verify signature with verify public key.

redis-cli -p $PORT AGE VERIFY verify_public_key "message" base64_encoded_signature
# → 1 (valid) or 0 (invalid)

AGE KEYGEN

Generate and persist named encryption keypair.

redis-cli -p $PORT AGE KEYGEN keyname
# → 1) "recipient_public_key"
#    2) "identity_secret_key"

AGE SIGNKEYGEN

Generate and persist named signing keypair.

redis-cli -p $PORT AGE SIGNKEYGEN keyname
# → 1) "verify_public_key"
#    2) "sign_secret_key"

AGE ENCRYPTNAME

Encrypt message with named key.

redis-cli -p $PORT AGE ENCRYPTNAME keyname "message"
# → base64_encoded_ciphertext

AGE DECRYPTNAME

Decrypt ciphertext with named key.

redis-cli -p $PORT AGE DECRYPTNAME keyname base64_encoded_ciphertext
# → decrypted_message

AGE SIGNNAME

Sign message with named signing key.

redis-cli -p $PORT AGE SIGNNAME keyname "message"
# → base64_encoded_signature

AGE VERIFYNAME

Verify signature with named verify key.

redis-cli -p $PORT AGE VERIFYNAME keyname "message" base64_encoded_signature
# → 1 (valid) or 0 (invalid)

AGE LIST

List all stored AGE keys.

redis-cli -p $PORT AGE LIST
# → 1) "keyname1"
#    2) "keyname2"

SYM Commands

SYM KEYGEN

Generate a symmetric encryption key.

redis-cli -p $PORT SYM KEYGEN
# → base64_encoded_32byte_key

SYM ENCRYPT

Encrypt a message with a symmetric key.

redis-cli -p $PORT SYM ENCRYPT <key_b64> "message"
# → base64_encoded_ciphertext

SYM DECRYPT

Decrypt a ciphertext with a symmetric key.

redis-cli -p $PORT SYM DECRYPT <key_b64> <ciphertext_b64>
# → decrypted_message

Server Information Commands

INFO

Get server information.

redis-cli -p $PORT INFO
# → Server information

With section:

redis-cli -p $PORT INFO replication
# → Replication information

COMMAND

Get command information (stub implementation).

redis-cli -p $PORT COMMAND
# → Empty array (stub)

Database Selection

SELECT

Select database by index.

redis-cli -p $PORT SELECT 0
# → OK

This expanded documentation includes all the list commands that were implemented in the cmd.rs file:
1. LPUSH - push elements to the left (head) of a list
2. RPUSH - push elements to the right (tail) of a list
3. LPOP - pop elements from the left (head) of a list
4. RPOP - pop elements from the right (tail) of a list
5. BLPOP - blocking pop from the left with timeout
6. BRPOP - blocking pop from the right with timeout
7. LLEN - get list length
8. LREM - remove elements from list
9. LTRIM - trim list to range
10. LINDEX - get element by index
11. LRANGE - get range of elements


## Updated Database Selection and Access Keys

HeroDB uses an `Admin DB 0` to control database existence, access, and encryption. Access to data DBs can be public (no key) or private (requires a key). See detailed model in `docs/admin.md`.

Examples:

```bash
# Public database (no key required)
redis-cli -p $PORT SELECT 1
# → OK

# Private database (requires access key)
redis-cli -p $PORT SELECT 2 KEY my-db2-access-key
# → OK

# Admin DB 0 (requires admin secret)
redis-cli -p $PORT SELECT 0 KEY my-admin-secret
# → OK