Creating storage buckets in Supabase - Mechanics & Internals

Overview - Creating storage buckets

What is it?

Creating storage buckets means making special containers in the cloud where you can keep files like photos, documents, or videos. These buckets help organize and protect your files so you can find and use them easily. In Supabase, storage buckets are part of a service that lets you save and manage files securely online. You can create buckets to separate different types of files or projects.

Why it matters

Without storage buckets, managing many files in the cloud would be messy and unsafe. Imagine trying to find a photo in a huge pile without folders. Buckets solve this by grouping files logically and controlling who can see or change them. This makes apps faster, safer, and easier to build. Without buckets, developers would struggle to keep user data organized and protected.

Where it fits

Before learning to create storage buckets, you should understand basic cloud storage concepts and how Supabase works as a backend service. After mastering bucket creation, you can learn about file uploading, access controls, and integrating storage with your app's database and authentication.

Mental Model

Core Idea

A storage bucket is like a labeled box in the cloud where you safely keep and organize your files.

Think of it like...

Think of a storage bucket as a filing cabinet drawer labeled for a specific type of document. You put related papers inside so you can find them quickly and keep them safe from others who shouldn't see them.

┌───────────────────────────┐
│       Storage Bucket       │
│  ┌───────────────┐        │
│  │ File 1        │        │
│  │ File 2        │        │
│  │ ...           │        │
│  └───────────────┘        │
└───────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is a storage bucket?

Concept: Introducing the basic idea of a storage bucket as a container for files in the cloud.

A storage bucket is a place in the cloud where you can store files. It acts like a folder or box that holds your files safely. Each bucket has a name and can hold many files. You can create multiple buckets to keep different files separate.

Result

You understand that a bucket is a named container for files in cloud storage.

Understanding buckets as containers helps you organize files logically and manage them easily.

2

Foundation

Supabase storage basics

Concept: Learning how Supabase provides storage buckets as part of its cloud services.

Supabase offers storage buckets as part of its backend platform. These buckets let you save files like images or documents. Supabase manages the storage infrastructure, so you don't worry about servers or disks. You just create buckets and upload files.

Result

You know that Supabase storage buckets are ready-made containers managed by Supabase for your files.

Knowing Supabase handles the backend lets you focus on using storage without managing hardware.

3

Intermediate

Creating a bucket with Supabase CLI

🤔Before reading on: do you think creating a bucket requires writing code or just a command? Commit to your answer.

Concept: Using the Supabase command-line tool to create a storage bucket quickly.

You can create a bucket by running a simple command in the terminal. For example: supabase storage bucket create my-bucket This command tells Supabase to make a new bucket named 'my-bucket'. You can choose any name that helps you remember what files go inside.

Result

A new storage bucket named 'my-bucket' is created and ready to hold files.

Using CLI commands speeds up bucket creation and fits well in automated workflows.

4

Intermediate

Creating a bucket via Supabase dashboard

🤔Before reading on: do you think the dashboard method is faster or slower than CLI? Commit to your answer.

Concept: Using the Supabase web dashboard to create storage buckets with a graphical interface.

In the Supabase dashboard, go to the Storage section. Click 'New Bucket', enter a name, and set privacy options. Then click 'Create'. This method is visual and easy if you prefer clicking over typing commands.

Result

A new bucket appears in your dashboard, ready for file uploads.

The dashboard method is user-friendly and good for beginners or quick setups.

5

Intermediate

Bucket privacy settings explained

🤔Before reading on: do you think buckets are public by default or private? Commit to your answer.

Concept: Understanding how to control who can access files in a bucket by setting privacy options.

When creating a bucket, you choose if it is public or private. Public buckets let anyone with the link see files. Private buckets restrict access to authorized users only. This setting helps protect sensitive data or share files openly.

Result

You can control file visibility and security by setting bucket privacy.

Knowing privacy settings prevents accidental data leaks or access problems.

6

Advanced

Bucket lifecycle and management

🤔Before reading on: do you think buckets can be deleted anytime or have restrictions? Commit to your answer.

Concept: Learning how to manage buckets after creation, including renaming, deleting, and lifecycle policies.

After creating buckets, you can rename or delete them via CLI or dashboard. Some buckets may have lifecycle rules to automatically delete or archive files after a time. Managing buckets well keeps storage organized and cost-effective.

Result

You can maintain buckets over time to fit your app's needs and control costs.

Understanding bucket management helps keep your cloud storage clean and efficient.

7

Expert

Advanced bucket security and access control

🤔Before reading on: do you think bucket privacy alone is enough for security? Commit to your answer.

Concept: Exploring fine-grained access controls like signed URLs and role-based permissions beyond basic privacy.

Supabase supports signed URLs that grant temporary access to private files. You can also use policies to allow or deny actions based on user roles. This layered security protects files even if bucket privacy is public or shared.

Result

You can secure files with precise controls, balancing access and protection.

Knowing advanced security options prevents common vulnerabilities in file storage.

Under the Hood

Storage buckets in Supabase are logical containers mapped to cloud object storage systems. When you create a bucket, Supabase allocates a namespace in its storage backend. Files uploaded to a bucket are stored as objects with metadata. Access controls are enforced by Supabase's API gateway, which checks permissions before allowing file operations. Signed URLs are generated with cryptographic tokens that expire, ensuring temporary access.

Why designed this way?

Buckets provide a simple abstraction over complex cloud storage infrastructure. This design separates file organization from physical storage details, making it easier for developers. Using namespaces and access policies allows flexible security without exposing raw storage. Signed URLs offer secure, time-limited sharing without changing bucket privacy. This balances usability, security, and scalability.

┌───────────────┐       ┌───────────────┐
│ Supabase API  │──────▶│ Access Control│
│ Gateway       │       │ Checks        │
└───────────────┘       └───────────────┘
        │                      │
        ▼                      ▼
┌───────────────┐       ┌───────────────┐
│ Storage Bucket│──────▶│ Object Storage│
│ Namespace     │       │ Backend       │
└───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think all buckets are private by default? Commit to yes or no.

Common Belief: Buckets are private by default and secure without extra settings.

Reality: Buckets can be public or private depending on settings; public buckets allow anyone to access files.

Why it matters: Assuming buckets are private by default can lead to accidental public exposure of sensitive files.

Quick: Do you think creating a bucket automatically creates folders inside it? Commit to yes or no.

Common Belief: Creating a bucket also creates folders inside it for organizing files.

Reality: Buckets do not have real folders; files are stored with paths that look like folders but are just part of file names.

Why it matters: Expecting real folders can cause confusion when managing files or setting permissions.

Quick: Do you think signed URLs grant permanent access? Commit to yes or no.

Common Belief: Signed URLs provide permanent access to private files once created.

Reality: Signed URLs expire after a set time, limiting access duration for security.

Why it matters: Misunderstanding signed URLs can lead to security risks if access is assumed permanent.

Quick: Do you think you must manage physical storage hardware when using Supabase buckets? Commit to yes or no.

Common Belief: Developers need to manage servers or disks for storage buckets.

Reality: Supabase handles all physical storage management behind the scenes.

Why it matters: Thinking you manage hardware distracts from focusing on app development and can cause unnecessary complexity.

Expert Zone

1

Bucket names must be globally unique within your Supabase project but can be reused across different projects.

2

Access policies can be combined with bucket privacy to create complex rules, such as allowing read-only access to some users while others can upload.

3

Supabase storage integrates tightly with its authentication system, enabling seamless user-based file access control without extra setup.

When NOT to use

Storage buckets are not suitable for storing structured data like databases or real-time data streams. Use Supabase's database or real-time services instead. For extremely large files or specialized storage needs, consider dedicated cloud storage providers with advanced features.

Production Patterns

In production, buckets are often organized by environment (development, staging, production) and file type (images, backups). Access controls use role-based policies and signed URLs for temporary sharing. Automation scripts create and manage buckets as part of deployment pipelines.

Connections

File System Directories

Buckets are like directories that organize files logically.

Understanding file system directories helps grasp how buckets group files without physical folders.

Access Control Lists (ACLs)

Bucket privacy and policies implement ACL-like controls for file access.

Knowing ACLs clarifies how permissions restrict who can see or modify files in buckets.

Library Book Lending

Signed URLs are like library cards that allow temporary borrowing of books.

This analogy shows how temporary access tokens protect resources while enabling sharing.

Common Pitfalls

#1 Creating a bucket with a name that already exists in the project.

Wrong approach:

supabase storage bucket create my-bucket
# Error: Bucket name already exists

Correct approach:

supabase storage bucket create my-unique-bucket
# Bucket created successfully

Root cause:

Not checking for existing bucket names causes conflicts and errors.

#2 Setting a bucket as public when it should be private.

Wrong approach:

Creating bucket with --public flag for sensitive files.

Correct approach:

Creating bucket without --public flag to keep files private.

Root cause:

Misunderstanding privacy settings leads to accidental data exposure.

#3 Assuming folders exist inside buckets and trying to create them explicitly.

Wrong approach:

Trying to create a folder inside a bucket with a command like 'mkdir'.

Correct approach:

Uploading files with path prefixes to simulate folders, e.g., 'images/photo.jpg'.

Root cause:

Confusing bucket object storage with traditional file systems causes management errors.

Key Takeaways

Storage buckets are cloud containers that organize and protect your files logically.

Supabase makes creating and managing buckets easy through CLI and dashboard tools.

Bucket privacy settings control who can access your files, preventing accidental exposure.

Advanced security like signed URLs and policies provide fine-grained access control.

