725 lines
15 KiB
Markdown
725 lines
15 KiB
Markdown
# 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:
|
|
```bash
|
|
./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:
|
|
```bash
|
|
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](./rpc_examples.md) 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.
|
|
```bash
|
|
redis-cli -p $PORT PING
|
|
# → PONG
|
|
```
|
|
|
|
### ECHO
|
|
Echo the given message.
|
|
```bash
|
|
redis-cli -p $PORT ECHO "hello"
|
|
# → hello
|
|
```
|
|
|
|
### SET
|
|
Set a key to hold a string value.
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT GET key
|
|
# → value
|
|
```
|
|
|
|
### MGET
|
|
Get values of multiple keys.
|
|
```bash
|
|
redis-cli -p $PORT MGET key1 key2 key3
|
|
# → 1) "value1"
|
|
# 2) "value2"
|
|
# 3) (nil)
|
|
```
|
|
|
|
### MSET
|
|
Set multiple key-value pairs.
|
|
```bash
|
|
redis-cli -p $PORT MSET key1 value1 key2 value2
|
|
# → OK
|
|
```
|
|
|
|
### INCR
|
|
Increment the integer value of a key by 1.
|
|
```bash
|
|
redis-cli -p $PORT SET counter 10
|
|
redis-cli -p $PORT INCR counter
|
|
# → 11
|
|
```
|
|
|
|
### DEL
|
|
Delete a key.
|
|
```bash
|
|
redis-cli -p $PORT DEL key
|
|
# → 1
|
|
```
|
|
|
|
For multiple keys:
|
|
```bash
|
|
redis-cli -p $PORT DEL key1 key2 key3
|
|
# → number of keys deleted
|
|
```
|
|
|
|
### TYPE
|
|
Determine the type of a key.
|
|
```bash
|
|
redis-cli -p $PORT TYPE key
|
|
# → string
|
|
```
|
|
|
|
### EXISTS
|
|
Check if a key exists.
|
|
```bash
|
|
redis-cli -p $PORT EXISTS key
|
|
# → 1 (exists) or 0 (doesn't exist)
|
|
```
|
|
|
|
For multiple keys:
|
|
```bash
|
|
redis-cli -p $PORT EXISTS key1 key2 key3
|
|
# → count of existing keys
|
|
```
|
|
|
|
### EXPIRE / PEXPIRE
|
|
Set expiration time for a key.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT TTL key
|
|
# → remaining time in seconds
|
|
```
|
|
|
|
### PERSIST
|
|
Remove expiration from a key.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT HSET hashkey field1 value1 field2 value2
|
|
# → number of fields added
|
|
```
|
|
|
|
### HGET
|
|
Get value of a field in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HGET hashkey field1
|
|
# → value1
|
|
```
|
|
|
|
### HGETALL
|
|
Get all field-value pairs in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HGETALL hashkey
|
|
# → 1) "field1"
|
|
# 2) "value1"
|
|
# 3) "field2"
|
|
# 4) "value2"
|
|
```
|
|
|
|
### HDEL
|
|
Delete fields from a hash.
|
|
```bash
|
|
redis-cli -p $PORT HDEL hashkey field1 field2
|
|
# → number of fields deleted
|
|
```
|
|
|
|
### HEXISTS
|
|
Check if a field exists in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HEXISTS hashkey field1
|
|
# → 1 (exists) or 0 (doesn't exist)
|
|
```
|
|
|
|
### HKEYS
|
|
Get all field names in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HKEYS hashkey
|
|
# → 1) "field1"
|
|
# 2) "field2"
|
|
```
|
|
|
|
### HVALS
|
|
Get all values in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HVALS hashkey
|
|
# → 1) "value1"
|
|
# 2) "value2"
|
|
```
|
|
|
|
### HLEN
|
|
Get number of fields in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HLEN hashkey
|
|
# → number of fields
|
|
```
|
|
|
|
### HMGET
|
|
Get values of multiple fields in a hash.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT HINCRBY hashkey field1 5
|
|
# → new value
|
|
```
|
|
|
|
### HINCRBYFLOAT
|
|
Increment float value of a field in a hash.
|
|
```bash
|
|
redis-cli -p $PORT HINCRBYFLOAT hashkey field1 3.14
|
|
# → new value
|
|
```
|
|
|
|
### HSCAN
|
|
Incrementally iterate over fields in a hash.
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT LPUSH listkey element1 element2 element3
|
|
# → number of elements in the list
|
|
```
|
|
|
|
### RPUSH
|
|
Insert elements at the tail of a list.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT LPOP listkey
|
|
# → element1
|
|
```
|
|
|
|
With count:
|
|
```bash
|
|
redis-cli -p $PORT LPOP listkey 2
|
|
# → 1) "element1"
|
|
# 2) "element2"
|
|
```
|
|
|
|
### RPOP
|
|
Remove and return elements from the tail of a list.
|
|
```bash
|
|
redis-cli -p $PORT RPOP listkey
|
|
# → element3
|
|
```
|
|
|
|
With count:
|
|
```bash
|
|
redis-cli -p $PORT RPOP listkey 2
|
|
# → 1) "element3"
|
|
# 2) "element2"
|
|
```
|
|
|
|
### LLEN
|
|
Get the length of a list.
|
|
```bash
|
|
redis-cli -p $PORT LLEN listkey
|
|
# → number of elements in the list
|
|
```
|
|
|
|
### LINDEX
|
|
Get element at index in a list.
|
|
```bash
|
|
redis-cli -p $PORT LINDEX listkey 0
|
|
# → first element
|
|
```
|
|
|
|
Negative indices count from the end:
|
|
```bash
|
|
redis-cli -p $PORT LINDEX listkey -1
|
|
# → last element
|
|
```
|
|
|
|
### LRANGE
|
|
Get a range of elements from a list.
|
|
```bash
|
|
redis-cli -p $PORT LRANGE listkey 0 -1
|
|
# → 1) "element1"
|
|
# 2) "element2"
|
|
# 3) "element3"
|
|
```
|
|
|
|
### LTRIM
|
|
Trim a list to specified range.
|
|
```bash
|
|
redis-cli -p $PORT LTRIM listkey 0 1
|
|
# → OK (list now contains only first 2 elements)
|
|
```
|
|
|
|
### LREM
|
|
Remove elements from a list.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT KEYS *
|
|
# → 1) "key1"
|
|
# 2) "key2"
|
|
```
|
|
|
|
### SCAN
|
|
Incrementally iterate over keys.
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT DBSIZE
|
|
# → number of keys
|
|
```
|
|
|
|
### FLUSHDB
|
|
Remove all keys from current database.
|
|
```bash
|
|
redis-cli -p $PORT FLUSHDB
|
|
# → OK
|
|
```
|
|
|
|
## Configuration Commands
|
|
|
|
### CONFIG GET
|
|
Get configuration parameter.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT CLIENT SETNAME myconnection
|
|
# → OK
|
|
```
|
|
|
|
### CLIENT GETNAME
|
|
Get current connection name.
|
|
```bash
|
|
redis-cli -p $PORT CLIENT GETNAME
|
|
# → myconnection
|
|
```
|
|
|
|
## Transaction Commands
|
|
|
|
### MULTI
|
|
Start a transaction block.
|
|
```bash
|
|
redis-cli -p $PORT MULTI
|
|
# → OK
|
|
```
|
|
|
|
### EXEC
|
|
Execute all commands in transaction block.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT AGE GENENC
|
|
# → 1) "recipient_public_key"
|
|
# 2) "identity_secret_key"
|
|
```
|
|
|
|
### AGE ENCRYPT
|
|
Encrypt message with recipient public key.
|
|
```bash
|
|
redis-cli -p $PORT AGE ENCRYPT recipient_public_key "message"
|
|
# → base64_encoded_ciphertext
|
|
```
|
|
|
|
### AGE DECRYPT
|
|
Decrypt ciphertext with identity secret key.
|
|
```bash
|
|
redis-cli -p $PORT AGE DECRYPT identity_secret_key base64_encoded_ciphertext
|
|
# → decrypted_message
|
|
```
|
|
|
|
### AGE GENSIGN
|
|
Generate ephemeral signing keypair.
|
|
```bash
|
|
redis-cli -p $PORT AGE GENSIGN
|
|
# → 1) "verify_public_key"
|
|
# 2) "sign_secret_key"
|
|
```
|
|
|
|
### AGE SIGN
|
|
Sign message with signing secret key.
|
|
```bash
|
|
redis-cli -p $PORT AGE SIGN sign_secret_key "message"
|
|
# → base64_encoded_signature
|
|
```
|
|
|
|
### AGE VERIFY
|
|
Verify signature with verify public key.
|
|
```bash
|
|
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.
|
|
```bash
|
|
redis-cli -p $PORT AGE KEYGEN keyname
|
|
# → 1) "recipient_public_key"
|
|
# 2) "identity_secret_key"
|
|
```
|
|
|
|
### AGE SIGNKEYGEN
|
|
Generate and persist named signing keypair.
|
|
```bash
|
|
redis-cli -p $PORT AGE SIGNKEYGEN keyname
|
|
# → 1) "verify_public_key"
|
|
# 2) "sign_secret_key"
|
|
```
|
|
|
|
### AGE ENCRYPTNAME
|
|
Encrypt message with named key.
|
|
```bash
|
|
redis-cli -p $PORT AGE ENCRYPTNAME keyname "message"
|
|
# → base64_encoded_ciphertext
|
|
```
|
|
|
|
### AGE DECRYPTNAME
|
|
Decrypt ciphertext with named key.
|
|
```bash
|
|
redis-cli -p $PORT AGE DECRYPTNAME keyname base64_encoded_ciphertext
|
|
# → decrypted_message
|
|
```
|
|
|
|
### AGE SIGNNAME
|
|
Sign message with named signing key.
|
|
```bash
|
|
redis-cli -p $PORT AGE SIGNNAME keyname "message"
|
|
# → base64_encoded_signature
|
|
```
|
|
|
|
### AGE VERIFYNAME
|
|
Verify signature with named verify key.
|
|
```bash
|
|
redis-cli -p $PORT AGE VERIFYNAME keyname "message" base64_encoded_signature
|
|
# → 1 (valid) or 0 (invalid)
|
|
```
|
|
|
|
### AGE LIST
|
|
List all stored AGE keys.
|
|
```bash
|
|
redis-cli -p $PORT AGE LIST
|
|
# → 1) "keyname1"
|
|
# 2) "keyname2"
|
|
```
|
|
|
|
## SYM Commands
|
|
|
|
### SYM KEYGEN
|
|
Generate a symmetric encryption key.
|
|
```bash
|
|
redis-cli -p $PORT SYM KEYGEN
|
|
# → base64_encoded_32byte_key
|
|
```
|
|
|
|
### SYM ENCRYPT
|
|
Encrypt a message with a symmetric key.
|
|
```bash
|
|
redis-cli -p $PORT SYM ENCRYPT <key_b64> "message"
|
|
# → base64_encoded_ciphertext
|
|
```
|
|
|
|
### SYM DECRYPT
|
|
Decrypt a ciphertext with a symmetric key.
|
|
```bash
|
|
redis-cli -p $PORT SYM DECRYPT <key_b64> <ciphertext_b64>
|
|
# → decrypted_message
|
|
```
|
|
|
|
## Server Information Commands
|
|
|
|
### INFO
|
|
Get server information.
|
|
```bash
|
|
redis-cli -p $PORT INFO
|
|
# → Server information
|
|
```
|
|
|
|
With section:
|
|
```bash
|
|
redis-cli -p $PORT INFO replication
|
|
# → Replication information
|
|
```
|
|
|
|
### COMMAND
|
|
Get command information (stub implementation).
|
|
```bash
|
|
redis-cli -p $PORT COMMAND
|
|
# → Empty array (stub)
|
|
```
|
|
|
|
## Database Selection
|
|
|
|
### SELECT
|
|
Select database by index.
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```bash
|
|
# Private database (requires access key)
|
|
redis-cli -p $PORT SELECT 2 KEY my-db2-access-key
|
|
# → OK
|
|
```
|
|
|
|
```bash
|
|
# Admin DB 0 (requires admin secret)
|
|
redis-cli -p $PORT SELECT 0 KEY my-admin-secret
|
|
# → OK
|
|
```
|