Caching - Upstash Documentation

This page covers the cache option: what Cache-Control an object is served with, where to set it, and which value to pick. Every SDK takes the same values.

await bucket.put("avatars/7.png", file, { contentType: "image/png", cache: "immutable" })

bucket.put("avatars/7.png", file, content_type="image/png", cache="immutable")

bucket.Put(ctx, "avatars/7.png", file, &blob.PutOptions{
	ContentType: "image/png",
	Cache:       blob.CacheImmutable,
})

Cache-Control is written once, at upload, and stored with the object. The CDN and the browser honor it on every read. There is no per-request override; changing it means writing the object again.

Which value to pick

Object	Path	`cache`	How readers see a change
Unique path per upload (unique paths)	new each time	`'immutable'`	the path is new, nothing to invalidate
Stable path that changes rarely	stable	`'immutable'` plus the versioned URL	the URL changes with the etag
Fixed URL you do not control, or a client that drops query strings	stable	`'revalidate'`	a 304 check on every read
Private or sensitive	any	`'no-store'`, or a short duration	the link expires; see below

The `cache` option

Value	Stored header
`'immutable'`	`public, max-age=31536000, immutable`
`'revalidate'`	`public, max-age=0, must-revalidate`
`'no-store'`	`no-store`
a duration (`'15m'`, `3600`)	`public, max-age=<seconds>`
unset	`public, max-age=3600`
anything containing `=` or `,`	stored exactly as written

cache: "1h"      // public, max-age=3600
cache: 3600      // public, max-age=3600
cache: "15 min"  // public, max-age=900
cache: "7d"      // public, max-age=604800

cache="1h"                  # public, max-age=3600
cache=3600                  # public, max-age=3600
cache="15 min"              # public, max-age=900
cache="7d"                  # public, max-age=604800
cache=timedelta(minutes=5)  # public, max-age=300

Cache: "1h"     // public, max-age=3600
Cache: "3600"   // public, max-age=3600
Cache: "15 min" // public, max-age=900
Cache: "7d"     // public, max-age=604800
Cache: "1h30m"  // public, max-age=5400

A duration is converted to whole seconds, so '1500ms' stores max-age=1. The grammar is on Types.

The raw header

cache: "public, max-age=60, s-maxage=31536000"
cache: "max-age=0, stale-while-revalidate=86400"

cache="public, max-age=60, s-maxage=31536000"
cache="max-age=0, stale-while-revalidate=86400"

Cache: "public, max-age=60, s-maxage=31536000"
Cache: "max-age=0, stale-while-revalidate=86400"

Anything containing = or , is treated as a raw header and stored as written. Use this for s-maxage, stale-while-revalidate, no-transform and anything else the three keywords do not cover.

`revalidate` versus a short max-age

	`cache: 'revalidate'`	`cache: '60s'`
Unchanged object	304, no body	full object, once a minute
Object just overwritten	next read sees it	up to 60 s of the old bytes

'revalidate' stores public, max-age=0, must-revalidate. The cached copy is checked with If-None-Match on every read, so an unchanged object costs a 304 with no body. A short max-age serves stale bytes until it expires, then re-downloads the whole object. 'revalidate' costs a round trip per read, but is never stale and never downloads the bytes twice.

Where you can set it

Four places. The most specific one wins.

On the bucket

// lib/blob.ts
import { Bucket } from "@upstash/blob"

export const bucket = Bucket.fromEnv({ cache: "immutable" })

# app/blob.py
from upstash_blob import Bucket

bucket = Bucket.from_env(cache="immutable")

// blob.go
bucket, err := blob.NewBucketWith(blob.Options{
	Token: os.Getenv("UPSTASH_BLOB_TOKEN"),
	Cache: blob.CacheImmutable,
})

The default for every object this client stores. Client options: TypeScript, Python, Go.

On a put

await bucket.put("avatars/7.png", file, {
  contentType: "image/png",
  cache: "revalidate",
})

bucket.put("avatars/7.png", file, content_type="image/png", cache="revalidate")

bucket.Put(ctx, "avatars/7.png", file, &blob.PutOptions{
	ContentType: "image/png",
	Cache:       blob.CacheRevalidate,
})

The JSON update takes it too, for the object it rewrites. So do copy and move, for the destination. Without it the source’s value carries over.

On a signed upload URL

const upload = await bucket.signedUploadUrl("u/7/report.pdf", {
  contentType: "application/pdf",
  cache: "immutable",
})

await fetch(upload.url, { method: "PUT", headers: upload.headers, body })

upload = bucket.signed_upload_url("u/7/report.pdf", content_type="application/pdf", cache="immutable")

httpx.put(upload.url, headers=upload.headers, content=body)

