Go SDK
Create a reusable Go client, pass request contexts and handle database results.
Use a reusable client for SQL and search requests from Go. This guide describes the 1.0.0-rc.1 source candidate and requires Go 1.23 or newer.
- Prepare the supported Go setupFollow the pinned source version’s installation instructions.
- Load connection values on the serverUse the complete OC_URL and its OC_TOKEN.
- Run parameterized SQLPass values separately and use a bounded request context.
- Inspect the typed resultCheck errors and close the client when finished.
Get the SDK
The SDK is available on GitHub. Follow the source-install steps in that README, then return here to run your first query. The 1.0 candidate package has not been released on registries; the examples below use its source API.
The candidate uses FromEnv, SQL.Run and operation namespaces. Older generated clients use service builders; changing only the import path will not migrate them.
Connect and run SQL
Set OC_URL to the complete HTTPS database address from Connect and OC_TOKEN to its credential. Do not construct or remove a tenant path.
With the candidate installed in your module, save this as main.go:
package main
import (
"context"
"log"
"time"
oc "github.com/originchaindb/originchaindb-go"
)
func main() {
db, err := oc.FromEnv()
if err != nil {
log.Fatal(err)
}
defer db.Close()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
result, err := db.SQL.Run(ctx, "SELECT $1 AS value", 7)
if err != nil {
log.Fatal(err)
}
log.Println(result.Rows)
}Run go run .. Expect one row with value equal to 7. This read-only query needs no table and creates no data. SQL values are variadic arguments after the statement; $1 binds 7. Parameters replace values, not table or column names. The client supports concurrent calls, and Close releases idle connections.
Credentials and permissions
Use the connection offered by Connect for your database configuration. See authentication for access-token availability and instance-credential fallback. PostgreSQL tools use their own database login.
Query other models
Every network operation takes a context.Context. Prepare the named schema, field or vector table before calling its method.
Full-text search
Within a function using the db and ctx above:
result, err := db.FTS.Search(ctx, "documents", "body", "account setup", oc.FTSSearchOptions{
Mode: "bm25",
K: 10,
})
if err != nil {
return err
}
for _, hit := range result.Hits {
log.Println(hit.DocID, hit.Score)
}This fragment belongs in a function returning error. Index the text field first. DocID identifies a source document; Score ranks matches for that search, not a confidence percentage. An empty Hits slice is a valid no-match result. Ranked, boolean and phrase searches use a consistent hits-and-facets result.
Vector search
Use db.Vector.Put, Search and Delete for embeddings. Your query must use the same dimension and embedding model as the stored vectors. Follow the vector guide for data preparation.
Graph queries
Use db.Graph.Query for Cypher with named parameters, or Neighbors and BFS for traversal. The graph quickstart covers the required tables and relationships.
Read results and errors
The common namespaces are SQL, Schemas, Rows, Vector, FTS and Graph. Usage and query metrics are also available.
SQL.Run retains rows, columns, column types, confirmed counts, buffered counts, nested results and the original envelope. Missing write counts remain unknown. Batches may partially succeed.
Use errors.As to inspect an *oc.Error. Its Kind, Status and RequestID help distinguish HTTP, network, timeout and protocol failures. Partial contains SQL outcomes when a batch fails. Response bodies are optional diagnostics; avoid logging private data.
Deadlines and retries
The client defaults to a 60-second HTTP timeout. Use a request context for a shorter deadline, as in the example, or oc.WithTimeout when constructing the client. The example's context expires after ten seconds; create an appropriate context for later independent work rather than reusing an expired one.
Requests are not retried automatically and redirects are not followed. A canceled or timed-out write may already have committed. Inspect its outcome before retrying; an idempotency key alone is not a replay guarantee.