Database

The Go Nucleus client provides type-safe access to all 14 data models over the PostgreSQL wire protocol.

Connection

import "github.com/neutron-dev/neutron-go/nucleus"

db, err := nucleus.Connect(ctx, "postgres://localhost:5432/mydb")
defer db.Close()

// Auto-detect Nucleus features
fmt.Println(db.Features().IsNucleus)  // true

SQL (Relational)

// Type-safe queries with struct scanning
type User struct {
    ID    int64  `db:"id"`
    Name  string `db:"name"`
    Email string `db:"email"`
}

users, err := nucleus.Query[User](ctx, db.SQL(),
    "SELECT id, name, email FROM users WHERE active = $1", true)

user, err := nucleus.QueryOne[User](ctx, db.SQL(),
    "SELECT * FROM users WHERE id = $1", 42)

Transactions

tx, err := db.Begin(ctx)

_, err = tx.SQL().Exec(ctx,
    "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, 1)
_, err = tx.SQL().Exec(ctx,
    "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, 2)

err = tx.Commit(ctx)  // or tx.Rollback(ctx)

Key-Value

kv := db.KV()

await kv.Set(ctx, "session:1", "data", nucleus.WithTTL(3600))
val, err := kv.Get(ctx, "session:1")
kv.Delete(ctx, "session:1")

// Lists
kv.LPush(ctx, "queue", "item1")
item, _ := kv.RPop(ctx, "queue")

// Hashes
kv.HSet(ctx, "user:1", "name", "Alice")
name, _ := kv.HGet(ctx, "user:1", "name")

// Sorted sets
kv.ZAdd(ctx, "leaderboard", 100.0, "player1")
top, _ := kv.ZRange(ctx, "leaderboard", 0, 9)

Vector Search

results, err := db.Vector().Search(ctx, "documents", queryEmbedding,
    nucleus.WithLimit(10),
    nucleus.WithMetric(nucleus.Cosine),
    nucleus.WithFilter(map[string]any{"category": "tech"}),
)

for _, r := range results {
    fmt.Printf("ID: %s, Score: %.4f\n", r.ID, r.Score)
}

Full-Text Search

results, err := db.FTS().Search(ctx, "articles", "machine learning",
    nucleus.WithFTSLimit(10),
    nucleus.WithFuzzy(2),
    nucleus.WithHighlight(true),
)

Graph

graph := db.Graph()

nodeID, _ := graph.AddNode(ctx, "Person", map[string]any{"name": "Alice"})
graph.AddEdge(ctx, "KNOWS", nodeID, otherID, map[string]any{"since": 2024})

result, _ := graph.Query(ctx,
    "MATCH (p:Person)-[:KNOWS]->(q) RETURN p.name, q.name")

Document

doc := db.Document()

id, _ := doc.Insert(ctx, "posts", map[string]any{
    "title": "Hello", "body": "World",
})

post, _ := doc.Get(ctx, id)
posts, _ := doc.Find(ctx, "posts", map[string]any{"author": "alice"})

Time Series

ts := db.TimeSeries()

ts.Insert(ctx, "cpu_usage", time.Now(), 72.5, nucleus.WithTags(map[string]string{"host": "web-01"}))
avg, _ := ts.RangeAvg(ctx, "cpu_usage", start, end)
last, _ := ts.Last(ctx, "cpu_usage")

Streams

streams := db.Streams()

id, _ := streams.XAdd(ctx, "events", map[string]string{"action": "login", "user": "alice"})
entries, _ := streams.XRange(ctx, "events", 0, -1, 100)

// Consumer groups
streams.XGroupCreate(ctx, "events", "workers", 0)
entries, _ = streams.XReadGroup(ctx, "events", "workers", "worker-1", 10)
streams.XAck(ctx, "events", "workers", entryID)

All 14 Models

| Model | Accessor | Key Methods | |-------|----------|-------------| | SQL | db.SQL() | Query, Exec | | Key-Value | db.KV() | Get, Set, Del, HSet, LPush, ZAdd | | Vector | db.Vector() | Search | | TimeSeries | db.TimeSeries() | Insert, RangeAvg, Last | | Document | db.Document() | Insert, Find, Get | | Graph | db.Graph() | AddNode, AddEdge, Query | | FTS | db.FTS() | Index, Search | | Geo | db.Geo() | Distance, Within | | Blob | db.Blob() | Put, Get, Delete | | Streams | db.Streams() | XAdd, XRange, XReadGroup | | Columnar | db.Columnar() | Insert, Sum, Avg | | Datalog | db.Datalog() | Assert, Query | | CDC | db.CDC() | Subscribe, GetChanges | | PubSub | db.PubSub() | Publish, Subscribe |