Migrating Supabase Storage and Large Files

When founders think about migrating their Supabase project, they usually think about the database first. Tables, rows, schemas. But if your application handles file uploads, profile images, documents, or any kind of binary content, there is a second migration that is just as important: Supabase Storage.

Storage migration is where things tend to go wrong. Large files, network interruptions, and inconsistent metadata can turn what seems like a straightforward copy job into a frustrating debugging session. This guide explains what you are actually dealing with and how to get it right.

What Supabase Storage Actually Includes

Supabase Storage is not just a folder full of files. It is a structured system with several moving parts:

Buckets. These are the top-level containers for your files, similar to S3 buckets. Each bucket has a name, a public or private visibility setting, and size limits. Your app might have buckets for user avatars, document uploads, media assets, and more.

Objects. These are the individual files stored within buckets. Each object has metadata including its path, MIME type, size, creation date, and a unique identifier. The objects table in your database tracks all of this.

Access policies. Each bucket and sometimes individual paths within buckets have Row Level Security policies that control who can upload, download, and delete files. These policies are PostgreSQL functions tied to your auth system.

Database references. Your application tables likely contain columns that reference storage paths. A user profile table might have an avatar_url column pointing to a file in the avatars bucket. These references need to remain valid after migration.

A complete storage migration moves all four of these components. Miss any one of them and your application will have broken file links, inaccessible uploads, or security gaps.

Why Large File Migration Is Difficult

Migrating a database is mostly about transferring structured text data. Storage migration means moving potentially gigabytes of binary files across a network. That introduces challenges you do not face with database migrations:

Transfer timeouts. A file that takes longer to upload than your connection timeout will fail silently or partially. Large video files, high-resolution images, and document archives are common culprits. A standard HTTP upload that fails at 80% completion means starting over from the beginning.

Data corruption. Binary files are unforgiving. A single flipped bit during transfer means a corrupted image, an unreadable PDF, or a video that won't play. Unlike text data where corruption is often obvious, file corruption can go unnoticed until a user tries to open the file weeks later.

Network interruptions. Internet connections are not perfectly reliable. A brief network hiccup during a large file transfer can cause the entire upload to fail. When you are moving thousands of files, the probability of at least one interruption approaches certainty.

Memory pressure. Naive migration scripts that load entire files into memory before uploading them will crash when they encounter a 500 MB video or a 200 MB dataset export. Your migration tool needs to stream files efficiently.

Consistency. While files are being migrated, your application may still be generating new uploads. If the migration takes hours, you can end up with files that exist in the source but were never copied to the target.

How Stack2X Handles Storage Migration

Stack2X addresses each of these challenges with specific technical strategies designed for reliability at scale.

TUS resumable uploads. Instead of standard HTTP uploads that fail completely on interruption, Stack2X uses the TUS protocol for large file transfers. TUS breaks files into chunks and tracks upload progress. If a transfer fails at 80%, it resumes from that point rather than starting over. This is the same protocol that platforms like YouTube and Vimeo use for handling large media uploads.

Bucket recreation. Stack2X does not just copy files. It recreates the entire bucket structure on your target instance, including visibility settings, file size limits, and MIME type restrictions. Your target environment mirrors the source configuration exactly.

Policy preservation. RLS policies on storage buckets are migrated alongside the files. You do not need to manually rewrite security rules on the target instance. The policies that control who can read, write, and delete files are carried over automatically.

Integrity verification. After each file transfer, Stack2X verifies that the transferred file matches the original by comparing checksums. If a file arrives corrupted, it is flagged and retransferred rather than silently accepted.

Streaming transfers. Files are streamed between source and target without loading entire files into memory. This means a 2 GB video file does not require 2 GB of RAM on the migration server.

File Size Considerations

Not all storage migrations are equal. The size and composition of your storage affects how you should plan:

Under 1 GB total storage. Migration is fast and straightforward. You can typically complete it in a single session without worrying about timeouts or interruptions.

1 GB to 10 GB. Plan for the migration to take 30 minutes to a few hours depending on your network speed. Resumable uploads become important at this scale. Make sure your maintenance window accounts for this time.

10 GB to 100 GB. At this scale, network reliability becomes a real concern. Resumable uploads are essential. Consider running the migration during off-peak hours when your network has the most bandwidth available.

Over 100 GB. Large storage migrations need careful planning. Talk to your team about whether all files need to migrate immediately. Some teams migrate active files first and archive older files separately. Prioritize the files your application actively serves to users.

Regardless of size, always check that your target server has enough disk space before starting. Running out of storage mid-migration creates a mess that is tedious to clean up.

Verification Steps After Migration

Do not consider the migration complete until you have verified these items:

File count comparison. The number of objects in each bucket on the target should match the source. A mismatch means files were skipped or failed to transfer.

Spot-check file integrity. Open a random sample of files on the target instance. Can images be viewed? Do PDFs render? Can videos play? Automated checksums catch corruption, but a manual spot check builds confidence.

Test application features. Upload a new file through your application pointed at the target instance. Download an existing file. Delete a test file. Confirm that the full read/write/delete lifecycle works.

Verify access policies. Try accessing a private file without authentication. It should be denied. Try accessing a public file without authentication. It should succeed. Confirm that your RLS policies are enforced correctly.

Check database references. Load a few records in your application that reference storage files. Do the images display? Do the download links work? Broken references here mean the file paths changed during migration.

Planning for a Smooth Migration

Storage migration does not need to be stressful. The teams that struggle are the ones who treat it as an afterthought, tacking it on after the database migration without planning. The teams that succeed treat storage as a first-class component of the migration plan.

Include storage in your pre-migration audit. Know how much data you are moving and how long it will take. Use a tool that handles resumable uploads and integrity checks. Verify thoroughly before cutting over. And if something does go wrong, your pre-migration backup means you can always start fresh.

Your files are just as important as your database. Migrate them with the same level of care.