Go Client

The Go client is a thread-safe, connection-pooled driver for VeltrixDB with the broadest API surface of any SDK — single-key ops, batches, namespaces, hash fields, atomic ops (CAS/INCR/DECR/SETNX), range scans, optimistic transactions, secondary indexes, and vector search.

Install

bash
go get github.com/VeltrixDB/veltrixdb-client-go

Requires Go 1.19+. No external dependencies — the client is built entirely on the standard library (net, crypto/tls, encoding/binary).

Quick start

This example is drawn directly from the SDK's bundled go/example/main.go: connect, ping, put/get/delete, run a batch, and fan out concurrent writes across the pool.

go
package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "time"

    vdb "github.com/VeltrixDB/veltrixdb-client-go"
)

func main() {
    // ── Connect ──────────────────────────────────────────────────────
    cfg := vdb.DefaultConfig()
    cfg.PoolSize = 16 // 16 persistent connections

    client, err := vdb.New("127.0.0.1:9000", cfg)
    if err != nil {
        log.Fatalf("connect: %v", err)
    }
    defer client.Close()

    ctx := context.Background()

    // ── Ping ─────────────────────────────────────────────────────────
    if err := client.Ping(ctx); err != nil {
        log.Fatalf("ping: %v", err)
    }

    // ── Put / Get / Delete ───────────────────────────────────────────
    if err := client.Put(ctx, "hello", []byte("world")); err != nil {
        log.Fatalf("put: %v", err)
    }

    val, err := client.Get(ctx, "hello")
    if err != nil {
        log.Fatalf("get: %v", err)
    }
    fmt.Printf("GET  hello = %s\n", val)

    if err := client.Delete(ctx, "hello"); err != nil {
        log.Fatalf("delete: %v", err)
    }

    // ErrNotFound is a known sentinel, not a hard error.
    _, err = client.Get(ctx, "hello")
    if errors.Is(err, vdb.ErrNotFound) {
        fmt.Println("GET  hello → not found (expected after delete)")
    }
}

Config

Config is passed to New; DefaultConfig() returns production-sane defaults that you can override selectively.

go
type Config struct {
    PoolSize    int           // connections to maintain (default 8)
    DialTimeout time.Duration // TCP/TLS handshake timeout (default 5s)
    IOTimeout   time.Duration // per-operation deadline (default 10s); 0 = no deadline
    TLS         *tls.Config   // nil = plain TCP
}

The client pre-dials all PoolSize connections inside New, so construction fails fast if the server is unreachable. Close() drains and closes every pooled connection; after Close, all methods return ErrClosed.

API surface

Every method takes a context.Context as its first argument, so cancellation and per-call deadlines compose naturally with the pool's own IOTimeout.

Core key-value

Batch operations

go
entries := []vdb.Entry{
    {Key: "user:1", Value: []byte(`{"name":"Alice","age":30}`)},
    {Key: "user:2", Value: []byte(`{"name":"Bob","age":25}`)},
    // With a 60-second TTL:
    {Key: "session:abc", Value: []byte("token-xyz"), TTLSeconds: 60},
}
mputResults, err := client.MultiPut(ctx, entries)
if err != nil {
    log.Fatalf("multiput: %v", err)
}
for i, r := range mputResults {
    if r.Err != nil {
        log.Printf("entry %d failed: %v", i, r.Err)
    }
}

getResults, err := client.MultiGet(ctx, []string{"user:1", "user:2", "user:99"})
for _, r := range getResults {
    if r.Found {
        fmt.Printf("GET  %s = %s\n", r.Key, r.Value)
    } else {
        fmt.Printf("GET  %s → not found\n", r.Key)
    }
}

Results are returned in the same order as the input. Only individual entries fail on partial errors — the batch itself only errors on connection or protocol-level failure.

Namespaces

Hash fields (per-field TTL)

Atomic operations

New in v1.1.0 — typed atomic ops (previously Rust/C++ only):

go
// Counter — missing key starts from 0
n, err := client.Incr(ctx, "counter", 5)   // n = 5
n, err = client.Decr(ctx, "counter", 2)    // n = 3

// Compare-and-swap
swapped, err := client.CAS(ctx, "hello", []byte("world"), []byte("earth"))
if err != nil {
    if errors.Is(err, vdb.ErrNotFound) {
        // key doesn't exist
    }
} else if !swapped {
    // current value didn't match "world"
}

// Distributed lock-style set-if-absent
created, err := client.SetNX(ctx, "lock", []byte("owner-A"))
// created == false → someone else holds the key

Range scans, transactions, indexes, and vectors

Beyond the wire-protocol operations documented in the client README, the Go client exposes a further set of methods (RangeScan, ScanCursor, Txn, KeyVersion, IdxCreate/IdxDrop/IdxQuery, VSet/VSearch, Query) implemented directly in client.go:

Txn semantics are read-committed optimistic CAS — atomic within the batch, but not serializable. Re-read versions with KeyVersion and retry on ErrTxnConflict.

TLS

go
import "crypto/tls"

// Server verification only
tlsCfg := &tls.Config{RootCAs: loadCACert("ca.crt")}
client, _ := veltrix.New("veltrix.example.com:9443", veltrix.Config{TLS: tlsCfg})

// mTLS (client certificate + server certificate)
tlsCfg := &tls.Config{
    Certificates: []tls.Certificate{loadCert("client.crt", "client.key")},
    RootCAs:      loadCACert("ca.crt"),
}

Auth

go
client, _ := veltrix.New("127.0.0.1:9000", veltrix.Config{PoolSize: 4})
client.Auth(ctx, "alice", "secret")
client.Put(ctx, "key", []byte("value"))

Error handling

The client defines three sentinel errors you should check with errors.Is: ErrNotFound, ErrClosed, and ErrTxnConflict.

go
val, err := client.Get(ctx, "missing-key")
if errors.Is(err, veltrix.ErrNotFound) {
    // key doesn't exist
}
if errors.Is(err, context.DeadlineExceeded) {
    // operation timed out
}

Internally, when an operation fails with anything other than ErrNotFound or ErrTxnConflict, the pool assumes the connection is broken: it discards it and dials a fresh replacement before returning the error to the caller.

Concurrent usage

The Client is safe for concurrent use from multiple goroutines — each call borrows a connection from the pool independently:

go
const workers = 50
done := make(chan struct{}, workers)
for i := 0; i < workers; i++ {
    go func(id int) {
        key := fmt.Sprintf("concurrent:%d", id)
        val := []byte(fmt.Sprintf("value-%d", id))
        if err := client.Put(ctx, key, val); err != nil {
            log.Printf("worker %d put: %v", id, err)
        }
        done <- struct{}{}
    }(i)
}
for i := 0; i < workers; i++ {
    <-done
}

Cluster-aware variant

This page covers github.com/VeltrixDB/veltrixdb-client-go — a single-node, connection-pooled client. The VeltrixDB server repository also bundles a separate cluster-aware client under github.com/VeltrixDB/veltrixdb/client (client.NewClient), which discovers cluster topology, builds a consistent-hash ring matching the server's, and follows Raft MOVED redirects automatically. Reach for that package specifically when talking to a raft or replicated mode deployment — see Deployment Modes.