Go SDK

Go client for the HeliosDB-Lite REST API.

Installation

The SDKs are Apache-2.0 and developed in the public HeliosDatabase/HeliosDB-SDKs repository. The Go client is fetched directly from that repository with go get; see SDKs & Integrations for the other languages.

go get github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go

Quick Start

Every Lite /v1 route needs Authorization: Bearer <JWT>, signed with the server’s HELIOSDB_JWT_SECRET (see Authentication). The Go client’s WithAPIKey option sends an X-API-Key header, which the stock heliosdb-lite start does not accept, so pass an http.Client that adds the bearer token:

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    heliosdb "github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go"
)

type bearer struct{ token string }

func (b bearer) RoundTrip(r *http.Request) (*http.Response, error) {
    r = r.Clone(r.Context())
    r.Header.Set("Authorization", "Bearer "+b.token)
    return http.DefaultTransport.RoundTrip(r)
}

func main() {
    ctx := context.Background()

    client, err := heliosdb.NewClient("http://localhost:8080",
        heliosdb.WithHTTPClient(&http.Client{Transport: bearer{os.Getenv("HELIOSDB_TOKEN")}}),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Query the main branch (POST /v1/branches/main/query)
    result, err := client.Query(ctx, "SELECT * FROM users WHERE id = $1", 1)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Columns, result.Rows)
}

Branching

branch, err := client.CreateBranch(ctx, "dev", "main")
res, err := client.QueryOnBranch(ctx, "dev", "SELECT count(*) FROM users")

Branches can also be managed in SQL: CREATE DATABASE BRANCH dev FROM main AS OF NOW.

Vector Search and Agent Memory

The client has VectorSearch and Memory helpers. The matching Lite REST endpoint groups are planned, so these calls return a not-implemented error against Lite today. Run vector search in SQL instead; see Vector Search.

See the REST API Reference for the routes Lite serves and the package source for the full Go API.