> Complete content index: https://sirannon.sondelali.com/llms.txt

# Go client

> Call registered reads and writes from Go through generated structs, keep a query result current, and route calls across a replication group.

URL: https://sirannon.sondelali.com/docs/go-client
Section: Networked access
Version: 0.4 (@delali/sirannon-db@0.4.1, latest)

`github.com/assetcorp/sirannon-db/packages/go` connects a Go 1.26 or later program to a Sirannon server over WebSocket or HTTP. The client returns every integer in a row as an `int64` and every BLOB as a `[]byte`, so your program reads a value beyond 2^53 exactly as SQLite stores it. Its one dependency outside the standard library is `github.com/coder/websocket`.

Build `main.go` step by step against the `server.ts` from [registered operations](/docs/registered-operations), which serves the `orders` database and authenticates every request as the account `u_maria`.

## Install the module

Create a module in a `go` folder beside `operations.ts` and `server.ts`, and add the client to it. The examples on this page use version 0.1.0 of the client.

```bash
cd go
go mod init example.com/orders
go get github.com/assetcorp/sirannon-db/packages/go@v0.1.0
```

## Generate the references from the server's operations

The server refuses SQL unless you start it with `acceptSql: true`, so a Go program calls the operations that the server registers. `sirannon-codegen` writes a typed reference for each of them. In the workspace that holds `operations.ts` and `server.ts`, write the references into an `operations` package inside the module:

```bash
pnpm exec sirannon-codegen --registry ./operations.ts --go ./go/operations/operations.go --go-package operations
```

The 0.4.1 generator writes this complete file from that registry:

```go title="operations/operations.go"
// Code generated by sirannon-codegen. DO NOT EDIT.

package operations

import sirannon "github.com/assetcorp/sirannon-db/packages/go"

const RegistryDigest = "8848da8cd5d9537501dbf824f7bdaf25a64c3fec419376367088c832787c529d"

type OrdersMyOrdersRow struct {
	ID     any `json:"id"`
	Total  any `json:"total"`
	Status any `json:"status"`
}

type OrdersOrdersByStatusArgs struct {
	Status any `json:"status"`
}

type OrdersOrdersByStatusRow struct {
	ID     any `json:"id"`
	Total  any `json:"total"`
	Status any `json:"status"`
}

type OrdersPlaceOrderArgs struct {
	Total any `json:"total"`
}

var (
	OrdersMyOrders       = sirannon.ReadRef[sirannon.NoArgs, OrdersMyOrdersRow]{Name: "myOrders"}
	OrdersOrdersByStatus = sirannon.ReadRef[OrdersOrdersByStatusArgs, OrdersOrdersByStatusRow]{Name: "ordersByStatus"}
	OrdersPlaceOrder     = sirannon.WriteRef[OrdersPlaceOrderArgs]{Name: "placeOrder"}
)
```

The generator writes each operation as a `sirannon.ReadRef` or a `sirannon.WriteRef` variable, whose name joins the database and the operation in PascalCase. It writes the arguments and rows of each operation as structs with JSON tags, and an operation that takes no caller arguments, such as `myOrders`, takes `sirannon.NoArgs`. Every field takes the type `any`, because the registry declares the names of the arguments and columns without their types. When an argument has a name that a JSON tag cannot hold, the generator types the arguments of that operation as a `map[string]any`, and it types the rows as a `sirannon.Row` when a column has such a name.

A Go project that has no copy of the server's source can generate the same file from a manifest. Add `--manifest` when you generate the references in the server's workspace, and commit the manifest that the generator writes:

```bash
pnpm exec sirannon-codegen --registry ./operations.ts --go ./go/operations/operations.go --go-package operations --manifest ./operations.json
```

The Go project can then generate its references from that manifest through pnpm, without a Node project:

```bash
pnpm --package=@delali/sirannon-db@0.4.1 dlx sirannon-codegen --from-manifest ./operations.json --go ./operations/operations.go --go-package operations
```

## Read and write through the references

Delete the `data` folder beside `server.ts` and start the server with a secret `SIRANNON_TOKEN`, so that the database holds only the three orders that `server.ts` inserts. Save this complete `main.go` in the `go` folder and start it with `go run .` and the same `SIRANNON_TOKEN`:

