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 but not implemented. See VeltrixDB vs. Redis and Limitations & Roadmap.
Which network front-end serves which commands?
The default Go server (--net=go) serves both the text and binary protocols (auto-detected per connection), every command, AUTH, TLS on --tls-addr, and all deployment modes. The experimental C++ front-end (--net=cpp|uring|poll, New in v1.7) serves only the binary protocol's PUT GET DEL PING MPUT MGET, only in standalone mode and never with --auth-config; it is not faster overall in the measurements so far. See Performance Tuning.
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: stale on followers, while a newly elected leader holds GET/MGET until it has applied every write its predecessor acknowledged (v1.12). In v1.12 only GET and MGET pass that barrier; namespace, hash and range reads do not. Fixed in v1.14 every read on both protocols (namespace, hash, list, set, range, VER/GETVER, IDXQUERY, QUERY and searches) passes it. 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 by default, quorum, or strong) controls how many copies must have the write before it's acknowledged. Replicated mode favors durability across copies over strict write ordering; it resolves no conflicts, and in v1.12 a replica marked FAILED stays failed until the primary restarts. Fixed in v1.14 failed replicas are re-probed with backoff and caught up (SYNC_PENDING → SYNC) without a restart. A server runs one mode or the other, never both. See Deployment Modes.
Are all operations routed through the distributed layer in cluster modes?
Writes, yes. Plain key-value operations, atomic ops (CAS/INCR/DECR/SETNX), transactions, namespace, hash-field, list/set, vector, text and secondary-index writes — including IDXCREATE/IDXDROP, which replicated mode now carries as @idxdef/ keys — all go through the coordinator in raft mode (FSM ops) and replicated mode. Searches, QUERY and IDXQUERY fan out to every node. What stays local: RANGE/SCANCUR and namespace scans (receiving node's data only), and in raft mode on v1.13 and earlier namespace / hash / range reads skip the read barrier that GET and MGET pass, so they can be stale (Fixed in v1.14 every read passes it). See Limitations & Roadmap.
Storage and performance
How does VeltrixDB avoid RocksDB/LSM-style write amplification?
VeltrixDB uses WiscKey-style key-value separation: each value is appended once to an append-only Value Log (VLog) on NVMe, and only a small key/offset record goes to the WAL. There is no LSM-style sorted compaction (RocksDB and LevelDB are commonly cited at 10–30× write amplification). Values are rewritten only when VLog GC relocates the live values out of a region that has become mostly garbage (30% dead space triggers GC by default), so amplification depends on your overwrite rate; it has not been published as a measured figure. See VeltrixDB vs. Redis for the comparison table.
How does VeltrixDB keep P99 latency predictable under write pressure?
The VLog garbage collector is throttled on an EWMA of read latency: at 15 ms GC bandwidth is capped at 60 MB/s, above 20 ms GC pauses and each PUT sleeps 2 ms (admission control), and below 10 ms everything resumes. Independently, GC escalates when garbage piles up (200 MB/s at 50%, an uncapped emergency mode at 65% that bypasses the pause) so it cannot fall permanently behind. The benchmark harness treats any emergency GC run as a failed run. See Performance Tuning.
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?
Yes. RANGE and SCANCUR (cursor-based scan) run over an ordered skiplist of every live key, and namespaces offer prefix scans with NSSCAN. The ordered index costs ~90 B of RAM per key; point-lookup-only deployments can drop it with --disable-ordered-index, after which RANGE/SCANCUR return ErrOrderedIndexDisabled. In cluster modes these reads are served from the receiving node's local data (see Limitations & Roadmap).
How much RAM does VeltrixDB need for a large dataset?
Enough for the key index and the LIRS cache you configure — not the full dataset. Values live on NVMe; the index stays in RAM for every key: about 142 B/key with the off-heap native index (cgo builds; New in v1.6), plus ~90 B/key for the ordered index unless it is disabled. So RAM scales with key count. The 100M-key YCSB run reported ~15 GB of RAM in use besides the 400 GB cache (pure-Go build, before the native index). See Benchmarking Methodology.
Vector and hybrid search
Does VeltrixDB do vector search?
Yes. Each namespace holds an in-RAM HNSW graph over cosine similarity (VCREATE, VSET, VSEARCH, VDEL; dimensions 1–4096). Vectors persist as ordinary durable keys and share an id with the KV record they describe, so FILTER field op value is evaluated against that record. On GloVe-100 (100K real vectors, macOS, one thread) float32 reached recall@10 0.842 at ef 64 (p50 0.25 ms) and 0.953 at ef 256 (p50 0.77 ms). See Vector & Hybrid Search.
Can it do full-text and hybrid search?
Yes. TSET/TSEARCH is BM25 (k1 = 1.2, b = 0.75; lowercase Unicode tokenizer, no stemming or phrase queries). HSEARCH runs a vector and a text search and fuses the two ranked lists with weighted reciprocal rank fusion (ALPHA, default 0.5), so cosine and BM25 scores never need a common scale. See BM25 and hybrid search.
How much RAM do vectors need?
The full float32 vectors always live on NVMe; RAM holds per-namespace codes plus the graph. Measured at 768-dim (10K vectors, Go heap per vector): float32 3,383 B, QUANT int8 1,078 B, QUANT pq (m = 96) 493 B, PQ with GRAPH disk 378 B plus 216 B in a memory-mapped file. Quantized layouts re-rank candidates against the stored float32 vectors. See Vector & Hybrid Search for the sizing rule.
Does search work across a cluster?
Yes. In raft and replicated modes every vector / text / hybrid search (and QUERY / IDXQUERY) runs on all non-failed nodes and the results are merged; BM25 first sums every node's corpus statistics. A peer that does not answer within --search-timeout-ms fails the request unless --search-allow-partial. Sign node-to-node traffic with --cluster-secret-file — see Security.
What are the search limitations?
The graphs and inverted index are rebuilt from the persisted keys at every start, and searches are refused until that finishes (INFO → search_ready=1). On v1.13 and earlier, DEL of a record does not delete its vector or text document — issue VDEL/TDEL too. Fixed in v1.14 DEL also deletes the record’s vectors and documents in every namespace. Testing goes up to 100K real vectors (nothing at 10M+), and no same-hardware comparison with another vector database has been run. See Limitations.
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 32-byte key supplied through the VELTRIXDB_ENCRYPTION_KEY environment variable (base64) or a file named by -encryption-key-path. Note that PITR WAL archives hold decrypted values, so protect the archive directory. In-cluster traffic can be protected with TLS / mTLS and a shared HMAC cluster secret (v1.11), and there's RBAC with three roles (admin, readwrite, readonly) plus a JSONL audit log of writes (no user identity, never value bytes; in v1.12 single-key PUT/DEL only). The gap: there is no key rotation. On v1.13 and earlier, atomic ops (CAS/INCR/DECR/SETNX) also store their values unencrypted; Fixed in v1.14 they are compressed and encrypted like PUT, and the audit log covers every write path. See Security.
Is VeltrixDB's change data capture (CDC) durable?
The final state is, when repl-ship runs with --checkpoint. The live CDC stream is in-memory and drops events for slow subscribers; in v1.12 it carries only single-key PUT/DEL (not batched writes or atomic ops) — Fixed in v1.14 every write path emits; the durable /admin/changes catch-up feed (index-backed, includes tombstones) lets a restarted shipper replay each key's latest state before rejoining the live stream. Intermediate versions are not replayed. Without --checkpoint, events emitted while the shipper is down are missed. Remaining caveats: last-write-wins 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?
The reproducible headline numbers come from YCSB 0.17.0 (June 9 2026, pure-Go v1.0 build): an AWS EC2 high-memory instance (495 GB RAM), 4×873 GB NVMe with raw block-device VLog, 400 GB LIRS cache, 200 client threads, 100M keys × ~100 B values — 18,064 fdatasync-durable writes/s (P99 47.3 ms) and 427,697 reads/s with the whole dataset in cache (P99 2.77 ms). The project's scripts/bench.sh harness enforces pass/fail gates on packing density and GC emergency runs, and scripts/net-bench.sh compares network front-ends and storage configurations. The 3-node GKE figures (7.2M reads/s, 1B keys) come from an internal run with no published harness and are unverified. Later measurements (October 2026: adaptive group commit, go-ycsb A–F, vector recall) were taken mostly on one macOS laptop and are VeltrixDB-only. No same-hardware comparison with Aerospike, ScyllaDB or a vector database has been run yet. Full methodology, hardware specs, and raw numbers are in Benchmarking Methodology.