up, err := bucket.SignedUploadURL(ctx, "u/7/report.pdf",
	&blob.SignedUploadURLOptions{
		ContentType: "application/pdf",
		Cache:       blob.CacheImmutable,
	})
// PUT to up.URL with every header in up.Headers

Signed into the URL and handed back in the returned headers, so the uploader has to send it verbatim.

On a direct browser upload

// lib/uploads.ts
import { uniquePath, uploadHandler } from "@upstash/blob"

export const uploads = uploadHandler({
  onBeforeUpload: ({ file }) => ({
    path: uniquePath(`uploads/${file.name}`),
    cache: "immutable",
  }),
})

# app/uploads.py
from upstash_blob import AsyncUploadHandler, BeforeUploadResult, unique_path

uploads = AsyncUploadHandler(
    on_before_upload=lambda args: BeforeUploadResult(
        path=unique_path(f"uploads/{args.file.name}"),
        cache="immutable",
    ),
)

// uploads.go
uploads, err := blob.NewUploadHandler(blob.UploadHandlerOptions[struct{}]{
	OnBeforeUpload: func(
		a blob.BeforeUploadArgs[struct{}],
	) (blob.BeforeUploadResult, error) {
		return blob.BeforeUploadResult{
			Path:  blob.UniquePath("uploads/" + a.File.Name),
			Cache: blob.CacheImmutable,
		}, nil
	},
})

Decided per upload in the before-upload callback on your server and signed into the presigned PUT. See Authorizing an upload.

Private buckets

`cache`	Public bucket	Private bucket
unset	`public, max-age=3600`	`private, max-age=3600`
`'1m'`	`public, max-age=60`	`private, max-age=60`
`'immutable'`	`public, max-age=31536000, immutable`	`private, max-age=31536000, immutable`
`'revalidate'`	`public, max-age=0, must-revalidate`	`private, max-age=0, must-revalidate`
`'no-store'`	`no-store`	`no-store`

On a private bucket, private replaces public, so no shared cache keeps a copy of an object only a signed request may read. This follows the bucket’s visibility in the console; nothing in the code declares it. A raw header string is passed through as written, visibility included: cache: 'public, max-age=60' on a private bucket stores public, max-age=60.

Immutable plus a versioned URL

// app/api/avatar/route.ts
const blob = await bucket.put(`avatars/${user.id}.png`, file, {
  contentType: "image/png",
  cache: "immutable",
})

await db.users.update(user.id, { avatar: blob.versionedUrl })

# app/main.py
blob = bucket.put(f"avatars/{user.id}.png", file, content_type="image/png", cache="immutable")

db.users.update(user.id, avatar=blob.versioned_url)

// avatar.go
b, err := bucket.Put(ctx, "avatars/"+user.ID+".png", file, &blob.PutOptions{
	ContentType: "image/png",
	Cache:       blob.CacheImmutable,
})
if err != nil {
	return err
}

db.UpdateUserAvatar(ctx, user.ID, b.VersionedURL)

<img src={user.avatar} />

The versioned URL is the URL with the etag on the query, so it changes whenever the content does. A stable path stored immutable and served through the versioned URL is cached for a year, and every overwrite produces a URL no cache has seen. The path never moves, so nothing has to be deleted. A private bucket has neither URL.

`no-store` and signed reads

await bucket.put("private/report.pdf", body, {
  contentType: "application/pdf",
  cache: "no-store",
})

const { url, expiresAt } = await bucket.signedReadUrl("private/report.pdf")

bucket.put("private/report.pdf", body, content_type="application/pdf", cache="no-store")

link = bucket.signed_read_url("private/report.pdf")

bucket.Put(ctx, "private/report.pdf", body, &blob.PutOptions{
	ContentType: "application/pdf",
	Cache:       blob.CacheNoStore,
})

link, err := bucket.SignedReadURL(ctx, "private/report.pdf", nil)

These are two separate mechanisms. The link expires at its returned expiry, but the stored Cache-Control outlives it: with a long max-age the reader’s browser keeps the bytes after the link stops working. If a reader must not keep the bytes, store the object with no-store. no-store drops the visibility scope entirely and stores no-store on public and private buckets alike. See Signed read URLs for link lifetimes.

What the upload route itself caches

An upload route’s GET serves its constraints document with a 60 second Cache-Control of its own, unrelated to the objects the route stores. See Constraints.

​Which value to pick

​The cache option

​The raw header

​revalidate versus a short max-age

​Where you can set it

​On the bucket

​On a put

​On a signed upload URL

​On a direct browser upload

​Private buckets

​Immutable plus a versioned URL

​no-store and signed reads

​What the upload route itself caches