```go title="main.go"
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	sirannon "github.com/assetcorp/sirannon-db/packages/go"

	"example.com/orders/operations"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	if token == "" {
		return errors.New("set SIRANNON_TOKEN to the application credential")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	client, err := sirannon.New("http://127.0.0.1:9876", sirannon.Options{
		Headers: map[string]string{"Authorization": "Bearer " + token},
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}

	pending, err := sirannon.Query(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", pending)
	results, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 2750})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", results)
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)
	return nil
}
```

```text result
[{ID:1 Total:4999 Status:pending}]
[{Changes:1 LastInsertRowID:4} {Changes:1 LastInsertRowID:4}]
[{ID:1 Total:4999 Status:pending} {ID:3 Total:890 Status:shipped} {ID:4 Total:2750 Status:pending}]
```

The server fills `ownerId` with `u_maria` on every call, so both reads leave out order 2, which `u_ravi` owns. `sirannon.Execute` returns one `ExecuteResult` for each statement of the write, which gives `placeOrder` one result for its insert and one for its counter update. The compiler refuses an argument or a column that the generated struct lacks, so a misspelt field fails `go build` before the program sends anything.

The client returns the error of a failed write without sending the write again. When the reply to a write goes missing, the server can still commit the write, so check the orders before your program repeats it.

## Keep the pending orders current

`sirannon.Live` opens a [live query](/docs/live-queries) on a registered read and returns once the server confirms it. Each time the table changes, the server sends edits to those rows. Once the client applies an edit, in the order in which the server sends them, it calls every listener with a `LiveUpdate`. Delete the `data` folder and start the server again, then start the extended file:

```go title="main.go"
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	sirannon "github.com/assetcorp/sirannon-db/packages/go"

	"example.com/orders/operations"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	if token == "" {
		return errors.New("set SIRANNON_TOKEN to the application credential")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	client, err := sirannon.New("http://127.0.0.1:9876", sirannon.Options{
		Headers: map[string]string{"Authorization": "Bearer " + token},
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}

	pending, err := sirannon.Query(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", pending)
	results, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 2750})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", results)
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)

	live, err := sirannon.Live(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"}) // [!code ++:25]
	if err != nil {
		return err
	}
	defer live.Close(ctx)
	fmt.Println("live", orderIDs(live.State().Rows))
	updated := make(chan struct{}, 1)
	stop := live.Subscribe(func(update sirannon.LiveUpdate[operations.OrdersOrdersByStatusRow]) {
		if update.Kind == sirannon.LiveUpdateOps {
			fmt.Println("live", orderIDs(update.State.Rows))
			select {
			case updated <- struct{}{}:
			default:
			}
		}
	})
	defer stop()
	if _, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 6400}); err != nil {
		return err
	}
	select {
	case <-updated:
	case <-ctx.Done():
		return ctx.Err()
	}
	return nil
}

func orderIDs(rows []operations.OrdersOrdersByStatusRow) []any { // [!code ++:7]
	ids := make([]any, 0, len(rows))
	for _, row := range rows {
		ids = append(ids, row.ID)
	}
	return ids
}
```

```text result
[{ID:1 Total:4999 Status:pending}]
[{Changes:1 LastInsertRowID:4} {Changes:1 LastInsertRowID:4}]
[{ID:1 Total:4999 Status:pending} {ID:3 Total:890 Status:shipped} {ID:4 Total:2750 Status:pending}]
live [1 4]
live [1 4 5]
```

`update.Kind` holds `LiveUpdateRows` for a fresh result, `LiveUpdateOps` for edits, `LiveUpdateRevalidating` while the connection is down, and `LiveUpdateError` for a failure, so the listener prints only after an edit. The client calls listeners one at a time on a separate goroutine, so the program waits on a channel before it closes the query. After a reconnection, the client subscribes again and replaces the rows with a fresh result. When a listener panics, the client recovers and passes the panic to the `OnError` handler as a `*sirannon.CallbackPanic`.

Live queries and table subscriptions need the WebSocket transport, which the client uses unless you set `Options.Transport` to `sirannon.TransportHTTP`. Over HTTP, both fail with `TRANSPORT_ERROR`.

