Go SDK

github.com/upstash/blob-go is the Go SDK. It has a Bucket client for server-side reads and writes, and an upload handler that serves the browser client, so a React app can upload straight to storage through a Go backend.

This section is the Go reference: names, types, and net/http wiring. What each call does, its defaults and its limits are on the concept pages it links to.

Install#

go get github.com/upstash/blob-go

It needs Go 1.22 or later and uses only the standard library.

import blob "github.com/upstash/blob-go"

The package name is blob. The examples import it under that name explicitly, since the module path ends in blob-go.

There is no Go browser client. The browser runs @upstash/blob/react or @upstash/blob/browser, which speak the same protocol to a Go handler as to a TypeScript one; see With a server in another language.

The Bucket client#

bucket, err := blob.NewBucketFromEnv() // reads UPSTASH_BLOB_TOKENif err != nil {	log.Fatal(err)}

NewBucketFromEnv() returns an error when UPSTASH_BLOB_TOKEN is unset or empty. NewBucket(token) takes the token directly. NewBucketWith takes every option:

bucket, err := blob.NewBucketWith(blob.Options{	Token:            os.Getenv("REPORTS_BUCKET_TOKEN"),	Cache:            blob.CacheImmutable,	DisableTelemetry: true,	Retry:            blob.RetryConfig{Retries: 5},	HTTPClient:       &http.Client{Transport: proxyTransport},})

A missing or malformed token, an unparseable Cache and a negative retry count are returned as an error from the constructor, not on the first request.

There is no visibility option. Whether the bucket is public or private is a console setting; see Connecting.

A *Bucket is safe for concurrent use. Build one at startup and share it, or build one per request: buckets on the same token share one credential cache.

Contexts#

Every method that makes a request takes a context.Context first. Canceling it, or a deadline passing, stops the request and any retry wait, and the method returns the context’s error. In a handler, pass r.Context().

A multipart upload that fails or is canceled aborts itself on its way out, on a context of its own, so the parts already sent are not left behind.

Retries#

// every request onceblob.NewBucketWith(blob.Options{	Token: token,	Retry: blob.RetryConfig{Disabled: true},})blob.NewBucketWith(blob.Options{	Token: token,	Retry: blob.RetryConfig{		Retries: 5,		Backoff: func(n int) time.Duration {			return time.Duration(n) * 500 * time.Millisecond		},	},})

Which requests are retried, and the default budget and backoff, are on Retries. In Go, a body Put can read again is retried; see Bodies.

Using an S3 client#

import (	"github.com/aws/aws-sdk-go-v2/aws"	"github.com/aws/aws-sdk-go-v2/service/s3")refresh := func(ctx context.Context) (aws.Credentials, error) {	c, err := bucket.S3(ctx)	if err != nil {		return aws.Credentials{}, err	}	return aws.Credentials{		AccessKeyID:     c.AccessKeyID,		SecretAccessKey: c.SecretAccessKey,		SessionToken:    c.SessionToken,		CanExpire:       true,		Expires:         c.Expires,	}, nil}cfg, err := bucket.S3(ctx)if err != nil {	return err}client := s3.New(s3.Options{	Region:       cfg.Region,	BaseEndpoint: aws.String(cfg.Endpoint),	Credentials:  aws.NewCredentialsCache(aws.CredentialsProviderFunc(refresh)),})out, err := client.GetObject(ctx, &s3.GetObjectInput{	Bucket: aws.String(cfg.Bucket),	Key:    aws.String("reports/q3.pdf"),	Range:  aws.String("bytes=0-1023"),})

bucket.S3(ctx) returns an *S3Credentials with Endpoint, Region, Bucket, a short-lived credential and its Expires. The SDK does not depend on the AWS SDK; bring your own. The credential stops working at Expires, so hand the AWS SDK a provider that calls bucket.S3 again, as above, rather than a static one.

What an S3 client is for, and why it must not presign, is on Using an S3 client.

Option types#

KB, MB, GB and TB are powers of 1,000, and KiB, MiB, GiB and TiB powers of 1,024. 32 * blob.MB refuses a 32 MiB file.

bucket.SignedReadURL(ctx, "reports/q3.pdf", &blob.SignedReadURLOptions{	ExpiresIn: 2 * time.Minute,})// Cache-Control: public, max-age=604800bucket.Put(ctx, "avatars/7.png", file, &blob.PutOptions{Cache: "7d"})bucket.Put(ctx, "export.csv", rows, &blob.PutOptions{MaxSize: 10 * blob.MiB})

A size read from configuration goes through blob.ParseSize("32MiB"), which takes the same strings as the other SDKs and returns invalid_input for one that does not parse. blob.FormatBytes(2_400_000) is "2.4 MB", the same text the browser client shows.

The zero value of every option means unset: no limit, the default lifetime, the bucket’s cache. A negative size or lifetime on a Bucket call is refused with invalid_input, and a negative MaxSize on an upload handler or route is an error from NewUploadHandler. Two negatives have a meaning: a route’s MaxSize: blob.NoLimit clears the handler’s limit, and MultipartOver treats a negative threshold as 0.

Next steps#