Quickstart

Run VeltrixDB in Docker, talk to it with a one-line text-protocol test, and confirm the server is healthy — all in under a minute.

Run with Docker

No build required. Pull and run the published image, then talk to it over the text protocol using nc:

docker run -p 9000:9000 ghcr.io/veltrixdb/veltrixdb:latest

echo -e "PUT hello world\nGET hello\nPING" | nc localhost 9000

The same socket speaks every data type — counters, hashes, lists, sets, and vector search:

# atomic counter
echo -e "INCR pageviews\nINCR pageviews 10" | nc localhost 9000

# hash fields (per-field TTL)
echo -e "HSET user:42 name alice\nHGET user:42 name" | nc localhost 9000

# lists and sets
echo -e "RPUSH queue job-1\nLPOP queue\nSADD tags red\nSMEMBERS tags" | nc localhost 9000

# vector search (HNSW)
echo -e "VSET doc:1 0.12 0.94 0.31\nVSEARCH 3 0.10 0.90 0.30" | nc localhost 9000

Full syntax for every command is in the wire protocol reference; the type semantics live in the data model.

You should see OK, world, then PONG printed back.

Build from source

VeltrixDB's Go layer is cross-platform and builds cleanly on macOS and Linux. You'll need Go 1.19+.

go build ./...
go run ./cmd/server -addr :9000 -data ./dev-data -cache 256

This starts a single-node server listening on :9000, writing to a local ./dev-data directory, with a 256 MB LIRS cache. On Linux, the optional C++ acceleration layer (io_uring, ART index, NUMA pinning) is used automatically for production-grade throughput; the Go path works everywhere else.

8-disk production example

For production hardware with multiple NVMe disks, pass them as a comma-separated list via -data-dirs so shards fan out across all disks in parallel:

./veltrixdb -addr :9000 \
  -data-dirs /mnt/nvme0,/mnt/nvme1,/mnt/nvme2,/mnt/nvme3,\
/mnt/nvme4,/mnt/nvme5,/mnt/nvme6,/mnt/nvme7 \
  -cache 65536

With 8 disks, each disk serves 1024 of the 8192 shards, and a 64 GB (65536 MB) cache is allocated for hot data.

Connect with a client SDK

VeltrixDB ships client SDKs for six languages over the same binary protocol, with connection pooling built in. Here's the Python SDK:

import veltrixdb
db = veltrixdb.Client(host="localhost", port=9000)
db.put("user:1001", "alice")
print(db.get("user:1001"))  # alice

See the Python SDK reference for installation and the full API. Tip: MPUT/MGET batch operations are roughly 50× faster than issuing individual calls — use them for bulk loads.

Verify it's running

Every VeltrixDB node exposes a metrics and health endpoint on port 2112:

curl http://localhost:2112/healthz   # liveness probe
curl http://localhost:2112/readyz    # readiness probe
curl http://localhost:2112/metrics   # Prometheus scrape endpoint

/healthz returns 200 as soon as the process is alive; /readyz returns 503 until the storage engine has finished startup (for example, WAL replay) and is ready to serve traffic. /metrics exposes 60+ Prometheus metrics, including:

You can also open the built-in web dashboard at http://localhost:2112/admin/ui.