## Handle what the server refuses

The client returns every failure as a `*sirannon.Error`, whose `Code`, `Message`, `Details`, and `Status` hold what the server sent. `errors.As` reaches all four fields, and `sirannon.ErrorCode(err)` returns the code alone. Delete the `data` folder and start the server again, then start the file with two refused calls at its end:

```go title="main.go"
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	sirannon "github.com/assetcorp/sirannon-db/packages/go"

	"example.com/orders/operations"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	if token == "" {
		return errors.New("set SIRANNON_TOKEN to the application credential")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	client, err := sirannon.New("http://127.0.0.1:9876", sirannon.Options{
		Headers: map[string]string{"Authorization": "Bearer " + token},
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}

	pending, err := sirannon.Query(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", pending)
	results, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 2750})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", results)
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)

	live, err := sirannon.Live(ctx, db, operations.OrdersOrdersByStatus, operations.OrdersOrdersByStatusArgs{Status: "pending"})
	if err != nil {
		return err
	}
	defer live.Close(ctx)
	fmt.Println("live", orderIDs(live.State().Rows))
	updated := make(chan struct{}, 1)
	stop := live.Subscribe(func(update sirannon.LiveUpdate[operations.OrdersOrdersByStatusRow]) {
		if update.Kind == sirannon.LiveUpdateOps {
			fmt.Println("live", orderIDs(update.State.Rows))
			select {
			case updated <- struct{}{}:
			default:
			}
		}
	})
	defer stop()
	if _, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 6400}); err != nil {
		return err
	}
	select {
	case <-updated:
	case <-ctx.Done():
		return ctx.Err()
	}

	_, err = db.Query(ctx, "SELECT id, total FROM orders", nil) // [!code ++:7]
	fmt.Println(err)
	_, err = db.On("orders").Subscribe(ctx, func(event sirannon.ChangeEvent) {})
	var refusal *sirannon.Error
	if errors.As(err, &refusal) {
		fmt.Println(refusal.Code, refusal.Status)
	}
	return nil
}

func orderIDs(rows []operations.OrdersOrdersByStatusRow) []any {
	ids := make([]any, 0, len(rows))
	for _, row := range rows {
		ids = append(ids, row.ID)
	}
	return ids
}
```

```text result
[{ID:1 Total:4999 Status:pending}]
[{Changes:1 LastInsertRowID:4} {Changes:1 LastInsertRowID:4}]
[{ID:1 Total:4999 Status:pending} {ID:3 Total:890 Status:shipped} {ID:4 Total:2750 Status:pending}]
live [1 4]
live [1 4 5]
SQL_NOT_ACCEPTED: This server does not accept SQL over the network. Call a registered operation by name, or start the server with acceptSql: true.
SQL_NOT_ACCEPTED 0
```

The client refuses the statement itself, because the server's capabilities leave out `query.sql`, so the client sends no request for it. The server refuses the table subscription, since a subscription to a whole table can deliver rows that no registered read returns. `Status` holds 0, because the server sends that refusal over WebSocket, where no HTTP answer holds a status.

A server that you start with `acceptSql: true`, or with an `onBeforeSubscribe` hook that authorises each table and filter, accepts a call such as `db.On("orders").Filter(map[string]any{"status": "pending"}).Subscribe(ctx, callback, sirannon.OnReset(reload))`. Such a subscription delivers each change once, in the order of the server's change log. While 1024 callbacks wait, the client pauses reading from the connection until they catch up. After a dropped connection, the client reconnects every `Options.ReconnectInterval` and resumes from the last change that it delivered. When the server holds no history after that change, the client calls the `OnReset` handler, so read the table again in that handler. [Subscription resumption](/docs/subscription-resumption) describes the cursor that the server keeps.

The `sirannon.Code` constants, such as `CodeConnectionError`, `CodeTimeout`, and `CodeTransportError`, hold the codes that the client returns when it fails before the server answers. [Error codes](/docs/error-codes) lists the codes that the server sends.

## Route calls across a replication group

