fomadev0/kiva-db repository overview

⁠KivaDB

A typed key-value, document and vector database in a single executable, written in Rust.

KivaDB stores typed values and JSON documents with indexes and queries, finds AI embeddings by similarity (exact or HNSW), caches the answers of language models by meaning, and groups changes in atomic transactions. Every write goes to disk with a checksum, and can be encrypted at rest. Replicas follow the master live and elect a new one by themselves when it dies. Applications talk to it over its own protocol, a REST API, or the Redis protocol, so existing Redis client libraries connect unchanged.

• Source code and documentation: github.com/fomadev/kiva-db⁠
• Full manual: DOCUMENTATION.md⁠
• What changed in 1.5.1: CHANGELOG.md⁠
• Desktop client: Kiva Studio⁠

⁠Quick start

docker run -d --name kivadb \
  -e KIVADB_ADMIN_PASSWORD=a-long-secret \
  -p 2911:2911 -p 8080:8080 -p 6379:6379 \
  -v kivadb-data:/data \
  fomadev0/kiva-db:1.5.1

Then connect with user kiva and the password you chose:

# Interactive shell inside the container
docker exec -it kivadb kivadb -u kiva

# REST API
curl -u kiva:a-long-secret http://localhost:8080/v1/key/user:1

# Any Redis client
redis-cli -p 6379 -a a-long-secret

KIVADB_ADMIN_PASSWORD is required: inside a container KivaDB listens on every network interface, and it refuses to do so without authentication.

⁠Tags

Images are built for linux/amd64. For ARM servers, build the image from the source: docker build -t kivadb:local .

⁠Ports

Each port accepts plain and encrypted (TLS) connections: HTTPS on 8080, rediss:// on 6379. Publish only the ports you use.

⁠Environment variables

⁠Encryption at rest

Create a key once, keep it safe (a password manager, a vault), and give it to the container:

docker run --rm fomadev0/kiva-db:1.5.1 keygen
docker run -d --name kivadb \
  -e KIVADB_ADMIN_PASSWORD=a-long-secret \
  -e KIVADB_ENCRYPTION_KEY=<the 64 characters> \
  -p 2911:2911 -v kivadb-data:/data \
  fomadev0/kiva-db:1.5.1

Records, index snapshots and vector graphs are then encrypted on disk: a copied volume or backup reveals nothing without the key, and nothing can be read without it either, so do not lose it. On a volume that already holds data, run docker exec -it kivadb kivadb -u kiva -e compact to encrypt it too; -e encryption shows what is left in clear.

⁠Data and backups

Everything lives in /data: mount a volume there, or the data disappears with the container. Back it up while it runs, then copy the archive out:

docker exec kivadb kivadb backup -u kiva -p "$KIVADB_ADMIN_PASSWORD" -o /data/backups/kivadb-$(date +%F).tar.gz
docker cp kivadb:/data/backups/. ./backups/

The archive holds the configuration, the users and every workspace, with a SHA-256 for each file and <archive>.sha256 for the whole. To restore into a new, empty volume (every checksum is verified before anything is written):

docker run --rm -v kivadb-new:/data -v "$PWD/backups":/backups \
  fomadev0/kiva-db:1.5.1 restore /backups/kivadb-2026-10-22.tar.gz --target /data

⁠Docker Compose

services:
  kivadb:
    image: fomadev0/kiva-db:1.5.1
    restart: unless-stopped
    environment:
      KIVADB_ADMIN_PASSWORD: ${KIVADB_ADMIN_PASSWORD:?set KIVADB_ADMIN_PASSWORD}
      # KIVADB_ENCRYPTION_KEY: ${KIVADB_ENCRYPTION_KEY}
    ports:
      - "2911:2911"
      - "8080:8080"
      - "6379:6379"
    volumes:
      - kivadb-data:/data

volumes:
  kivadb-data:

KIVADB_ADMIN_PASSWORD=a-long-secret docker compose up -d

⁠High availability

Run three containers (on three machines), make two of them replicas of the first, and turn automatic failover on everywhere:

docker exec -it kivadb kivadb -u kiva -e "config set failover.auto true"
docker exec -it kivadb kivadb -u kiva -e "replica of 10.0.0.11 2911"    # on the replicas

When the master dies, the replicas agree by majority, elect the most up-to-date one, and the other follows it; the old master becomes a replica when it comes back. Writes sent to a replica are refused with the master's address (READONLY: this node is a replica of ...).

⁠Updating

Inside a container, update the image, not the executable (kivadb update is for installations on Windows, Linux and macOS). The data in the volume is kept:

docker pull fomadev0/kiva-db:1.5.1
docker rm -f kivadb
# then the same docker run command, with the new tag

With Compose: change the tag in the file, then docker compose up -d. Back up first (see above).

⁠Features

• Typed values: string, number, boolean, null, array, object, bytes
• JSON documents: read and change single fields, secondary indexes, get where, count, sum, execution plans
• Vector search: get similar doc:*.embedding to [...] with cosine, dot or L2; exact in-memory indexes, or HNSW for large collections (0.5 ms instead of 105 ms on 100 000 vectors grouped by topic)
• Semantic cache for applications that call a language model: an answer comes back for a question already asked in other words
• Atomic transactions with savepoints and conflict detection
• Expiring keys (TTL), sorted keys and range queries; set ... if not exists, del ... if exists
• Redis protocol: strings, counters, expiry (with NX/XX/GT/LT), hashes, lists, sets, sorted sets, MULTI/EXEC, Lua scripts (EVAL, EVALSHA), publish/subscribe, databases 0 to 15, RESP2 and RESP3. Checked with ioredis, node-redis, rate-limiter-flexible and rate-limit-redis
• Users and roles, a personal workspace for each user, per-workspace grants and an audit log
• Replication with planned failover and automatic failover by majority
• Encryption at rest (AES-256-GCM) with key rotation, and encrypted connections (TLS) on every port
• kivadb backup / kivadb restore, while running, with SHA-256 checks
• Lua scripts and triggers, run atomically in a sandbox
• Change notifications over TCP, WebSocket and Server-Sent Events
• Optional value cache, LZ4 / Zlib compression, automatic compaction, integrity checks
• Commands over several lines and .kva command files, for example: docker exec -i kivadb kivadb -u kiva -p "$PASSWORD" < data.kva

⁠Image details

• Based on debian:bookworm-slim, containing only the kivadb executable
• Runs as the unprivileged user kivadb (uid 10001)
• Health check: kivadb status
• docker stop shuts KivaDB down cleanly

⁠Security

Every port accepts encrypted connections (TLS): KivaDB creates its certificate in /data/tls on first start, and docker exec kivadb kivadb tls shows its fingerprint for clients to check. Over the Internet, require encryption (docker exec -it kivadb kivadb -u kiva -e "config set tls.required true"), open only the ports you need, and encrypt the data at rest (see above).

⁠License

Fordima Public License (FPL)⁠. Running the published images is free for personal, academic and production use; see the license for the conditions on the source code.