Migrating from Supabase Cloud

This guide walks you through migrating an existing Supabase Cloud project to your self-hosted Supascale instance.

Migration Options

Supascale offers two ways to migrate from Supabase Cloud:

Automatic Migration (Recommended)

The Lift & Shift feature connects directly to your Supabase Cloud project and transfers your data automatically.

What Gets Migrated

Prerequisites

Before starting:

1. Create a project in Supascale and start it (required for database migration)
2. Gather your Supabase Cloud credentials (see below)

Finding Your Supabase Credentials

You'll need three pieces of information from your Supabase Cloud project:

1. Project URL

• Go to Settings → API in your Supabase dashboard
• Copy the Project URL (e.g., https://hkajjfcjmpigqaziopzw.supabase.co)

2. Service Role Key

• On the same Settings → API page
• Under "Project API keys", copy the service_role key (not the anon key)

The service role key has full access to your project. Keep it secure and never expose it in client-side code.

3. Database Password

• This is the password you set when creating your Supabase project
• If you've forgotten it, go to Settings → Database and click "Reset database password"

Step-by-Step Migration

1. Navigate to Import page

   • In Supascale, go to Backups → Import / Migrate

2. Select your target project

   • Choose the Supascale project you want to migrate into
   • The project must be running for database migration

3. Enter Supabase credentials

   • Project URL: Your Supabase project URL
   • Service Role Key: Your service_role API key
   • Database Password: Your Supabase database password

4. Select components to migrate

   • Database (recommended) - Migrates all your data
   • Storage (recommended) - Migrates all files and buckets
   • Auth Config - Detects OAuth providers (requires manual re-setup)

5. Click "Start Migration"

6. Monitor progress

   • A dialog will show real-time progress
   • The migration streams updates as each step completes
   • Large databases may take several minutes

After Migration

Once the migration completes:

1. Verify your data

   • Check your tables in the SQL Editor or Table Editor
   • Browse storage files in the Storage Browser
   • Test your application against the new project

2. Update your application

   • Change your Supabase URL and keys to point to your Supascale instance
   • Update any hardcoded references to the old project URL

3. Re-configure OAuth providers (if using social login)

   • Go to Project Settings → Authentication → Auth Providers
   • Re-enter client secrets for each provider
   • Update redirect URIs in each provider's dashboard (Google, GitHub, etc.)
   • The new redirect URI format is: https://your-domain/auth/v1/callback

OAuth provider secrets cannot be exported from Supabase Cloud for security reasons. You'll need to copy them from each provider's developer console.

Manual Migration

If you prefer more control or have specific requirements, you can migrate manually.

Step 1: Export Database

From your local machine with psql installed:

# Get your connection string from Supabase Dashboard → Settings → Database
pg_dump "postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres" \
  -Fc -f backup.dump

Or use a plain SQL dump:

pg_dump "postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres" \
  -f backup.sql

Step 2: Export Storage Files

1. Go to Storage in your Supabase dashboard
2. Download files from each bucket
3. Organize them in folders matching your bucket names:

   storage/
   ├── avatars/
   │   └── user1.png
   ├── documents/
   │   └── report.pdf
   └── public/
       └── logo.svg
   

4. Create a ZIP archive:

   zip -r storage.zip storage/
   

Step 3: Export Edge Functions

If you have Edge Functions:

# From your project directory
tar -czf functions.tar.gz -C supabase functions

Step 4: Import into Supascale

1. Go to Backups → Import / Migrate in Supascale
2. Select your target project
3. Use the manual import cards to upload each file:
   • Database: Upload your .dump or .sql file
   • Storage: Upload your .zip archive
   • Edge Functions: Upload your .tar.gz archive

Troubleshooting

"Project must be running"

The target project needs to be running for database migration. Start the project from the Projects page before attempting migration.

"Failed to connect to source database"

• Verify your database password is correct
• Check that your Supabase project is active (not paused)
• Ensure you're using the correct project URL

"Service role key invalid"

• Make sure you copied the service_role key, not the anon key
• The key should start with eyJhbGciOi...
• Check for any extra spaces when copying

Migration timeout

For very large databases:

• Consider migrating database and storage separately
• Use manual migration with pg_dump for databases over 1GB
• Storage migration handles large files but may take time

Some storage files missing

• Check the output log for any failed file transfers
• Verify bucket permissions in the source project
• Re-run storage migration if needed (it won't duplicate files)

Best Practices

1. Test first - Create a test project and migrate there before your production migration

2. Plan downtime - Brief downtime may be needed when switching your application to the new instance

3. Backup before migrating - Keep your Supabase Cloud project active until you've verified the migration

4. Update DNS last - Only point your domain to the new instance after verifying everything works

5. Monitor after migration - Watch logs and application behavior for the first few hours

Related Documentation

• Backups API - Lift & Shift - API documentation for automated migration
• Creating Backups - Set up backups in your new instance
• Auth Providers - Configure social login providers