Buckets

Files live in buckets, which are either public or private and can limit file size and type.

#Create a bucket

Create buckets in Studio under Storage, or with the service_role key:

await admin.storage.createBucket('avatars', {
  public: true,
  fileSizeLimit: '2MB',                 // at most your plan's upload size
  allowedMimeTypes: ['image/png', 'image/jpeg', 'image/*'],
})

Bucket names are 2 to 100 characters: lower-case letters, digits, -, _ and ..

#Public and private

Files in a public bucket can be downloaded by anyone with the URL. Files in a private bucket require a policy that allows the request, or a signed URL. Uploads always need a policy, in both kinds of bucket.

#Caching of public files

Files in public buckets (/storage/v1/object/public/…) are cached on the servers that answer your project, including read replica servers in other regions, so repeat downloads come from close to the user. A cached copy is kept as long as the file's cache time allows: one hour unless you set cacheControl (in seconds) when you upload. After that it is checked against the original and refreshed if it changed. The X-Cache response header shows HIT or MISS.

await stitchdb.storage.from('avatars').upload('u1.png', file, { cacheControl: '86400' }) // cache for a day
await stitchdb.storage.from('avatars').upload('u1.png', file, { cacheControl: '60', upsert: true }) // changes show within a minute

When you replace a public file, users can see the old copy until its cache time runs out. For files you change often, use a short cache time or a new file name (for example with a version in it). Files of 100 MB or more, partial downloads (Range requests) and private or signed URLs are not cached.

#Manage buckets

const { data: buckets } = await admin.storage.listBuckets()
await admin.storage.updateBucket('avatars', { public: false })
await admin.storage.emptyBucket('avatars')   // delete all files
await admin.storage.deleteBucket('avatars')  // must be empty