turso-api-client-go

Go client for the Turso Cloud HTTP API (organizations, members, groups, databases, API tokens, locations). It mirrors the behavior of the official TypeScript package @tursodatabase/api.

Requirements: Go 1.23+ (see go.mod).

Install

go get github.com/invertase/turso-api-client-go

Quick start

All RPC-style methods take a context.Context as the first argument. Construct a client with your organization slug and an API token:

package main

import (
	"context"
	"log"
	"os"

	"github.com/invertase/turso-api-client-go"
)

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

	client, err := turso.NewClient(turso.Config{
		Org:   "your-org-slug",
		Token: os.Getenv("TURSO_TOKEN"),
	})
	if err != nil {
		log.Fatal(err)
	}

	orgs, err := client.Organizations.List(ctx)
	if err != nil {
		log.Fatal(err)
	}
	_ = orgs // use organizations
}

turso.CreateClient is the same as turso.NewClient; use whichever name you prefer.

Configuration

Field	Meaning
Org	Organization or personal account slug (used in API paths).
Token	Bearer token (required; must not be empty).
BaseURL	Optional API base; default is https://api.turso.tech/v1/.
HTTPClient	Optional *http.Client (timeouts, tests, custom transport).

Errors

API error responses shaped like {"error":"..."} are returned as *turso.ClientError with Message and Status (HTTP status code). Use errors.As to inspect them.

Usage examples

The snippets below assume ctx and client are already set up as in the quick start.

Organizations

_, err := client.Organizations.List(ctx)

_, err = client.Organizations.Update(ctx, turso.OrganizationUpdateOptions{Overages: true})

err = client.Organizations.Delete(ctx)

members, err := client.Organizations.Members(ctx)

_, err = client.Organizations.AddMember(ctx, "username", string(turso.OrgRoleAdmin))
_, err = client.Organizations.AddMember(ctx, "username", "") // default role: member

_, err = client.Organizations.RemoveMember(ctx, "username")

invites, err := client.Organizations.ListInvites(ctx)

invite, err := client.Organizations.InviteUser(ctx, "you@example.com", string(turso.OrgRoleAdmin))

err = client.Organizations.DeleteInvite(ctx, "you@example.com")

invoices, err := client.Organizations.Invoices(ctx)

Locations

locations, err := client.Locations.List(ctx)

closest, err := client.Locations.Closest(ctx) // GET https://region.turso.io/ (no API auth)

Groups

groups, err := client.Groups.List(ctx)

group, err := client.Groups.Get(ctx, "default")

group, err = client.Groups.Create(ctx, "customgroup", "lhr", nil)

group, err = client.Groups.Create(ctx, "customgroup", "lhr", &turso.GroupCreateOptions{
	Extensions: []turso.ExtensionType{turso.ExtensionVector, turso.ExtensionMath},
})

group, err = client.Groups.Delete(ctx, "customgroup")

token, err := client.Groups.CreateToken(ctx, "default", nil)

token, err = client.Groups.CreateToken(ctx, "default", &turso.GroupCreateTokenOptions{
	Expiration:    "1w2d6h3m",
	Authorization: "full-access",
})

token, err = client.Groups.CreateToken(ctx, "default", &turso.GroupCreateTokenOptions{
	Permissions: &struct {
		ReadAttach struct {
			Databases []string `json:"databases"`
		} `json:"read_attach"`
	}{
		ReadAttach: struct {
			Databases []string `json:"databases"`
		}{Databases: []string{"db1", "db2"}},
	},
})

err = client.Groups.RotateTokens(ctx, "default")

Deprecated replica helpers from the TS client are also available: AddLocation, RemoveLocation.

API tokens (auth)

tokens, err := client.ApiTokens.List(ctx)

withJWT, err := client.ApiTokens.Create(ctx, "superdupertokenname")

revoked, err := client.ApiTokens.Revoke(ctx, "superdupertokenname")

validation, err := client.ApiTokens.Validate(ctx, "jwt-to-check")

Databases

Optional list filters use pointers so omitted query parameters match the TypeScript client:

dbs, err := client.Databases.List(ctx, nil)

group := "group-name"
dbs, err = client.Databases.List(ctx, &turso.DatabaseListOptions{Group: &group})

db, err := client.Databases.Get(ctx, "my-db")

created, err := client.Databases.Create(ctx, "db-name", nil)

created, err = client.Databases.Create(ctx, "db-name", &turso.DatabaseCreateOptions{
	Group: &group,
})

created, err = client.Databases.Create(ctx, "db-name", &turso.DatabaseCreateOptions{
	Group: &group,
	Seed: &turso.DatabaseSeedOption{
		Type: turso.DatabaseSeedTypeDatabase,
		Name: "my-existing-db",
	},
})

created, err = client.Databases.Create(ctx, "db-name", &turso.DatabaseCreateOptions{
	Seed: &turso.DatabaseSeedOption{
		Type:      turso.DatabaseSeedTypeDatabase,
		Name:      "my-existing-db",
		Timestamp: time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC),
	},
})

isSchema := true
created, err = client.Databases.Create(ctx, "parent-db", &turso.DatabaseCreateOptions{IsSchema: &isSchema})

parent := "parent-db"
created, err = client.Databases.Create(ctx, "child-db", &turso.DatabaseCreateOptions{Schema: &parent})

err = client.Databases.UpdateVersion(ctx, "my-db")

deleted, err := client.Databases.Delete(ctx, "my-db")

instances, err := client.Databases.ListInstances(ctx, "my-db")

inst, err := client.Databases.GetInstance(ctx, "my-db", "ams")

dbToken, err := client.Databases.CreateToken(ctx, "my-db", nil)

dbToken, err = client.Databases.CreateToken(ctx, "my-db", &turso.DatabaseCreateTokenOptions{
	Expiration:    "1w2d6h3n",
	Authorization: "full-access",
})

err = client.Databases.RotateTokens(ctx, "my-db")

usage, err := client.Databases.Usage(ctx, "my-db", nil)

usage, err = client.Databases.Usage(ctx, "my-db", &turso.DatabaseUsageOptions{
	From: time.Date(2023, 1, 1, 0, 0, 0, 0, time.UTC),
	To:   time.Date(2023, 2, 1, 0, 0, 0, 0, time.UTC),
})

usage, err = client.Databases.Usage(ctx, "my-db", &turso.DatabaseUsageOptions{
	From: "2023-01-01T00:00:00Z",
	To:   "2023-02-01T00:00:00Z",
})

Add "time" to your imports when using time.Date or Usage date bounds.

Development

From the repo root:

go test ./...

CI (GitHub Actions) runs on pushes and pull requests to main / master: gofmt, go mod verify, go vet, and go test -race ./... (.github/workflows/ci.yml).

Releases (Go modules are git tags)

There is no npm-style publish. Go resolves versions from your upstream Git tags (vMAJOR.MINOR.PATCH). After you push a tag, users run go get with it and pkg.go.dev will index that version shortly after someone fetches it.

Manual (local):

git tag -a v0.1.0 -m 'Release v0.1.0'
git push origin v0.1.0

Or GitHub: create a Release in the repo UI by choosing/creating tag v0.1.0 (still just a Git tag underneath).

Or CI: Actions → Release workflow → Run workflow → enter 0.1.0 or v0.1.0. It runs the same checks as CI, then creates an annotated tag, pushes it, and opens a GitHub Release with install notes (.github/workflows/release.yml).

go get github.com/invertase/turso-api-client-go@v0.1.0

Related

• TypeScript reference client: turso-api-client-ts/
• Turso docs: https://docs.turso.tech/