Configuring Storage in Supamode

Supamode integrates with Supabase Storage to handle file uploads directly from the Data Explorer. When you configure a column as a file type, Supamode automatically handles uploads, generates paths, and stores references in your database.

How Storage Integration Works

1. You configure a column as a file type (image, file, audio, video)
2. When editing a record, Supamode shows a file uploader instead of a text input
3. On upload, the file goes to your configured Supabase Storage bucket
4. The file path (URL or reference) is stored in the database column

This lets your team upload files through the admin UI without building custom upload flows.

Configuring Storage for a Column

Navigate to Settings > Tables, select a table, then click on a column to edit its settings.

UI Data Type

Set the column's UI Data Type to one of:

Once set, the column configuration expands to show storage options.

Bucket Name

The Bucket Name must match an existing bucket in your Supabase Storage.

Prerequisites:

1. Create the bucket in Supabase Dashboard > Storage
2. Configure the bucket's privacy settings (public/private)
3. Set up RLS policies if the bucket is private
4. Enter the exact bucket name in Supamode

avatars
documents
media
uploads

Storage Path Template

The Storage Path Template determines where files are stored within the bucket. Use placeholders to create dynamic paths.

Available placeholders:

Example templates:

# Simple - files in root with timestamp
{{timestamp}}-{{filename}}.{{extension}}
→ 1705689600-profile-photo.png
# Organized by user ID column
users/{{user_id}}/{{filename}}.{{extension}}
→ users/abc-123/profile-photo.png
# By date and type
uploads/{{timestamp}}/{{filename}}.{{extension}}
→ uploads/1705689600/document.pdf
# Custom folder structure
avatars/{{user_id}}/avatar.{{extension}}
→ avatars/abc-123/avatar.webp

Path rules:

• If the template doesn't include {{extension}}, Supamode treats the path as a folder and appends the original filename
• Use column references ({{column_name}}) for values from the same record
• Paths are case-sensitive

Max File Size

The Max File Size sets a client-side limit on upload size (in bytes).

Replace Existing Files

When Replace Existing Files is enabled, uploading a new file to the same path overwrites the previous file.

When to enable:

• User avatars (one file per user)
• Document that should always be the latest version
• Paths that are deterministic (like avatars/{{user_id}}/avatar.{{extension}})

When to disable:

• Upload history should be preserved
• Multiple files per record are expected
• Paths include timestamps (files are unique anyway)

Storage Permissions

Users need storage permissions to upload, view, or delete files. Configure these in Roles and Permissions.

Required permissions by action:

Example permission:

Type: Data
Scope: Storage
Bucket: avatars
Path: users/*
Action: * (all operations)

Troubleshooting

Upload Fails with "Bucket Not Found"

1. Verify the bucket exists in Supabase Dashboard > Storage
2. Check the bucket name matches exactly (case-sensitive)
3. Ensure the bucket is not disabled

Upload Fails with "Permission Denied"

1. Check the user's role has storage permissions for this bucket
2. Verify the bucket's RLS policies allow uploads
3. For public buckets, confirm public access is enabled

Files Not Displaying

1. Verify the column contains a valid storage path/URL
2. Check the bucket's privacy settings
3. For private buckets, ensure signed URLs are being generated

Path Template Not Working

1. Check placeholder syntax: {{column_name}} not {column_name}
2. Verify referenced columns exist in the same table
3. Ensure the column value is not null when uploading