Nov 16, 20268 min read

How to Migrate Supabase Storage to Amazon S3

Copy Supabase Storage buckets into S3 in your own AWS account over Supabase's S3-compatible endpoint, replace public URLs, signed URLs and storage RLS policies, and cut over without losing uploads made during the move.

Illustration for How to Migrate Supabase Storage to Amazon S3

Supabase Storage keeps files in buckets with an S3-compatible API, and the file metadata in the storage.objects table in your Postgres database, with Row Level Security policies on that table deciding who can read and write. Moving to S3 is therefore two jobs: copying the bytes, which the S3 endpoint makes straightforward, and replacing everything that pointed at Supabase, from public and signed URLs to the policies that checked the user's folder.

This guide covers both for S3 in your own AWS account: the inventory, the copy with rclone, the replacements for public URLs, signed URLs, RLS and image transformations with Encore or by hand, and a cutover that does not lose uploads made during the move.

Ways to move Supabase Storage to S3 at a glance

Encore in your AWS accountS3 by hand
Who creates the bucketEncore, from the bucket declarationYou, with Terraform or the console
Public filesPublic bucket behind CloudFront, PublicURLBucket policy or CloudFront distribution
Private filesSignedDownloadURL after your access checkPresigned URLs with the AWS SDK
Browser uploadsSignedUploadURLPresigned PUT URLs and CORS rules
PermissionsGranted to the service that declares the bucketIAM policy per task role
Local developmentencore run serves a local bucketLocalStack, MinIO or a dev bucket

Inventory what depends on Supabase Storage

The storage schema in your database lists every bucket and object, so start there. Buckets, whether they are public and how many objects and bytes each holds:

SELECT b.id, b.public, count(o.id) AS objects, pg_size_pretty(sum((o.metadata->>'size')::bigint)) AS size FROM storage.buckets b LEFT JOIN storage.objects o ON o.bucket_id = b.id GROUP BY b.id, b.public ORDER BY b.id;

Then list the policies with SELECT policyname, cmd, qual, with_check FROM pg_policies WHERE schemaname = 'storage';. A common one lets users read and write only under a folder named after their user ID, by comparing (storage.foldername(name))[1] with auth.uid(), and that check has to move into your backend.

In your code, search for getPublicUrl, createSignedUrl, createSignedUploadUrl, /storage/v1/object/public/ and /storage/v1/render/image/, and in your database for columns that store full Supabase URLs rather than object keys. The last one matters because Supabase image transformations, which resize images on request through the render/image path on Pro plans and above, have no S3 counterpart and need a replacement such as resizing on upload or an image service in front of CloudFront.

How do you migrate Supabase Storage to S3 with Encore?

Encore

Encore brings infrastructure from code to your AWS account: each bucket is a declaration in the service that uses it, and the AWS infrastructure docs describe how Encore creates a dedicated S3 bucket with a unique name for each one and puts CloudFront in front of public buckets. Encore provisions an IAM role for the service. The Supabase SDK calls become methods on the bucket, and the RLS check becomes code next to them.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create files-app --example=hello-world$ cd files-app && mkdir files$ encore secret set --type dev,local SessionKey

A public avatars bucket and a private documents bucket, keyed by user ID the same way as on Supabase, with an auth handler standing in for your login flow:

// files/files.go package files import ( "context" "crypto/hmac" "crypto/sha256" "encoding/hex" "errors" "path" "strconv" "strings" "time" "crypto/subtle" "encore.dev/beta/auth" "encore.dev/beta/errs" "encore.dev/storage/objects" ) // Was a public Supabase bucket: S3 behind CloudFront on AWS. var avatars = objects.NewBucket("avatars", objects.BucketConfig{Public: true}) // Was a private Supabase bucket with RLS on storage.objects: a private S3 bucket. var documents = objects.NewBucket("documents", objects.BucketConfig{}) var secrets struct { SessionKey string } // Tokens look like "<user id>.<unix expiry>.<hex HMAC of id.expiry>", issued by your login flow. // //encore:authhandler func AuthHandler(ctx context.Context, token string) (auth.UID, error) { uid, err := userIDFromToken(token) if err != nil { return "", &errs.Error{Code: errs.Unauthenticated, Message: "invalid token"} } return uid, nil } func userIDFromToken(token string) (auth.UID, error) { if secrets.SessionKey == "" { return "", errors.New("auth secret not set") } parts := strings.Split(token, ".") if len(parts) != 3 { return "", errors.New("invalid token") } id, expStr, sig := parts[0], parts[1], parts[2] if id == "" || strings.ContainsAny(id, "/ \t\n") { return "", errors.New("invalid token") } exp, err := strconv.ParseInt(expStr, 10, 64) if err != nil || exp <= time.Now().Unix() { return "", errors.New("invalid token") } mac := hmac.New(sha256.New, []byte(secrets.SessionKey)) mac.Write([]byte(id + "." + expStr)) expected := hex.EncodeToString(mac.Sum(nil)) if subtle.ConstantTimeCompare([]byte(sig), []byte(expected)) != 1 { return "", errors.New("invalid token") } return auth.UID(id), nil } type URLResponse struct { URL string `json:"url"` } // Replaces getPublicUrl: same object keys, new host. // //encore:api public method=GET path=/avatars/:userID func AvatarURL(ctx context.Context, userID string) (*URLResponse, error) { return &URLResponse{URL: avatars.PublicURL(userID + "/avatar.webp").String()}, nil } // Replaces createSignedUrl plus the RLS policy that matched the first folder to auth.uid(). // //encore:api auth method=GET path=/documents/:name func DocumentURL(ctx context.Context, name string) (*URLResponse, error) { uid, _ := auth.UserID() key := path.Join(string(uid), path.Base(name)) exists, err := documents.Exists(ctx, key) if err != nil { return nil, err } if !exists { return nil, &errs.Error{Code: errs.NotFound, Message: "document not found"} } signed, err := documents.SignedDownloadURL(ctx, key, objects.WithTTL(10*time.Minute)) if err != nil { return nil, err } return &URLResponse{URL: signed.URL}, nil } type UploadParams struct { Name string `json:"name"` } // Replaces createSignedUploadUrl: the browser PUTs the file straight to S3. // //encore:api auth method=POST path=/documents/upload-url func UploadURL(ctx context.Context, p *UploadParams) (*URLResponse, error) { if p.Name == "" || path.Base(p.Name) != p.Name { return nil, &errs.Error{Code: errs.InvalidArgument, Message: "name must be a plain file name"} } uid, _ := auth.UserID() signed, err := documents.SignedUploadURL(ctx, path.Join(string(uid), p.Name), objects.WithTTL(5*time.Minute)) if err != nil { return nil, err } return &URLResponse{URL: signed.URL}, nil }

With encore run, the avatar endpoint returns a URL on the local bucket, a document request without a token, with a bad signature or with an expired token gets a 401, a missing document gets a 404, and a file name like ../x.pdf is rejected. A signed upload URL accepts a PUT of the file, the download URL then returns the same bytes, and another user asking for the same file name gets a 404, because the key is always built from the caller's own ID. That last check is the storage.foldername(name)[1] = auth.uid() policy, now in Go where a test can cover it.

The object storage docs cover the rest of the API, including Upload, Download, List and Remove for server-side work like generating thumbnails on upload. A coding agent asked to add a bucket for exports declares it in the same file, and the next deploy creates it with the same permissions model.

Deploy and copy the files

Connect your AWS account as described in Connect your cloud account, create an environment on AWS and push, so Encore creates both buckets. They get unique names in your account, which aws s3 ls lists. Then generate S3 access keys under the Supabase Storage settings, which bypass RLS and are meant for server-side use only, and add both sides as rclone remotes:

# ~/.config/rclone/rclone.conf [supabase] type = s3 provider = Other access_key_id = <supabase s3 access key id> secret_access_key = <supabase s3 secret> endpoint = https://<project_ref>.storage.supabase.co/storage/v1/s3 region = <project region> [aws] type = s3 provider = AWS env_auth = true region = us-east-1
~
$ git push encore$ aws s3 ls$ rclone sync supabase:avatars aws:<avatars bucket> --progress$ rclone sync supabase:documents aws:<documents bucket> --progress$ rclone check supabase:documents aws:<documents bucket> --size-only

rclone keeps the object keys, so u_42/lease.pdf on Supabase is u_42/lease.pdf in S3 and rows that store keys need no change. For large buckets, run the copy from an EC2 instance in the bucket's region to keep it off your laptop's connection, and spot-check a few objects with aws s3api head-object to confirm the Content-Type came across.

Best fit: teams moving files into their own AWS account who want buckets, CDN and permissions created from the backend code and the access rules in code they can test.

S3 by hand

Create the buckets with Block Public Access on for private files, and for public files either a bucket policy that allows s3:GetObject or, better, a CloudFront distribution with origin access control so the bucket itself stays private. Browser uploads with presigned PUT URLs need a CORS rule on the bucket that allows PUT from your app's origin, and each service needs an IAM policy on its task role for the actions it uses. The S3 presigned URL guide covers generating them with the AWS SDK, and the rclone copy is the same as above with bucket names you chose.

Best fit: teams with an existing S3 and CloudFront layout in Terraform, or files shared with systems outside the app.

The cutover

Uploads keep arriving while the first sync runs, so copy twice. Run the full sync a day or so ahead, deploy the code that reads and writes S3 behind a switch, then in the cutover window stop uploads to Supabase, run the same rclone sync again, which only copies what changed, and flip the switch. Update stored URLs in the database with a single UPDATE that replaces the Supabase host with the new one, or better, store keys and build URLs at read time. Supabase Storage does not support S3 versioning, so deleted objects cannot be restored from it, and since rclone sync deletes objects on the destination that are not on the source, use rclone copy instead if S3 already holds new uploads you need to keep. Leave the Supabase buckets in place for a few days until nothing requests them.

How to choose

Pick Encore when the backend is moving to your own AWS account and you want the buckets, CloudFront and permissions created from the code that uses them, with Supabase's storage policies replaced by access checks in that code. Pick S3 by hand when an infrastructure team owns the bucket layout or other systems read the same buckets. The rclone copy and the two-pass cutover are the same either way.

Frequently asked questions

How do I move files from Supabase Storage to S3?

Generate S3 access keys in the Supabase Storage settings, add Supabase as an S3 remote in rclone with the endpoint https://<project_ref>.storage.supabase.co/storage/v1/s3 and your project's region, and run rclone sync from each Supabase bucket to its S3 bucket. Run one full sync ahead of time and a second incremental sync during the cutover.

Do Supabase Storage URLs keep working after moving to S3?

No. Public URLs under /storage/v1/object/public/ and signed URLs from createSignedUrl point at Supabase, so every place that builds or stores them needs to change. Keep the same object keys during the copy, so code and database rows that store keys rather than full URLs only need a new host or a new signing call.

What replaces Supabase Storage RLS policies on S3?

S3 has no per-user row policies. Keep the bucket private and have your backend check access before it returns a short-lived presigned URL, for example by requiring the first folder of the key to match the signed-in user ID, which is what a typical storage.objects policy checks.

How does Encore handle S3 buckets?

Declare a bucket in Go or TypeScript with objects.NewBucket or new Bucket. encore run serves it from a local store, and on AWS Encore creates the S3 bucket in your account, with CloudFront in front of public buckets. Encore provisions an IAM role for the service, so the code calls PublicURL, SignedDownloadURL or SignedUploadURL with no keys or bucket names in config.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders