Client SDK Overview
VeltrixDB ships official client libraries for six languages, maintained in the separate Veltrixdb-client repository. Every SDK speaks the same auto-detected binary wire protocol, so behavior, performance characteristics, and error semantics are consistent no matter which one you pick. Search (v1.11) is not in those SDKs yet: use the Go client package in the server repository, or send the text commands over a socket.
Available SDKs
All clients connect to the plaintext TCP port (9000 by default, server flag -addr) or, when the server has TLS configured, to the separate TLS port (9443 by default, -tls-addr). The default Go server auto-detects the protocol per connection and also accepts a human-readable text protocol on the same port for quick nc/telnet testing, but the SDKs use the binary protocol.
| Language | Install | Min version |
|---|---|---|
| Go | go get github.com/VeltrixDB/veltrixdb-client-go | Go 1.19+ |
| Python | pip install veltrixdb | Python 3.8+ |
| Node.js | npm install veltrixdb-client | Node.js 16+ |
| Java | com.veltrixdb:veltrixdb-client:1.0.0 (Maven/Gradle) | Java 11+ (17+ to build from source) |
| Rust | cargo add veltrixdb-client | Rust 2021 edition |
| C++ | header-only — copy cpp/include/veltrixdb.hpp | C++17, POSIX sockets |
None of the SDKs pull in third-party runtime dependencies — Go, Python, Node.js, and Java use only their standard networking libraries; Rust is pure stdlib; C++ depends only on POSIX sockets.
One protocol, six languages
Every client dials a plain TCP (or TLS) socket and frames requests the same way: [1B cmd][2B keyLen][4B valLen][key][value], with a [1B status][4B payloadLen][payload] response. Connection pooling is either built into the client (Go, Java, Python, Node.js all ship a pool type) or trivially composable (Rust and C++ are single-connection today — wrap them in your own pool, e.g. r2d2 for Rust).
CAS, INCR, DECR, and SETNX are implemented as typed methods in all six clients — Go, Python, Node.js, and Java gained them in v1.1.0; Rust and C++ had them from the start. See each language page's "Atomic operations" section for exact signatures, or the Binary Protocol Reference for the wire framing.
-net=go). If a server is started with the experimental C++ front-end (-net=cpp|uring|poll), it answers only binary PUT (0x01), GET (0x02), DEL (0x03), PING (0x04), MPUT (0x06) and MGET (0x07); any other command — AUTH, atomics, namespaces, INFO, scans — fails, and that front-end runs only in standalone mode without -auth-config. Clients needing TLS always go through the Go server on -tls-addr.
Use MPUT / MGET — they are dramatically faster
Every SDK exposes a batch write (MultiPut / multi_put / multiPut) and batch read (MultiGet / multi_get / multiGet) call. These send one request frame carrying N entries instead of N separate round trips, and the server fans the work out across its 8192 shards in parallel. Batches of 256–1024 entries are typically many times faster than issuing the same number of individual Put/Get calls (the server measured 1.77M–3.54M keys/s for 8 clients sending 1024-key MPUTs, depending on hardware; see Benchmarking) — use them for bulk loads, cache warms, and any hot loop that touches more than a handful of keys.
Put calls, which each consume one full block. See the Performance Tuning guide for the block-packing details.
Vector, text and hybrid search
New in v1.11 The search commands — VCREATE (with QUANT, PQM, PQTRAIN, and GRAPH disk since v1.12), VSET … NS, VSEARCH with NS/EF/FILTER, VDEL, TSET/TDEL/TSEARCH, HSEARCH and IDXCREATE/IDXQUERY — are server features on the text and binary protocols. Client support:
| Client | Search API |
|---|---|
Go, in-repo github.com/VeltrixDB/veltrixdb/client — BinaryConn, TCPConn | Full: VCreate, VCreateWithOptions, VSetNS, VSet, VDel, VSearch, VSearchWithOptions, TSet, TDel, TSearch, HSearch, IdxCreate/IdxDrop/IdxQuery. See Go → Search. |
Go, in-repo cluster-aware client.Client | None (only Put/Get/Delete). |
| The six SDKs in Veltrixdb-client | Not updated with the search release. From any language, open a TCP socket to -addr and send the text commands, one per line; each search answers id score lines then END, or one ERR … line. The text protocol is line-based, so TSET text cannot contain newlines and filter values cannot contain spaces. |
text protocolVCREATE docs 4 QUANT int8 OK PUT doc-42 {"lang":"en"} OK VSET doc-42 NS docs 0.12 -0.03 0.88 0.41 OK VSEARCH 10 NS docs EF 128 FILTER lang = en 0.1 0 0.9 0.4 doc-42 0.9991367 END TSET doc-42 NS docs TEXT how to rotate keys OK TSEARCH 5 NS docs QUERY rotate doc-42 0.2876821 END
Command syntax, filters, memory layouts and measured recall are on Vector & Hybrid Search.
Browse by language
Cluster-aware client (Go, bundled with the server)
The SDKs above each talk to a single node. VeltrixDB's server repository also ships a separate, cluster-aware Go client (client.NewClient, package github.com/VeltrixDB/veltrixdb/client) for use against raft or replicated deployments. It fetches cluster topology with the TOPOLOGY command, builds the same consistent-hash ring the server uses to route keys, and transparently follows MOVED redirects to the current Raft leader. It uses the text protocol, offers only Put/Get/Delete, and has no search methods. This is a different package from veltrixdb-client-go covered on the Go page — reach for it specifically when you're running a multi-node cluster and want client-side routing. See Deployment Modes for when each mode applies.