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.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.66go 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.tsexport { 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.gonpx 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), withjsontags 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 withjazz.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,UpdateandDelete. Writes and reads take ajazz.Querier: the*jazz.DB, or a*jazz.Txinsidedb.Tx(ctx, func(tx *jazz.Tx) error { … }). Adb.Txis mergeable, as TypeScript'sdb.transaction; passjazz.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.gofunc 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 withcreateJazz; - 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 generaterefuses Go bindings for an app that declares them; - non-finite doubles (
NaN,±Inf): Jazz carries them asnull, so a nullablefloatcolumn reads them asnil, and reading a non-nullable one fails with a*jazz.Errorthat names the column.