Help Center / Getting Started

Running Your First Migration

A migration moves data from one Supabase instance to another. Whether you're moving from Supabase Cloud to a self-hosted setup, consolidating projects, or setting up a new production environment, Stack2X makes the process straightforward. This guide walks you through your first migration step by step.

Prerequisites

Before you begin, make sure you have:

Two connected instances. You need both a source (where data comes from) and a target (where data goes). If you haven't connected your instances yet, follow the Connecting Your First Instance guide for each one.
Member, admin, or owner role. Viewers cannot run migrations.
A recent backup of your source instance. This isn't strictly required, but it's strongly recommended. If anything goes wrong, you'll have a fallback. See Creating Your First Backup for instructions.

Step 1: Navigate to Migrations

From your Stack2X dashboard, click Migrations in the sidebar. You'll see any previous migrations listed here, along with a button to start a new one.

Click New Migration to open the migration wizard.

Step 2: Select Source and Target

The wizard starts by asking you to choose your source and target instances from the dropdown menus.

Source -- The Supabase instance you're migrating data from.
Target -- The Supabase instance you're migrating data to.

Double-check your selection before proceeding. Mixing up source and target could overwrite data in the wrong project.

Step 3: Choose Components

Just like with backups, Stack2X lets you pick which components to include in the migration:

Database -- Tables, data, schemas, functions, and triggers.
Auth Users -- User accounts and authentication data.
Storage -- Files and storage buckets.
Edge Functions -- Serverless functions.

For your first migration, consider starting with just the database to keep things simple. You can always run additional migrations for other components afterward. If you're confident in your setup, selecting all components will move everything at once.

Step 4: Review and Start

Before the migration begins, Stack2X shows you a summary of what will happen: the source instance, the target instance, and the selected components. Review this carefully.

When you're ready, click Start Migration. Stack2X will begin transferring data from your source to your target instance.

Step 5: Monitor Progress

The migration page displays real-time progress for each component. You'll see each component move through these stages:

Pending -- Waiting to start.
Reading -- Extracting data from the source instance.
Writing -- Inserting data into the target instance.
Completed -- Successfully migrated.

The entire process typically takes a few minutes for small projects. Larger projects with extensive databases or many storage files may take longer. You can safely navigate away from the page -- the migration continues in the background and you'll receive a notification when it finishes.

If a component encounters an error, Stack2X will flag it and provide details. The other components will continue to migrate independently.

Step 6: Verify Your Results

After the migration completes, take a few minutes to verify that everything landed correctly in your target instance:

Check your database. Open your target Supabase project and confirm that your tables and data are present.
Test authentication. Try logging into your app with an existing user account to make sure auth users migrated correctly.
Verify storage. Browse your storage buckets in the target instance and confirm that files are accessible.
Test edge functions. If you migrated edge functions, invoke one to make sure it runs correctly.

Tips for a Smooth First Migration

Run a backup first. Always back up your source instance before migrating. This gives you a safety net if anything goes wrong.
Start small. If you're nervous, migrate just one component first to see how the process works. Then run the rest.
Use a staging target. If possible, migrate to a test instance first before touching your production environment.
Check your target is empty. Migrating into a target that already has data can cause conflicts. For a clean migration, start with a fresh Supabase project as your target.

What's Next

With your first migration complete, you're up and running with Stack2X. Explore the rest of the help center to learn about advanced topics like scheduling backups, managing team permissions, and troubleshooting common migration issues.