Migration Wizard Step-by-Step

The Stack2X migration wizard breaks a complex process into five straightforward steps. You do not need any database experience to use it. This article walks through every step so you know exactly what to expect.

Step 1: Select Your Source Instance

The first screen asks you to choose the instance you want to migrate from. This is your source -- the Supabase project that currently holds your data, users, and configuration.

Pick your source from the dropdown list. You will see each instance labeled with its name and hosting type (Cloud or Self-hosted). If you do not see the instance you need, go to the Instances page and add it first.

Click Next to continue.

Step 2: Select Your Target Instance

Now choose the instance you want to migrate to. This is where your data will be written. The source instance you selected in Step 1 is automatically excluded from this list so you cannot accidentally select the same project for both.

Pay attention to the warning on this screen: data will be written to the target instance, and existing data may be affected depending on your conflict resolution settings. If your target already contains data, decide how you want to handle overlaps before proceeding.

Click Next to continue.

Step 3: Pick Your Components

This is where you choose exactly what gets migrated. Stack2X lists every available component, from database schema and data to auth users, storage buckets, edge functions, and more.

Check the boxes next to the components you want to include. Some components are marked Cloud only, meaning they use the Supabase Management API and are only available when the source or target is a Cloud project. If your target is self-hosted, cloud-only components will be flagged during the review step.

Certain components may show a lock icon with a plan name (Starter, Pro, or Business). This means your current plan does not include that component. You can upgrade your plan to unlock it.

At the bottom of this screen, select a conflict resolution strategy:

Skip existing -- if a record or object already exists on the target, leave it untouched.
Overwrite existing -- replace existing records on the target with the source data.

Click Next when you have made your selections.

Step 4: Review Your Migration Plan

The review screen shows a summary of everything you have configured: source instance, target instance, selected components, and conflict resolution strategy.

At this point Stack2X checks your OAuth status for both instances. Some components (like auth configuration, email templates, edge functions, and secrets) require a Supabase OAuth connection to read from the source or write to the target. If OAuth is missing or does not have the right permissions, the wizard shows a red alert with a Connect or Reconnect button. Click it to authorize through Supabase and return to the wizard automatically.

The wizard also shows any warnings specific to your migration. Common warnings include:

JWT secret mismatch when migrating auth users, which means all users will need to log in again on the target.
Edge function secrets that cannot be exported via API and need to be re-entered manually.
Cloud-only components selected for a self-hosted target, which will be skipped.

Review everything carefully. When you are satisfied, check the confirmation box that says you understand data will be written to the target, then click Start Migration.

Step 5: Monitor Progress

After you start the migration, Stack2X takes you to the monitoring screen. Here you can watch progress in real time as each component is processed. The wizard handles the correct execution order automatically -- schema before data, auth before policies -- so you do not need to worry about sequencing.

Each component shows its current status: pending, running, completed, failed, or skipped. If something fails, you will see an error message with details about what went wrong.

A migration can finish in one of three states:

Completed -- everything migrated successfully.
Partially completed -- some components succeeded but others failed or were skipped.
Failed -- the migration could not proceed, and the target remains unchanged.

If a migration partially completes, review the failed tasks, fix the underlying issue, and run a new migration with only the failed components selected.

Tips for a Smooth Migration

Add both instances and test their connections before starting the wizard.
Freeze writes to your source during migration to prevent inconsistencies.
Start with a smaller migration (just schema and data) before migrating everything at once.
Keep your source instance running after migration as a fallback until you verify everything works.