Go SDK
Zero-dependency Go client for SapixDB: write records, query with SaQL, time travel, graph edges, SSE streaming, and error handling.
What you'll learn
- ✓go get github.com/sapixdb/sapixdb-go — zero external dependencies, Go 1.21+
- ✓sapixdb.New(Config{URL, Agent, APIKey}) — create a client
- ✓db.WriteRecord(ctx, payload) — write any Go struct as a strand record
- ✓db.Query(ctx, SaQL{Type, Limit, Where}) — filter, sort, paginate
- ✓SaQL.AsOf — point-in-time query with HLC timestamp
- ✓db.AddEdge / db.GetEdges — graph edge management
- ✓db.Stream(ctx, filter) — SSE channel for live records
- ✓SapixError type — StatusCode + Message for 4xx/5xx responses
Write a Go program that appends 10 records to an orders agent, queries for records where status=pending, then streams new records in a goroutine while you write one more.
## Go SDK
The official SapixDB Go client (github.com/sapixdb/sapixdb-go) uses only the standard library — no external dependencies. Context-aware, goroutine-safe, Go 1.21+.
Install
go get github.com/sapixdb/sapixdb-goCreate a client
`go
import sapixdb "github.com/sapixdb/sapixdb-go"
db := sapixdb.New(sapixdb.Config{
URL: "http://localhost:7475",
Agent: "orders",
APIKey: os.Getenv("SAPIX_API_KEY"),
})
`
Write a record
`go
type Order struct {
OrderID string json:"order_id"
Total float64 json:"total"
Status string json:"status"
}
res, err := db.WriteRecord(ctx, Order{
OrderID: "ord_001",
Total: 49.99,
Status: "pending",
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Wrote:", res.ContentHash)
`
Query with SaQL
results, err := db.Query(ctx, sapixdb.SaQL{
Type: "latest",
Limit: 20,
Where: []sapixdb.Filter{
{Field: "status", Op: "eq", Value: "pending"},
},
})
for _, rec := range results.Records {
fmt.Println(rec.Payload)
}Time travel (as_of)
var asOf uint64 = 1750000000000 << 16
results, err := db.Query(ctx, sapixdb.SaQL{
Type: "latest",
AsOf: &asOf,
Limit: 50,
})Graph edges
err = db.AddEdge(ctx, sapixdb.Edge{
SrcAgent: "orders",
DstAgent: "invoices",
EdgeType: "has_invoice",
})
edges, err := db.GetEdges(ctx, "orders")
fmt.Println(edges)Stream live records (SSE)
events, errCh, err := db.Stream(ctx, sapixdb.StreamFilter{
Field: "status",
Op: "eq",
Value: "shipped",
})
for ev := range events {
fmt.Printf("new record: %s\n", ev.ContentHash)
}
if err := <-errCh; err != nil {
log.Fatal(err)
}Error handling
res, err := db.WriteRecord(ctx, payload)
if err != nil {
var sapixErr *sapixdb.SapixError
if errors.As(err, &sapixErr) {
fmt.Println(sapixErr.StatusCode, sapixErr.Message)
}
}---
## SDK operation reference
| Operation | Go method |
|---|---|
| Write record | db.WriteRecord(ctx, payload) |
| Batch write | db.BatchWrite(ctx, records) |
| Query (SaQL) | db.Query(ctx, saql) |
| Get by hash | db.GetRecord(ctx, hash) |
| Time travel | set SaQL.AsOf |
| Graph edges | db.AddEdge, db.GetEdges |
| SSE stream | db.Stream(ctx, filter) |
| Blob upload | db.PutBlob(ctx, reader) |
| Chain verify | db.VerifyChain(ctx) |
---
See also: Lesson 49 (Python SDK), Lesson 50 (TypeScript SDK), /docs/sdk/go.