Go

Use Jazz from a Go app: sign in as an end user and sync through your main backend, with typed bindings generated from your app's schema.

Experimental

For apps: run your backend in TypeScript. A Go program is a client of your app, like a browser or a mobile app: it signs in as one of your users and syncs through your main backend's /jazz, the route createJazz serves. Like every other language, it works from your app's TypeScript schema and permissions: npx jazz-tools generate writes its typed bindings from them.

The Go module, github.com/garden-co/jazz/packages/jazz-go/v2, needs no cgo; its only dependency is purego. It uses context for every call and channels for subscriptions.

Install

Add the module. Its versions are Jazz's: each release tags it as packages/jazz-go/v<version>, so its path ends in /v2:

go get github.com/garden-co/jazz/packages/jazz-go/v2@v2.0.0-alpha.66
go build ./...

Generate the bindings

Author your app's schema and permissions in TypeScript, in a schema.ts beside your go.mod (which requires jazz-go/v2). If your app's TypeScript side already has one, re-export it:

schema.ts
export { schema, permissions } from "../web/schema";

Then run npx jazz-tools generate there. It writes jazz.app.json, jazz.permissions.json and the jazzapp package, jazzapp/jazz_app.go:

npx jazz-tools generate # writes jazz.app.json, jazz.permissions.json, jazzapp/jazz_app.go
npx jazz-tools generate --check # in CI: fails if any of them is stale

Run it with npx: the standalone jazz-tools binary refuses to write beside a schema.ts, though its generate --check still works. Commit the generated files, and import the bindings as <your module>/jazzapp. Per table they give you:

  • a row struct (Task), with json tags of the column names. Nullable columns are pointers;
  • NewTask, the row to insert. Nullable and defaulted columns are pointers you may leave nil;
  • TaskPatch, whose fields change a column only when you set them with jazz.Set(…);
  • a string type with constants for each enum column (TaskStatus, TaskStatusTodo, …);
  • the table's relations as optional fields of the row (Task.Show *Show), filled when a query includes them: q.Include(jazzapp.Tasks.Show);
  • a table value (jazzapp.Tasks) with typed columns (jazzapp.Tasks.Status.Eq(…)), relations, Query(), Insert, Update and Delete. Writes and reads take a jazz.Querier: the *jazz.DB, or a *jazz.Tx inside db.Tx(ctx, func(tx *jazz.Tx) error { … }). A db.Tx is mergeable, as TypeScript's db.transaction; pass jazz.Serializable() for a serializable transaction.

If your app declares computed fields or transforms, the bindings also declare a jazzapp.Computed interface. jazzapp.Open(ctx, cfg, computed) takes your implementation, so a missing method is a compile error.

A mergeable text column (merge: "text", "markdown" or "html") gets an edit method. For the text page's notes.body, that's jazzapp.Notes.EditBody(ctx, db, id, jazz.Splice(pos, deleteLen, insert)). Its positions are UTF-8 byte offsets, as Go indexes a string (strings.Index, slicing), where TypeScript counts UTF-16 code units. An offset inside a character is refused, not rounded, and so is a jazz.Range of a text column that would split one.

Open the app as an end user

Sign in with a token from your auth provider. Jazz asks your function for a fresh one whenever it needs it:

main.go
func openAsUser(ctx context.Context, appID, serverURL, dataDir string, token jazz.TokenProvider) (*jazz.DB, error) {
// Sign in through your main backend's /jazz with a token from your auth
// provider; rows stay in dataDir and sync through it.
return jazzapp.Open(ctx, jazz.Config{
AppID: appID,
ServerURL: serverURL,
Storage: jazz.StoragePersistent,
DataDir: dataDir,
Auth: jazz.Token(token),
})
}

Or use a local-first account kept on this device, created on first open:

db, err := jazzapp.Open(ctx, jazz.Config{
AppID: appID,
ServerURL: "https://my-app.com/jazz",
Storage: jazz.StoragePersistent,
DataDir: "./jazz-data",
Auth: jazz.DeviceAccount(jazz.FileStore("./jazz-data/device-key")),
})

Keep a device key like a password: jazz.FileStore keeps it in a file only its owner can read; implement jazz.SecretStore to keep it in the OS keychain. db.Session(ctx) is who is signed in, db.OnSession(ctx) and db.OnSyncStatus(ctx) are channels of their changes, and db.Refresh(ctx) and db.SignOut(ctx) do what they say.

Writes are local-first: a write your permissions refuse returns no error. It is never synced, and other users never see it.

Errors match their kind with errors.Is: jazz.ErrPermission, jazz.ErrRefused, jazz.ErrNotSupported, jazz.ErrConflict, jazz.ErrIO and jazz.ErrClosed. Use errors.As with a *jazz.Error for the details.

A *jazz.DB is safe for concurrent use. Every call takes a context.Context. A cancelled context returns at once, but the call still runs to its end, so a write may still apply. Before the process exits, call db.Close().

The Reading and Writing pages have a Go tab for each example. examples/stage-plan/apps/go-cli in the repository is a complete StagePlan command-line app.

A Go service can also connect to your main backend as a backend client, with a machine credential (trusted, acting for users with ForUser, or scoped): see Backend Client.

Not supported yet

  • running your main backend in Go (publishing permissions, serving /jazz): run it in TypeScript with createJazz;
  • guest (anonymous) users: a Go app signs in with your app's own sign-in (jazz.Token) or a device account (jazz.DeviceAccount), and has no guest mode;
  • nested rows, catalogue enums and transaction-id columns: npx jazz-tools generate refuses Go bindings for an app that declares them;
  • non-finite doubles (NaN, ±Inf): Jazz carries them as null, so a nullable float column reads them as nil, and reading a non-nullable one fails with a *jazz.Error that names the column.