Go SDK

The ParticleDB Go SDK provides both a PostgreSQL wire-protocol client (backed by lib/pq or pgx) and a native gRPC client. It includes helpers for vector search, KV operations, RAG pipelines, and AI functions.

Installation

go get github.com/particledb/particledb-go

Quick Start (PG Wire)

package main

import (
    "fmt"
    "log"

    particledb "github.com/particledb/particledb-go"
    _ "github.com/lib/pq" // PostgreSQL driver
)

func main() {
    // Connect with default config (localhost:5432)
    client, err := particledb.New(particledb.DefaultConfig())
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Run a query
    result, err := client.Query("SELECT * FROM users WHERE id = $1", 42)
    if err != nil {
        log.Fatal(err)
    }
    for _, row := range result.Rows {
        fmt.Println(row)
    }
}

Configuration

cfg := particledb.Config{
    Host:     "db.example.com",
    Port:     5433,
    User:     "admin",
    Password: "secret",
    Database: "mydb",
    PoolSize: 20,
    SSLMode:  "require",
}
client, err := particledb.New(cfg)

Or connect with a DSN string:

client, err := particledb.Connect("host=localhost port=5432 user=particledb dbname=particledb sslmode=disable")

Transactions

err := client.Transaction(func(tx *particledb.Tx) error {
    _, err := tx.Execute("INSERT INTO users (name) VALUES ($1)", "alice")
    if err != nil {
        return err // triggers rollback
    }
    _, err = tx.Execute("UPDATE counters SET val = val + 1 WHERE name = $1", "users")
    return err // nil = commit
})

Vector Search

// ANN search
results, err := client.Vector().Search("documents", "embedding",
    []float32{0.1, 0.2, 0.3},
    &particledb.VectorSearchOptions{K: 5},
)

// Insert with vector
err = client.Vector().Insert("documents",
    map[string]interface{}{"title": "My Doc", "content": "..."},
    "embedding", []float32{0.1, 0.2, 0.3},
)

// Create HNSW index
err = client.Vector().CreateIndex("documents", "embedding", "hnsw",
    map[string]interface{}{"m": "24", "ef_construction": "200"},
)

Key-Value Operations

kv := client.KV()

// Set / Get
kv.Set("user:1", "alice")
val, _ := kv.Get("user:1") // "alice"

// Set with TTL (seconds)
kv.SetWithTTL("session:abc", "data", 3600)

// Batch operations
kv.MSet(map[string]string{"a": "1", "b": "2"})
results, _ := kv.MGet([]string{"a", "b"})

// Atomic increment
newVal, _ := kv.Incr("counter", 1)

// Check existence
exists, _ := kv.Exists("user:1")

// Delete
deleted, _ := kv.Delete("user:1")

RAG (Retrieval-Augmented Generation)

rag := client.RAG()

// Create a pipeline
rag.CreatePipeline("qa", "documents", "embedding", "content", 5, "hybrid")

// Query using pipeline
answer, _ := rag.Query("What is ParticleDB?", "qa")

// Query with explicit options
answer, _ = rag.QueryWithOptions("What is ParticleDB?",
    "documents", "embedding", "content", 5,
)

AI Functions

ai := client.AI()

// Generate embeddings
embedding, _ := ai.Embed("Hello world", "text-embedding-ada-002")

// Batch embeddings
embeddings, _ := ai.EmbedBatch([]string{"Hello", "World"}, "text-embedding-ada-002")

// Text generation
result, _ := ai.Generate("Explain quantum computing", "gpt-4")

// Classification
label, _ := ai.Classify("I love this product!", []string{"positive", "negative", "neutral"})

// Summarization
summary, _ := ai.Summarize("Long text to summarize...")

gRPC Client

The SDK includes a native gRPC client that connects to the ParticleDB gRPC endpoint (default port 26257). This provides access to the ParticleDB service (SQL, batch, health) and the QueryService (query, streaming, DML).

Connecting

package main

import (
    "context"
    "fmt"
    "log"

    particledb "github.com/particledb/particledb-go"
)

func main() {
    client, err := particledb.NewGRPCClient("localhost", particledb.DefaultGRPCPort)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()

    health, err := client.Health(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("status=%s version=%s\n", health.Status, health.Version)
}

ExecuteSQL

// DDL
resp, err := client.ExecuteSQL(ctx, "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)")

// INSERT with parameters
resp, err = client.ExecuteSQL(ctx,
    "INSERT INTO users (id, name) VALUES ($1, $2)",
    particledb.IntValue(1),
    particledb.StringValue("alice"),
)
fmt.Println("rows affected:", resp.RowsAffected)

// SELECT
resp, err = client.ExecuteSQL(ctx, "SELECT id, name FROM users")
rows := particledb.ResultToMaps(resp)

StreamQuery

Stream large result sets via the server-streaming QueryStream RPC:

results, errCh := client.StreamQuery(ctx, "SELECT * FROM large_table")
for resp := range results {
    fmt.Println("batch:", len(resp.ResultSet.Rows), "rows")
}
if err := <-errCh; err != nil {
    log.Fatal(err)
}

BatchExecute

resp, err := client.BatchExecute(ctx, []string{
    "INSERT INTO users (id, name) VALUES (1, 'alice')",
    "INSERT INTO users (id, name) VALUES (2, 'bob')",
    "UPDATE users SET name = 'charlie' WHERE id = 1",
})
for i, result := range resp.Results {
    fmt.Printf("statement %d: affected=%d error=%q\n",
        i, result.RowsAffected, result.Error)
}

Connection Options

import "time"

client, err := particledb.NewGRPCClient("db.example.com", 26257,
    particledb.WithConnectTimeout(5 * time.Second),
    particledb.WithDialOptions(
        // add TLS, interceptors, etc.
    ),
)

Requirements

• Go 1.21+
• PG wire client: A PostgreSQL-compatible driver (e.g., github.com/lib/pq or github.com/jackc/pgx/v5/stdlib)
• gRPC client: google.golang.org/grpc (pulled in automatically via go mod tidy)

Next Steps

• SQL Reference — Full SQL syntax
• Vector Search — Vector search SQL syntax
• gRPC Connectivity — gRPC protocol details