Understanding bucket behavior and management is essential for building secure, scalable apps.

Practice

1. What is the main purpose of creating a storage bucket in Supabase?

easy

A. To send emails automatically

B. To run server-side code

C. To create a database table

D. To organize and protect files in the cloud

Solution

1. Step 1: Understand storage bucket purpose

   A storage bucket is used to hold and organize files securely in the cloud.

2. Step 2: Compare options

   Options B, C, and D describe other services not related to file storage.

3. Final Answer:

   To organize and protect files in the cloud -> Option D

4. Quick Check:

   Storage bucket = organize and protect files [OK]

Hint: Buckets store files safely in the cloud [OK]

Common Mistakes:

• Confusing buckets with databases
• Thinking buckets run code
• Assuming buckets send emails

2. Which is the correct way to create a private storage bucket named photos in Supabase?

easy

A. supabase.storage.createBucket('photos', { access: 'private' })

B. supabase.storage.createBucket('photos', { public: false })

C. supabase.storage.createBucket('photos', { private: true })

D. supabase.storage.createBucket('photos', { isPublic: true })

Solution

1. Step 1: Recall correct method signature

   The method createBucket takes the bucket name and an options object with a public boolean.

2. Step 2: Identify correct privacy option

   Setting public: false makes the bucket private. Other options use incorrect keys.

3. Final Answer:

   supabase.storage.createBucket('photos', { public: false }) -> Option B

4. Quick Check:

   Use public: false for private bucket [OK]

Hint: Use public: false to make bucket private [OK]

Common Mistakes:

• Using wrong option keys like isPublic or private
• Setting public: true for private buckets
• Confusing access property with public

3. What will be the result of this code snippet?

const { data, error } = await supabase.storage.createBucket('docs', { public: true });
console.log(data);

medium

A. An error because 'public' is not a valid option

B. Undefined because createBucket returns nothing

C. An object with bucket details including name 'docs' and public true

D. A boolean true indicating success

Solution

1. Step 1: Understand createBucket return value

   The method returns an object with bucket info if successful, including name and public status.

2. Step 2: Analyze the code output

   Since public: true is valid, data will contain bucket details, not an error or boolean.

3. Final Answer:

   An object with bucket details including name 'docs' and public true -> Option C

4. Quick Check:

   createBucket returns bucket info object [OK]

Hint: createBucket returns bucket info object on success [OK]

Common Mistakes:

• Thinking it returns only true/false
• Assuming it throws error for public option
• Expecting no return value

4. You wrote this code but get an error:

await supabase.storage.createBucket('files', { public: 'no' });

What is the likely cause?

medium

A. The 'public' option must be a boolean, not a string

B. Bucket name 'files' is invalid

C. createBucket requires a callback function

D. Missing await keyword before createBucket

Solution

1. Step 1: Check option types

   The public option expects a boolean true or false, not a string.

2. Step 2: Identify error cause

   Passing 'no' as a string causes a type error. Bucket name and await usage are correct.

3. Final Answer:

   The 'public' option must be a boolean, not a string -> Option A

4. Quick Check:

   public option = boolean, not string [OK]

Hint: Use true/false for public, not strings [OK]

Common Mistakes:

• Passing 'yes' or 'no' as strings
• Ignoring await keyword
• Using invalid bucket names

5. You want to create two buckets: one public named images and one private named backups. Which code correctly does this?

hard

A. await supabase.storage.createBucket('images', { public: true }); await supabase.storage.createBucket('backups', { public: false });

B. await supabase.storage.createBucket('images', { public: false }); await supabase.storage.createBucket('backups', { public: true });

C. await supabase.storage.createBucket('images'); await supabase.storage.createBucket('backups');

D. await supabase.storage.createBucket('images', { access: 'public' }); await supabase.storage.createBucket('backups', { access: 'private' });

Solution

1. Step 1: Set correct privacy flags

   Public bucket needs public: true, private bucket needs public: false.

2. Step 2: Verify method calls

   await supabase.storage.createBucket('images', { public: true }); await supabase.storage.createBucket('backups', { public: false }); correctly sets these flags. await supabase.storage.createBucket('images', { public: false }); await supabase.storage.createBucket('backups', { public: true }); reverses them. await supabase.storage.createBucket('images'); await supabase.storage.createBucket('backups'); omits privacy, defaulting to private. await supabase.storage.createBucket('images', { access: 'public' }); await supabase.storage.createBucket('backups', { access: 'private' }); uses invalid keys.

3. Final Answer:

   await supabase.storage.createBucket('images', { public: true }); await supabase.storage.createBucket('backups', { public: false }); -> Option A

4. Quick Check:

   Public = true, Private = false [OK]

Hint: Public bucket: public true; Private bucket: public false [OK]

Common Mistakes:

• Mixing up public true/false
• Omitting privacy option
• Using wrong option keys like access