Storage supports multiple bucket types
Supabase Storage supports multiple specialized bucket types designed for different use cases.
Supabase · Storage · all subjects
storage/buckets
53 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
NoSuchBucket error code (404)
The NoSuchBucket error with status code 404 means the specified bucket does not exist. Resolution: Verify the bucket name and ensure it exists in the system. If it exists, check that you have permissions to access it.
BucketAlreadyExists error code (409)
The BucketAlreadyExists error with status code 409 means the specified bucket already exists. Resolution: Choose a unique name for the bucket that does not conflict with existing buckets.
InvalidBucketName error code (400)
The InvalidBucketName error with status code 400 means the specified bucket name is invalid. Resolution: Ensure the bucket name follows naming conventions and does not contain invalid characters.
Empty large buckets using AWS CLI S3 sync
To delete all objects from a bucket with more than 200,000 objects, use the AWS CLI with Supabase's S3 protocol support. Create an empty local directory and sync it to the bucket with the --delete flag enabled: aws s3 sync empty-dir/ s3://your-bucket-name --delete --profile supabase-s3 --endpoint-url https://<project-ref>.supabase.co/storage/v1/s3 --region <your-region>. This approach safely deletes all objects without leaving orphaned files.
Dashboard and Storage API hard limit for emptying buckets
Deleting objects via the Supabase Dashboard or Storage API has a hard limit of 200,000 objects per bucket. If a bucket contains more than 200,000 objects, the empty bucket operation will fail.
Set maximum upload size at bucket level
You can set a maximum upload size for your bucket to prevent users from uploading and then downloading excessively large files. The maximum file size is configured at the bucket level.
Bucket, folder, and file names must follow AWS object key naming guidelines
File, Folder, and Bucket names must follow AWS object key naming guidelines and avoid use of any other characters.
Buckets are distinct containers for files and folders
Buckets are distinct containers for files and folders, which can be thought of as super folders. You would generally create distinct buckets for different Security and Access Rules. For example, you might keep all video files in a video bucket and profile pictures in an avatar bucket.
Create bucket with SQL
To create a bucket called avatars using SQL: insert into storage.buckets (id, name) values ('avatars', 'avatars');
Create bucket with Dart
To create a bucket using Dart: final supabase = SupabaseClient('supabaseUrl', 'supabaseKey'); final storageResponse = await supabase.storage.createBucket('avatars');
Create bucket with Python
To create a bucket using Python: response = supabase.storage.create_bucket('avatars')
Storage schema tables: buckets, objects, migrations
The Storage schema contains three tables: **buckets table** with columns: id (text, PK), name (text), created_at (timestamptz), updated_at (timestamptz), public (boolean), file_size_limit (bigint), allowed_mime_types (text[]), owner_id (text). **objects table** with columns: id (uuid, PK), bucket_id (text, FK), name (text), created_at (timestamptz), updated_at (timestamptz), metadata (jsonb), path_tokens (text[]), version (text), owner_id (text). **migrations table** with columns: id (integer, PK), name (varchar(100)), hash (varchar(40)), executed_at (timestamp). The buckets table has a one-to-many relationship with the objects table via buckets.id to objects.bucket_id.
Buckets table stores bucket configuration
The buckets table holds bucket configuration including the bucket id and name, whether the bucket is public, and constraints such as file_size_limit and allowed_mime_types.
Objects table stores per-file metadata
The objects table holds per-file metadata including the owning bucket_id, the object name and path_tokens, a metadata JSON blob, and version information.
Per-bucket file size restrictions
Per-bucket file size limits must not exceed the global file size limit. Buckets can have individual restrictions for file types (such as pdf, images, videos) and maximum file size. The per-bucket limit should be lower than the global limit.
Create vector index via Dashboard
To create a vector index using the Supabase Dashboard: open your vector bucket, click Create Index, enter an index name, set the dimension matching your embeddings (for example 1536 for OpenAI's text-embedding-3-small), select the distance metric (cosine, euclidean, or l2), and click Create.
Vector bucket creation via Dashboard
To create a vector bucket using the Supabase Dashboard: navigate to the Storage section, click Create Bucket, enter a name for the bucket, select Vector Bucket as the bucket type, and click Create.
Create vector bucket with JavaScript SDK
The example shows creating a vector bucket named 'embeddings' using JavaScript: import { createClient } from '@supabase/supabase-js'; const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key'); await supabase.storage.vectors.createBucket('embeddings');
Create vector bucket with Python SDK
The example shows creating a vector bucket named 'embeddings' using Python: from supabase import create_client; supabase = create_client('https://your-project-id.supabase.co', 'your-service-key'); supabase.storage.vectors().create_bucket('embeddings');
Vector index creation parameters
When creating a vector index, you specify: indexName (the name of the index), dataType (must be 'float32'), dimension (number of dimensions, must match the embedding model such as 1536 for OpenAI), and distanceMetric (one of 'cosine', 'euclidean', or 'l2').
Create vector index with JavaScript SDK
The example shows creating a vector index named 'documents-openai' using JavaScript: const bucket = supabase.storage.vectors.from('embeddings'); await bucket.createIndex({ indexName: 'documents-openai', dataType: 'float32', dimension: 1536, distanceMetric: 'cosine', });
Create vector index with Python SDK
The example shows creating a vector index named 'documents-openai' using Python: bucket = supabase.storage.vectors().from_('embeddings'); bucket.create_index( index_name='documents-openai', dimension=1536, distance_metric='cosine', data_type='float32' );
Vector index distance metrics are immutable
The distance metric (cosine, euclidean, or l2) selected for a vector index cannot be changed after creation.
Maximum vector indexes per bucket
The maximum number of indexes that can be created within a single vector bucket is 10.
Maximum batch size for vector operations
The maximum batch size for vector operations is 500 vectors per operation.
Dimension must match embedding model
The dimension parameter when creating a vector index must match the dimensions of your embedding model. For example, OpenAI's text-embedding-3-small uses dimension 1536.
Vector bucket storage limits during alpha
Vector buckets have default alpha phase limits: maximum 10 buckets per project, maximum 10 indexes per bucket, maximum vector dimensions of 4096, and maximum batch size of 1000 vectors per single insert or update request. These limits are designed to ensure fair resource allocation and can be adjusted on a case-by-case basis for production workloads.
Buckets per project limit for vector buckets
Maximum of 10 vector buckets per Supabase project.
Indexes per bucket limit for vector buckets
Maximum of 10 indexes per vector bucket.
Vector dimensions maximum for embeddings
Maximum vector dimension size for embeddings is 4096 dimensions.
Create local vector buckets with supabase seed buckets
After declaring vector buckets in config.toml, use the command 'supabase seed buckets' to create the buckets in the local environment or linked project.
Declare vector buckets in config.toml
Vector buckets can be defined declaratively in the config.toml file using the syntax [storage.vector.buckets.bucket-name]. For example: [storage.vector.buckets.documents-openai] and [storage.vector.buckets.images] define two vector buckets named documents-openai and images.
Vector bucket supported use cases
Vector buckets excel at semantic search to find documents or images similar to a query; recommendation systems to suggest products, content, or connections based on embeddings; clustering and anomaly detection to group similar items or identify outliers; image search to retrieve visually similar images from large catalogs; RAG (Retrieval-Augmented Generation) to find relevant context for LLM queries; and personalization to recommend tailored content based on user embeddings.
Vector buckets vs pgvector comparison
Vector buckets support only the `<===>` distance operator for similarity search, unlike pgvector which supports multiple algorithms. Vector buckets are ideal for large-scale data storage, backend processing workflows, and applications where speed is less critical. pgvector is ideal for fast prototyping and small data volumes, applications requiring quick response times, and user-facing features closer to the front end.
Vector bucket workflow steps
To use vector buckets: (1) Create a bucket to organize your vector data, (2) Create indexes within the bucket with specified dimensions and distance metrics, (3) Store vectors with embeddings and optional metadata, (4) Query vectors using similarity search to find nearest neighbors. The system automatically handles indexing and optimization to make searches fast and reliable even with millions of vectors.
Vector bucket contents and structure
Each vector bucket contains indexes (organized collections of vectors with consistent dimensions and distance metrics), vectors (embeddings with associated metadata for filtering and enrichment), and metadata (additional context about vectors including text, tags, and IDs).
Vector bucket key features
Vector buckets support similarity search using cosine, euclidean, or L2 distance metrics; metadata filtering to filter results by associated metadata before or after similarity search; batch operations to insert, update, and query up to 500 vectors per request; scalable storage for millions of vectors in a single index; and S3-native storage built on proven S3 infrastructure for reliability and durability.
Public bucket access model bypasses download controls
When a bucket is designated as public, it bypasses access controls for retrieving and serving files within the bucket. Anyone who possesses the asset URL can readily access the file. Access control is still enforced for uploading, deleting, moving, and copying operations.
Buckets organize files and determine access model
Buckets in Supabase Storage organize files and determine the access model for assets. Upload restrictions like maximum file size and allowed content types are defined at the bucket level.
Two access models for buckets: public and private
Supabase Storage buckets support two access models: private (the default) and public. Private buckets require RLS policies for all operations. Public buckets bypass access controls for file retrieval and serving but still enforce access control for uploads, deletes, moves, and copies.
Private bucket use cases
Private buckets are suitable for uploading users' sensitive documents and securing private assets through fine-grain RLS access controls.
Public bucket use cases
Public buckets are suitable for user profile pictures, user public media, and blog post content. Public buckets are more performant than private buckets since they are cached differently on the CDN.
createBucket public option default
The public option when creating a bucket defaults to false.
Create bucket with JavaScript client library
Use the JavaScript client library to create a bucket with this code: const { data, error } = await supabase.storage.createBucket('avatars', { public: true }). The public option defaults to false.
Create bucket with SQL
Create a bucket using SQL by inserting into the storage.buckets table: insert into storage.buckets (id, name, public) values ('avatars', 'avatars', true).
Create bucket with Dart client library
Use the Dart client library to create a bucket with this code: final storageResponse = await supabase.storage.createBucket('avatars').
Create bucket with Swift client library
Use the Swift client library to create a bucket with this code: try await supabase.storage.createBucket('avatars', options: BucketOptions(public: true)).
Create bucket with Python client library
Use the Python client library to create a bucket with this code: supabase.storage.create_bucket('avatars', options={'public': True}).
Create bucket with C# client library
Use the C# client library to create a bucket with this code: var bucket = await supabase.Storage.CreateBucket('avatars', new BucketUpsertOptions { Public = true }).
Create bucket via Supabase Dashboard
To create a bucket using the Supabase Dashboard: (1) Go to the Storage page in the Dashboard, (2) Click New Bucket and enter a name for the bucket, (3) Click Create Bucket.
Restrict bucket uploads by MIME type and file size
When creating a bucket, you can restrict uploads by specifying allowedMimeTypes and fileSizeLimit options. For example: supabase.storage.createBucket('avatars', { public: true, allowedMimeTypes: ['image/*'], fileSizeLimit: '1MB' }). Uploads that don't meet these restrictions will be rejected.
Storage buckets are interoperable with Postgres database
Supabase Storage is interoperable with the Postgres database, allowing you to create and manage buckets using SQL or client libraries in addition to the Dashboard.