Connecting

This page covers creating the bucket client from its token, how it retries, what it sends as telemetry, and reaching storage through an S3 client.

import { Bucket } from "@upstash/blob"export const bucket = Bucket.fromEnv() // reads UPSTASH_BLOB_TOKEN

from upstash_blob import Bucketbucket = Bucket.from_env()  # reads UPSTASH_BLOB_TOKEN

import blob "github.com/upstash/blob-go"bucket, err := blob.NewBucketFromEnv() // reads UPSTASH_BLOB_TOKEN

Client options and their types: TypeScript, Python, Go.

Create a bucket in the Upstash Console and put its token in your environment:

UPSTASH_BLOB_TOKEN=...

Every SDK reads UPSTASH_BLOB_TOKEN by default and also takes a token directly, for a token under another variable or a platform without environment variables, such as Cloudflare Workers.

The token is a bearer secret. Anything holding it can read and write the whole bucket. Keep it server side, never in NEXT_PUBLIC_, VITE_, or any other variable your bundler inlines into client code.

Options#

Constructing a client per request is fine. Credentials are cached per token, so two clients built from the same token share one.

Public or private#

Whether the bucket is public or private is a console setting, not an option: the SDK learns it from the backend on the first request. See Private buckets.

Retries#

new Bucket({ token, retry: false }) // every request oncenew Bucket({ token, retry: { retries: 5, backoff: (n) => n * 500 } })

Bucket(token, retry=False)  # every request onceBucket(token, retry={"retries": 5, "backoff": lambda n: n * 500})

// 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		},	},})

A request that fails with a 5xx, a 429 or a dropped connection is sent again if it can be: reads, deletes, copies, multipart parts and signing calls. A put that goes up as one PUT with a streamed body is sent once, since a stream cannot be read twice. In TypeScript every body is streamed; in Python a body held in memory is retried: bytes, a str, or one buffered under max_size. In Go a body that can be read again is retried: a *bytes.Reader, a *strings.Reader, a regular file, or one buffered under MaxSize; see Bodies. The POSTs that create and complete a multipart upload and a batch delete are sent once. When the credential service asks the SDK to wait, it waits up to 10 seconds and asks again, three times.

Clients built from the same token share one credential cache, so a credential fetch already in progress keeps the retry setting of the client that started it. An expired temporary credential is not a failure: the SDK fetches a new one and sends the request once more, even with retries off, unless its body was a stream. Browser uploads retry on their own budget; see Retries.

Telemetry#

The SDK sends its version, runtime and platform as headers on credential and signing requests to Upstash. Turn it off with UPSTASH_DISABLE_TELEMETRY in the environment, set to anything but an empty string, false, 0, no or off, or with the telemetry option on the client.

Using an S3 client#

import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3"const { endpoint, region, bucket: name, credentials } = bucket.s3()const s3 = new S3Client({ endpoint, region, credentials })await s3.send(  new GetObjectCommand({ Bucket: name, Key: "reports/q3.pdf", Range: "bytes=0-1023" }),)

import boto3cfg = bucket.s3()s3 = boto3.client("s3", **cfg.client_kwargs())s3.get_object(Bucket=cfg.bucket, Key="reports/q3.pdf", Range="bytes=0-1023")

cfg, err := bucket.S3(ctx)if err != nil {	return err}client := s3.New(s3.Options{	Region:       cfg.Region,	BaseEndpoint: aws.String(cfg.Endpoint),	Credentials:  credentials, // refreshed from bucket.S3, see the Go SDK page})client.GetObject(ctx, &s3.GetObjectInput{	Bucket: aws.String(cfg.Bucket),	Key:    aws.String("reports/q3.pdf"),	Range:  aws.String("bytes=0-1023"),})

Buckets are backed by Cloudflare R2 and are S3-compatible. The client’s s3() returns a config for an S3 client, for anything the SDK does not wrap: byte ranges, conditional GETs, delimiters and common prefixes, object tagging. The credentials in it are short-lived; see Minting temporary credentials.

Wiring it into an S3 client: TypeScript, Python, Go.

Next steps#