FAQ
Common questions from developers and architects evaluating VeltrixDB, answered from the same source material as the rest of these docs.
Protocol and compatibility
Does VeltrixDB support the Redis protocol (RESP)?
Not yet. You can't point an existing Redis client at VeltrixDB today. VeltrixDB has its own text protocol (nc/telnet-compatible: PUT/GET/DEL/PING) and a binary protocol used by the native SDKs, with a command surface intentionally close to Redis's. RESP compatibility is on the roadmap — once it ships, migrating will require only a connection-string change. See VeltrixDB vs. Redis and Limitations & Roadmap.
How hard is it to migrate an existing Redis application?
The API surface is designed to be close: PUT/GET/DEL map directly to SET/GET/DEL, MultiPut/MultiGet map to Redis pipelines, and SETNX, INCR, DECR, and CAS are all supported. For SDK-based migrations it's largely a client swap (e.g. redis.Redis(...) becomes veltrixdb.Client(...)) rather than a rewrite. Full details and code samples are in VeltrixDB vs. Redis.
Can I run VeltrixDB without Kubernetes?
Yes. VeltrixDB is a single Go binary that runs standalone via go build ./... or the published Docker image (docker run -p 9000:9000 ghcr.io/veltrixdb/veltrixdb:latest). Kubernetes support (Helm chart, CRD Operator, NVMe provisioner) is first-class but optional — it's the recommended path for multi-node production clusters, not a hard requirement.
Is there a managed cloud version of VeltrixDB?
No, not today. VeltrixDB is self-hosted only. A managed cloud offering is explicitly listed as planned work. See Limitations & Roadmap.
Consistency and architecture
Is VeltrixDB linearizable?
It depends on the deployment mode. standalone mode is single-node linearizable. raft mode gives linearizable writes via quorum commit through the Raft log; since v1.1.0, reads can be made linearizable too by starting the server with --linearizable-reads, which runs each GET through the Raft ReadIndex fence (quorum-confirmed, never stale). Without that flag, raft reads are served from local applied state and can be slightly stale. replicated mode is primary-copy replication for durability across copies and is not linearizable under concurrent writers to the same key. Use raft mode when linearizability matters. Details in Deployment Modes and Limitations & Roadmap.
What's the difference between raft mode and replicated mode?
raft mode commits writes through a Raft log to a quorum before acknowledging, and non-leader nodes redirect writes with MOVED <leader> — this gives linearizable writes. replicated mode instead does a local write followed by primary-copy replication, where the -consistency flag (eventual, quorum, or strong) controls how many replicas must apply the write before it's acknowledged. Replicated mode favors durability across copies over strict write ordering. See Deployment Modes.
Are all operations routed through the distributed layer in cluster modes?
Mostly, since v1.1.0. Plain key-value operations, atomic ops (CAS/INCR/DECR/SETNX), transactions, and — new in v1.1.0 — namespace, hash-field, vector, secondary-index, and list/set operations all go through the coordinator in raft mode (dedicated FSM ops) and replicated mode (composite-key KV effects). Two gaps remain: secondary-index metadata (IDXCREATE/IDXDROP) is node-local in replicated mode (raft mode replicates it), and QUERY/RANGE/SCANCUR reads are always served from the receiving node's local data. Both are called out in Limitations & Roadmap.
Storage and performance
How does VeltrixDB avoid RocksDB/LSM-style write amplification?
VeltrixDB uses WiscKey-style key-value separation: values are written once to an append-only Value Log (VLog) on NVMe and are never rewritten during compaction, unlike LSM trees (RocksDB, LevelDB) whose compaction repeatedly sorts and rewrites full records, typically producing 10–30× write amplification. VeltrixDB's compaction only garbage-collects dead space in the VLog, keeping write amplification at roughly 1.0× — every byte lands on NVMe exactly once. See VeltrixDB vs. Redis for the comparison table.
How does VeltrixDB keep P99 latency predictable under write pressure?
A three-tier, admission-controlled garbage collector rate-limits GC work proportional to read latency (rate cap around a 3 ms read EWMA, pause around 4 ms, with an emergency bypass around a 65% garbage ratio) so garbage can't accumulate to the point of causing a latency cliff. In the 30-minute sustained 1-billion-key benchmark, this produced zero GC emergency events. See Benchmarking Methodology for the full numbers.
What happens if a disk fails?
Since v1.1.0 the node degrades automatically: 5 consecutive I/O errors on a disk's WAL/VLog trip a per-disk breaker. The disk is marked FAILED — writes routed to it fail fast with ErrDiskFailed (a retriable node-degraded condition; retry on another replica), GC skips the disk, reads still try the device and are served from cache when possible, /readyz returns 503 (degraded: disks [N] failed) so orchestrators drain traffic, and INFO shows FAILED_DISKS. The breaker does not auto-reset — recovery is drain / replace / restart, per the Disaster Recovery runbook. Data on a failed disk is local to that disk rather than smeared across all of them, and durability comes from the group-commit WAL with fdatasync plus, in multi-node deployments, Raft or primary-copy replication across nodes. Full/incremental backup chains and the background CRC32C scrubber round out the recovery story.
Does VeltrixDB support range or prefix scans?
Not natively yet. The workaround today is namespaces plus NSSCAN, or a secondary index with a user-supplied extraction function. Native range/prefix scans are on the roadmap. See Limitations & Roadmap.
How much RAM does VeltrixDB need for a large dataset?
Only enough for the DRAM index and the LIRS cache you configure — not the full dataset. In the 100M-key/100-byte-value YCSB benchmark, VeltrixDB needed about 15 GB of RAM (with 400 GB provisioned as cache) versus 30–45 GB for the equivalent dataset fully resident in Redis. Values live on NVMe; only hot keys and the index need to be in memory. See Benchmarking Methodology.
Security and operations
How is data encrypted?
VeltrixDB supports AES-256-GCM encryption at rest, applied per record with a per-record 12-byte nonce, enabled via the -encrypt-at-rest flag with the key supplied through the VELTRIXDB_ENCRYPTION_KEY environment variable. In-cluster traffic can be protected with mTLS, and there's RBAC with per-namespace prefix restriction plus an append-only JSONL audit log (which never logs value bytes).
Is VeltrixDB's change data capture (CDC) durable?
Yes, as of v1.1.0 — when repl-ship is run with --checkpoint. The live CDC stream itself is still in-memory, but the durable /admin/changes catch-up feed (index-backed, includes tombstones) lets a restarted shipper replay exactly the delta it missed before rejoining the live stream, so no events are lost across shipper downtime. Without --checkpoint, events emitted while the shipper is down are still missed. Remaining caveats: last-write-wins conflict resolution only, and no back-pressure to the source. See Replication & CDC.
What consistency do I get in replicated mode vs. raft mode?
In replicated mode, the -consistency flag controls the acknowledgment point: eventual acknowledges after the local write, quorum after a majority of replicas apply it, and strong after all replicas apply it — but there's no single-writer ordering, so concurrent writers to the same key are not linearizable. In raft mode, writes are quorum-committed through the Raft log and are linearizable; reads are served from local state (possibly stale) by default, or made linearizable with the --linearizable-reads server flag (v1.1.0+), which fences each GET with a quorum-confirmed ReadIndex. Choose raft when write linearizability is required; choose replicated when you mainly need durability across copies. Full detail in Deployment Modes.
What benchmark tooling and hardware were used to produce VeltrixDB's published numbers?
Two harnesses: the project's own scripts/bench.sh (used for the 3-node GKE cluster figures on n2-highmem-64 instances with 8×375 GB NVMe per node) and YCSB 0.17.0 (used for the 100-million-key AWS EC2 benchmark with 4×873 GB NVMe disks). Both enforce pass/fail gates on packing density and GC emergency runs. Full methodology, hardware specs, and raw numbers are in Benchmarking Methodology.