Go client: github.com/relatedb/relate/clients/go
Install
go get github.com/relatedb/relate/clients/go # import relateGo 1.22+; cgo over the C ABI (librelate_ffi, ABI version 2, ADR-0502),
so CGO_ENABLED=1 and a C toolchain are required. The module ships its own
header but not the native library: download the release's
relate-ffi-<triple>.tar.gz for your platform, extract it, and build with
CGO_LDFLAGS="-L<dir>"; at run time put the same directory on
LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on macOS). Pin a release with
go get github.com/relatedb/relate/clients/go@vX.Y.Z (ADR-0592). In a repo
checkout, cargo build --release -p relate-ffi and go build from
clients/go find the library in target/ with no flags.
Minimal usage
import "github.com/relatedb/relate/clients/go"
db, _ := relate.Open(":memory:") // or "./mydata" / "./task.rl"
defer db.Close()
conn, _ := db.Connect() // or db.ConnectNamespace("system")
res, _ := conn.QueryParams("MATCH (n:Person {name: $name}) RETURN n",
map[string]any{"name": "Ada"})
n := res.Rows[0][0].(relate.Node) // typed values, never JSON
n.ElementID // elementId(n)
n.ID // id(n) — deprecated (ADR-0506)
res.QueryType // typed QueryType — "r" | "w" | "rw" | "s" (ADR-0162)
res.Namespace // typed Namespace — resolved (ADR-0117)
res.Bookmark // "relate:<n>" after a write
res.Stats // typed Stats — the 11 mutation counters, zeros included (ADR-0216)
res.Plan // *PlanDocument — EXPLAIN/PROFILE
res.Notifications // [] on a plain run; Severity / Category are typed, closed vocabularies
_ = conn.Begin() // explicit transaction
bookmark, _ := conn.Commit() // "" when nothing committedGotchas
- Metadata vocabularies are closed — a
QueryType,Namespace, notificationSeverityorCategory(or error stage) outside the documented set is anABI contract violated: ...error, like the Java and Swift clients. The offending value echoed into the message is sanitized — non-printable characters arrive escaped and the value is bounded. - The library must be findable — the cgo directives search the checkout's
target/debugandtarget/release; outside the build tree setDYLD_LIBRARY_PATH(macOS) /LD_LIBRARY_PATH(Linux) to the directory holdinglibrelate_ffi.dylib/.so. On macOS the linker needs the.dylib— a Linux.soleft intarget/debugfails withunknown file type. - Every value is typed —
int64(lossless, 2^53+1 round-trips),string(interior NULs kept),[]any/map[string]any,Node/Relationship(element ids, labels / type, properties),Path, temporals as component structs (not ISO strings),Point,Vector,Duration. Entities also carry the deprecated numeric ids:Node.ID,Relationship.ID/StartID/EndIDare exactlyid(n),id(r),id(startNode(r)),id(endNode(r))(ADR-0506); prefer the element ids for lookups. - Parameters are typed, not JSON — the params builder binds signed and
unsigned integers, floats,
bool,string, slices / arrays,map[string]T(keys sorted) and structs byjsontag; an unsupported type is refused before the statement runs withparameter "<name>": unsupported parameter type T. Never concatenate untrusted input into the statement text. - Errors are typed, never message-sniffed — engine and boundary failures
are
*relate.ErrorwithCode,GQLStatus,Stage(compile/runtime/internal) andRetryable; retry a unit of work exactly whenRetryable(the write-write conflict). A failedCommitsurfaces the conflict, so a retry loop checks bothQuery/QueryParamsandCommit. - Close what you open —
Connection.Closeis an implicit rollback; withoutDatabase.Closea file store cannot be reopened in the same process. One writer process per store;OpenReadOnlyreaders are unlimited;:memory:vanishes on close.Closeis idempotent and any method after it returnsErrClosed(errors.Is); a dropped handle is closed by its finalizer, but do not rely on it.
Spec
docs/api/go/spec.md (types, value mapping, errors, parameters, namespaces,
library build); runnable examples in docs/api/go/examples.