Go SDK

Recommended: github.com/jackc/pgx/v5 (direct PG wire) or github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go (REST API client) Repo: heliosdb-sdks Compatible with: all HeliosDB editions (Nano, Lite, Full)

---

UVP

There is no in-process Go embedding API for HeliosDB Nano — the engine is Rust. That’s by design: the Nano binary speaks the PostgreSQL v3 wire protocol natively, so the standard Go PostgreSQL drivers (pgx, lib/pq, database/sql, GORM, ent) connect without adapters. For services that prefer HTTP, the HeliosDB Go client (sdks/go in HeliosDB-SDKs) wraps the REST API: SQL, branches, vector stores and agent memory. No CGo or FFI is involved.

---

Path A — Direct PG Wire (pgx)

The first-choice path for Go services. Widely used driver, prepared statements, connection pooling, full SQL surface.

Install

go get github.com/jackc/pgx/v5@latest

Connect

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/jackc/pgx/v5"
)

const dsn = "postgresql://postgres:s3cret@127.0.0.1:5432/postgres"

func main() {
    ctx := context.Background()
    conn, err := pgx.Connect(ctx, dsn)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close(ctx)

    var v string
    if err := conn.QueryRow(ctx, "SELECT version()").Scan(&v); err != nil {
        log.Fatal(err)
    }
    fmt.Println(v)
}

CRUD

type Product struct {
    ID    int
    Name  string
    Price float64
}

// Schema (one-time)
_, err := conn.Exec(ctx, `
    CREATE TABLE IF NOT EXISTS products (
        id    SERIAL PRIMARY KEY,
        name  TEXT NOT NULL,
        price NUMERIC(10, 2)
    )`)

// Insert
var id int
err = conn.QueryRow(ctx,
    `INSERT INTO products (name, price) VALUES ($1, $2) RETURNING id`,
    "Widget", 9.99,
).Scan(&id)

// Read
rows, err := conn.Query(ctx,
    `SELECT id, name, price FROM products WHERE price < $1 ORDER BY id`, 50.0)
defer rows.Close()
for rows.Next() {
    var p Product
    rows.Scan(&p.ID, &p.Name, &p.Price)
    fmt.Println(p)
}

// Update
_, err = conn.Exec(ctx, `UPDATE products SET price = $1 WHERE id = $2`, 12.99, id)

// Delete
_, err = conn.Exec(ctx, `DELETE FROM products WHERE id = $1`, id)

Connection Pool

For HTTP services use pgxpool:

import "github.com/jackc/pgx/v5/pgxpool"

pool, err := pgxpool.New(ctx, dsn)
defer pool.Close()

// Use pool.Query / pool.Exec / pool.QueryRow exactly like *pgx.Conn

Transactions

tx, _ := conn.Begin(ctx)
defer tx.Rollback(ctx)        // no-op if Commit succeeds

_, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
if err != nil { return err }
_, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
if err != nil { return err }

return tx.Commit(ctx)

Vector Search

VECTOR(n) accepts the standard text literal '[v1,v2,...]' over the wire; we marshal []float32 to that form:

import (
    "strconv"
    "strings"
)

func vecLit(v []float32) string {
    parts := make([]string, len(v))
    for i, f := range v {
        parts[i] = strconv.FormatFloat(float64(f), 'f', 6, 32)
    }
    return "[" + strings.Join(parts, ",") + "]"
}

// Schema
conn.Exec(ctx, `
    CREATE TABLE IF NOT EXISTS docs (
        id SERIAL PRIMARY KEY,
        title TEXT,
        embedding VECTOR(384)
    );
    CREATE INDEX IF NOT EXISTS docs_emb_idx
        ON docs USING hnsw (embedding vector_cosine_ops);`)

// Insert
emb := make([]float32, 384)  // populate from your embedder
conn.Exec(ctx,
    `INSERT INTO docs (title, embedding) VALUES ($1, $2::vector)`,
    "Helios release", vecLit(emb))

// k-NN
qVec := make([]float32, 384)  // query vector
rows, _ := conn.Query(ctx,
    `SELECT id, title, embedding <=> $1::vector AS distance
     FROM docs ORDER BY distance LIMIT $2`,
    vecLit(qVec), 10)
defer rows.Close()
for rows.Next() {
    var id int
    var title string
    var dist float64
    rows.Scan(&id, &title, &dist)
    fmt.Printf("%.4f  %s\n", dist, title)
}

Distance operators:

Operator	Distance	Use case
<=>	Cosine	Normalized text/sentence embeddings
<->	L2	Image / unnormalized vectors
<#>	Negative inner product	Already-normalized, speed-critical

database/sql (standard library)

If you prefer the stdlib interface, pgx ships a stdlib adapter:

import (
    "database/sql"
    _ "github.com/jackc/pgx/v5/stdlib"
)

db, _ := sql.Open("pgx", dsn)
defer db.Close()

rows, _ := db.QueryContext(ctx, "SELECT id, name FROM users WHERE id = $1", 42)

GORM and ent ride on top of database/sql, so they work unchanged.

---

Path B — REST API Client (sdks/go)

For services that talk to Nano over HTTP. The client calls the REST API (/v1/...) that heliosdb-nano start serves on its HTTP port (8080 by default).

Install

go get github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go@latest

Connect + Query

import heliosdb "github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go"

client, err := heliosdb.NewClient("http://localhost:8080",
    heliosdb.WithAPIKey("api-key"), // only needed if the server requires a key
)
if err != nil {
    log.Fatal(err)
}

res, err := client.Query(ctx, "SELECT id, title FROM posts WHERE author = $1", "alice@example.com")
if err != nil {
    log.Fatal(err)
}
for _, row := range res.Rows {
    fmt.Println(row["id"], row["title"])
}

// Statements that don't return rows
n, err := client.Exec(ctx, "UPDATE posts SET body = $1 WHERE id = $2", "edited", 1)

Branches

branches, err := client.ListBranches(ctx)
dev, err := client.CreateBranch(ctx, "dev", "main")
res, err := client.QueryOnBranch(ctx, "dev", "SELECT count(*) FROM posts")

Vector Search

hits, err := client.VectorSearchByVector(ctx, "docs", queryVec,
    heliosdb.WithTopK(10),
    heliosdb.WithFilter(map[string]interface{}{"category": "tech"}),
)
for _, hit := range hits {
    fmt.Println(hit.ID, hit.Score, hit.Metadata["title"])
}

Agent Memory

mem := client.Memory("session-42")
_ = mem.Add(ctx, "user", "What's our refund policy?")
history, _ := mem.Get(ctx, 20)

Errors from non-2xx responses come back as *heliosdb.APIError (StatusCode, Message). The Go client does not wrap the auth or realtime endpoints — call those REST endpoints directly (see the BaaS REST tutorial below) or use the TypeScript SDK.

---

When to Pick Which

Need	Use
Backend service, heavy SQL	Path A (pgx)
GORM / ent / sqlx	Path A
Bulk imports (COPY FROM)	Path A
SQL over HTTP, branches, vector stores, agent memory	Path B
JWT auth flows, WebSocket realtime subscriptions	REST endpoints directly, or the TypeScript SDK

Both paths can share the same Nano server; data written via pgx is immediately visible through the REST API and vice versa.

---

Next Steps

• GO_EMBEDDED_APP — full Go service, end-to-end CRUD + vector search via pgx.
• BAAS_REST_API_TUTORIAL — REST endpoints at the curl level.
• VECTOR_SEARCH_TUTORIAL — distance metrics, HNSW tuning.
• Python SDK / TypeScript SDK — same patterns in other languages.