Supabase Storage

Why First

Your platform needs to handle files. Partners uploading their Aadhaar card for KYC verification. Customers setting a profile photo. Service categories displaying images in the app.

Where do these files go?

Not in the database. A database column stores a number, a date, a piece of text — it is designed for structured data. If you put an image file into a database column, you are storing megabytes of binary data in a system built for kilobytes of structured values. It works, technically. It is slow, expensive, and the wrong tool.

Files live in a file system. Supabase Storage is that file system — managed, versioned, secure, and integrated with the same auth system your database uses. It gives each file a URL. It enforces who can read or upload each file. It scales automatically.

Excel analogy: Think of SharePoint or a network drive that has folders with different access levels. The Public folder is visible to everyone. The Confidential folder requires you to log in first. The HR Documents folder requires you to have the HR role. Supabase Storage works exactly like this — but for your app's files, controlled by the same login your users already have.

---

Navigating to Storage

In your Supabase dashboard:

1. Click Storage in the left sidebar (the folder icon)
2. You see the Buckets list — currently empty for a new project

---

Storage — the buckets list. The "New bucket" button is highlighted in the top right.

---

Creating a Bucket

A bucket is a named container for a category of files. Think of it as a top-level folder.

1. Click New bucket
2. Enter a bucket name — use lowercase letters and hyphens, no spaces (e.g., profile-photos, kyc-documents, service-images)
3. Choose Public or Private:

Public vs Private Buckets

4. Click Save

---

File Path Structure

When you upload a file to a bucket, it lives at a path — like a folder structure inside the bucket. Best practice:

Examples:

• profile-photos/abc123-user-id/avatar.jpg
• kyc-documents/abc123-user-id/aadhaar-front.jpg
• service-images/cleaning/hero.jpg

Using the user's ID as a folder name means you can write Storage policies that say "a user can only read/write files inside their own folder" — exactly like RLS for files.

---

Uploading Files via the Dashboard

For development and testing, you can upload files directly in the Supabase dashboard:

1. Click into a bucket
2. Click Upload files or drag and drop files onto the page
3. Files appear in the file list with their path, size, and last modified time
4. Click a file → Copy URL to get the file URL (public buckets give a permanent URL; private buckets generate a signed URL)
5. Click Delete to remove a file permanently

In production, your app uploads files programmatically from the React frontend — covered in the Backend module.

---

Storage Policies (Access Control for Files)

Just like tables have RLS policies, buckets have Storage policies. They control who can upload, download, update, and delete files.

Storage policies — separate sections for SELECT (read), INSERT (upload), UPDATE, DELETE.

To set policies:

1. In Storage, click your bucket name
2. Click Policies tab
3. You see separate sections for SELECT (read/download), INSERT (upload), UPDATE, and DELETE

The most useful patterns:

Allow users to read their own files: storage.foldername(name) extracts the folder components from the file path. [1] gets the first component — the user ID folder. This checks that it matches the logged-in user.

Allow users to upload to their own folder:

Allow public read for a public bucket:

---

Getting File URLs in Code

You will use these two patterns constantly in your React app:

Public bucket — permanent URL:

Private bucket — signed URL (expires after set time):

---

Standard Bucket Setup for EduTrack

Create all four buckets before starting the KYC or profile flows. Changing a bucket from public to private after files are uploaded requires migrating all existing URLs — avoid that by deciding the access level upfront.