`sirannon.NewTopology` returns a client that sends writes to the primary of a [replication group](/docs/distributed-replication) and sends reads to the node that `ReadPreference` selects. Save this complete `replicas/main.go` in the `go` folder, set `SIRANNON_PRIMARY_URL` and a comma-separated `SIRANNON_REPLICA_URLS` to the addresses of your nodes, and start it with `go run ./replicas`:

```go title="replicas/main.go"
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	sirannon "github.com/assetcorp/sirannon-db/packages/go"

	"example.com/orders/operations"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	token := os.Getenv("SIRANNON_TOKEN")
	primary := os.Getenv("SIRANNON_PRIMARY_URL")
	replicas := os.Getenv("SIRANNON_REPLICA_URLS")
	if token == "" || primary == "" || replicas == "" {
		return errors.New("set SIRANNON_TOKEN, SIRANNON_PRIMARY_URL, and SIRANNON_REPLICA_URLS")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	client, err := sirannon.NewTopology(sirannon.TopologyOptions{
		Options:        sirannon.Options{Headers: map[string]string{"Authorization": "Bearer " + token}},
		Primary:        primary,
		Replicas:       strings.Split(replicas, ","),
		ReadPreference: sirannon.ReadFromReplica,
	})
	if err != nil {
		return err
	}
	defer client.Close()
	db, err := client.Database("orders")
	if err != nil {
		return err
	}

	if _, err := sirannon.Execute(ctx, db, operations.OrdersPlaceOrder, operations.OrdersPlaceOrderArgs{Total: 1800}); err != nil {
		return err
	}
	mine, err := sirannon.Query(ctx, db, operations.OrdersMyOrders, sirannon.NoArgs{})
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", mine)
	return nil
}
```

This example needs a replication group, so it has no fixed result panel. The program prints the orders of `u_maria` from a replica, which can answer before it holds the new order.

`ReadPreference` takes `ReadFromPrimary`, `ReadFromReplica`, or `ReadFromNearest`, and with `ReadFromNearest` the client measures the latency of each node. With `Discovery: sirannon.DiscoveryCoordinator` and a list of `Endpoints`, the client fetches the group's routing from `GET /db/{id}/cluster` and sends calls to the new primary after a failover. When the client cannot reach the node for a read, it sets that node aside for five seconds and sends the read once more to another node. A write reaches the server twice only when your program sends it twice, because the client returns the error of a failed write without sending it again. [Topology-aware routing](/docs/topology-routing) describes the same routing for the TypeScript client.

## Call any route of the server

`*sirannon.Client` has a typed method for every route that Sirannon describes in `openapi.json`, such as `GetCapabilities`, `GetHealth`, and `GetBackupStatus`. Each method takes the route's path parameters and request body, and it returns a model of the route's response. The client has no device sync controller, so a Go program that syncs a device calls the device sync routes itself.

## Client options

`sirannon.New` takes the server's address and a `sirannon.Options`, whose unset fields take these defaults.

| Field | Default | Behaviour |
| --- | --- | --- |
| `Transport` | `TransportWebSocket` | The client also accepts `TransportHTTP`, which serves every call except live queries and subscriptions. |
| `Headers` | none | The client sends these headers with every HTTP request and WebSocket handshake. |
| `WebSocketProtocols` | none | The client offers these subprotocols after `sirannon.v1`. |
| `DisableAutoReconnect` | `false` | With `true`, the client leaves a dropped WebSocket connection closed. |
| `ReconnectInterval` | one second | The client waits this long before it reconnects a dropped WebSocket connection. |
| `RequestTimeout` | 30 seconds | The client waits this long for each call and handshake, and with `NoTimeout` it waits for as long as the context of the call allows. |
| `MaxResponseBytes` | 64 MiB | The client refuses a larger answer, and with `NoResponseLimit` it reads whatever the server sends. |
| `HTTPClient` | a client that follows no redirects | The client sends every HTTP request and WebSocket handshake through this `*http.Client`. |

`sirannon.TopologyOptions` embeds `Options` and adds `Endpoints`, `Primary`, `Replicas`, `ReadPreference`, `Discovery`, and `ReadConcern`. When the server closes a WebSocket connection with `4401` or `4403`, the client stops reconnecting and passes that error to the `OnError` handler, because the same credential fails every later try. The [Python client](/docs/python-client) offers the same calls and routing.
