---
title: "Go SDK"
description: "Use the Apache-2.0 HeliosDB Go SDK against the HeliosDB Lite REST API: go get from source, send a JWT bearer token, run SQL and manage branches."
---

# 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](https://github.com/HeliosDatabase/HeliosDB-SDKs) repository. The Go client is fetched directly from that repository with `go get`; see [SDKs & Integrations](https://www.heliosdb.com/docs/lite/api/sdks/) for the other languages.

```bash
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](https://www.heliosdb.com/docs/lite/website/getting-started/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:

```go
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

```go
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](https://www.heliosdb.com/docs/lite/features/vector-search/).

See the [REST API Reference](https://www.heliosdb.com/docs/lite/website/api/readme/) for the routes Lite serves and the
[package source](https://github.com/HeliosDatabase/HeliosDB-SDKs/tree/main/sdks/go) for the full Go API.