Websites · Glossary
What is a storage bucket?
A storage bucket is a named container for files in an object storage service such as Amazon S3 or Supabase Storage. Files, called objects, are stored by key rather than in a real folder tree, and the bucket carries settings that apply to everything inside: who may read or upload, the largest file allowed and which file types are accepted.
Websites keep photos, documents and uploads in buckets rather than in the database. Whether a bucket is public or private decides whether anyone with a link can open a file.
Indunil Asanka · Co-founder
4 min read · Published
| Question | Public bucket | Private bucket |
|---|---|---|
| Who can download a file | Anyone with its URL | Only requests allowed by the access rules, or holders of a signed link |
| Who can upload | Only those allowed by the access rules | Only those allowed by the access rules |
| Good for | Logos, product photos, blog images | Contracts, invoices, ID documents, client files |
| Risk if misused | Private files exposed to anyone who finds the link | Public images fail to load if rules are too strict |
What it is
Object storage keeps each file as an object with a key, such as products/mug-blue.jpg, its bytes and some metadata. A bucket groups objects and holds the settings that apply to them. Keys can contain slashes, so dashboards show folders, but there is no real directory structure underneath. Amazon S3 introduced the model and most storage services, including Supabase Storage, follow it. Buckets are cheap and scale to very large numbers of files, which is why sites store media there and keep only the file's key in the database.
How access works
A public bucket serves files to anyone who has the URL, which suits images shown on public pages. A private bucket refuses downloads unless the request is allowed. In Supabase, buckets are private by default and every operation on a private bucket goes through row level security policies on the storage objects table, so a rule can say a client may download only files under their own folder. Upload limits, such as maximum file size and allowed content types, are also set per bucket. A signed URL, valid for a set time, lets a private file be shared without making the bucket public.
When it matters
Whenever a site stores files people upload or files that belong to one customer: CVs on a careers page, drawings in a client portal, receipts, waivers, photos for a quote. Getting the bucket type wrong is one of the most common data leaks on the web, because a public bucket full of documents can be listed or guessed. It also matters for cost and speed, since large images in a public bucket are served on every page view.
Common mistakes
Putting private documents in a public bucket because the images were there already. Guessable keys such as invoice-1, invoice-2 in a public bucket. No size limit, so someone uploads a gigabyte video into a form. No file type check, so an HTML file is uploaded and served from the site's domain. Signed links that last for months. Forgetting to delete files when the database row that pointed to them is deleted. And policies that let any signed in person read every other person's uploads.
Where it shows up in OneCraft
A OneCraft site with a database has two buckets on its project: site-files, which is public with a 10 MB limit per file, and site-private, read only through the site's own access rule, with a 25 MB limit per file. Both live in the site's own Supabase schema or project, with row level security on every table the agent creates. Hosted schemas are available on every plan, or owners can connect their own Supabase account.
Questions people ask
Is a storage bucket the same as a folder?
Not quite. A bucket is a top level container with its own settings, and the folders you see inside it are only prefixes in object keys. You cannot set different access rules on a folder in the way you can on a bucket, unless the service's policies match on the key prefix, as Supabase's can.
Should images go in the database or a bucket?
In a bucket. Databases are built for rows of structured data, and storing large files in them slows queries, bloats backups and costs more. Store the file in a bucket and keep its key, size and owner in a database row that points to it.
What is a signed URL?
A link to a private file that includes a signature and an expiry time. Anyone holding it can download the file until it expires, without signing in. Signed URLs suit emailing a document or showing a private image briefly. Keep expiry short and never put signed URLs on public pages.
How do I make a bucket private again?
Change the bucket's setting to private, then check every page that showed its files, because public URLs will stop working. Files already downloaded or cached by others cannot be recalled, so review what was exposed and rotate anything sensitive, such as documents with account numbers.
How much does bucket storage cost?
Object storage is usually charged per gigabyte stored per month plus data transferred out, and plans often include an allowance. Small business sites rarely exceed a few gigabytes. Large videos and unoptimised photos are what push storage and bandwidth bills up, so resize images before uploading.
Make one with websites
The button opens the generator with this use case already described. Change the wording to match your own.
Create a website with OneCraftRelated questions
- What is a Postgres schema?What is a Postgres schema? A named namespace of tables, views and functions inside one database, how search_path finds them, and how schemas separate tenants.
- What is seed data?What is seed data? Rows inserted into a new database so it has something to show and test: seed data compared with fixtures, reference and production data.
- What is row level security?What is row level security? Database policies that decide which rows each signed in person can read or change, with common policy shapes and how to test them.
- What is Stripe Checkout?What is Stripe Checkout? Stripe's prebuilt payment page created per purchase, how a Checkout Session works, and how it compares with Payment Links.
Written and checked by the OneCraft team. Last checked .