Migrate a Supabase project

Migration paths

• Migrate from Supabase Cloud to AnalyticDB Supabase.

• Migrate from a self-hosted Supabase project to AnalyticDB Supabase.

• Migrate between AnalyticDB Supabase projects.

Migration scope

• Database schema: Includes schemas, table structures, functions, and triggers.

• Database data: Includes user data, authentication data, and other system data.

• PostgreSQL extensions: Automatically installs required extensions in the target project.

• Storage objects: buckets and the files they contain.

• Edge Functions: Function code and related configuration.

• Roles and permissions: Database user and permission settings.

Required parameters

• Source environment configuration

  • Supabase Cloud source

    --source-project-ref string         # Source Project Ref (required)
    --source-anon-key string            # Source Anon Key (required)
    --source-service-role-key string    # Source Service Role Key (required)

  • Self-hosted Supabase or AnalyticDB Supabase source

    --source-api-url string             # Source API URL (required)
    --source-anon-key string            # Source Anon Key (required)
    --source-service-role-key string    # Source Service Role Key (required)
    --source-database-url string        # Source database URL (required, percent-encoded)

• Target environment configuration

  --target-api-url string             # Target API URL (required)
  --target-anon-key string            # Target Anon Key (required) 
  --target-service-role-key string    # Target Service Role Key (required)
  --target-database-url string        # Target database URL (required, percent-encoded)

Optional parameters

• Supabase Cloud source

  --source-database-url string        # Source database URL (optional, percent-encoded)

• Migration content

  --include-data                     # Include database data (default: true)
  --include-storage                  # Include storage objects (default: true)
  --include-functions                # Include Edge Functions (default: true)
  --include-system-data              # Include system module data (default: true)

• Execution options

  --use-local-exec                   # Use local executor; does not rely on a Docker container. Requires tools like pg_dump to be installed locally.
  --concurrency int                  # Concurrency (default: 2)
  --dry-run                          # Performs a dry run without executing the actual migration.
  --resume-from string               # Resume from a specified step (database|storage|functions).

• Security options

  Important

  When using the --allow-truncate parameter, verify your source and target configurations to avoid accidentally deleting data from the source database.

  --allow-truncate                  # Allow truncating table data (default: false)
  --preserve-extra-tables           # Preserve extra tables in the target database (default: true)

Step 1: Get project information and set environment variables

1. Get the source configuration information.

   For Supabase Cloud, get the following information from your project's settings page.

   • Project Ref: A 20-character project ID.

     • Go to the Supabase dashboard.

     • Click your source project and check the URL. For example, in https://supabase.com/dashboard/project/qeqfhfoebrtkbmwd****, the Project Ref is at the end of the URL (qeqfhfoebrtkbmwd****).

   • Anon Key: The anonymous key, which starts with eyJ.

   • Service Role Key: The service role key, which starts with eyJ. This key must have permission to read all data.

   • Database URL (Optional): The PostgreSQL connection string.

     On your source project's page, click Connect, go to the Connection String tab, and select Transaction pooler for the Method.

     Copy the displayed connection string and replace [YOUR-PASSWORD] with your actual database password.

2. Get the configuration information for the target AnalyticDB Supabase project. For details, see Get API Keys.

   • API URL: The full API address, such as https://your-domain.supabase.opentrust.net.

   • Anon Key: The anonymous key for the target environment.

   • Service Role Key: The service role key for the target environment. This key must have full administrative permissions.

   • Database URL: The PostgreSQL connection string. The target database user must have permissions to create tables and extensions.

3. (Optional) To avoid exposing sensitive information on the command line, we recommend configuring project information in environment variables.

   • Migrating from Supabase Cloud to AnalyticDB Supabase

     # Create a configuration file
     cat > migration.env << 'EOF'
     SOURCE_PROJECT_REF="your-project-ref"
     SOURCE_ANON_KEY="eyJ..."
     SOURCE_SERVICE_ROLE_KEY="eyJ..."
     TARGET_API_URL="https://your-domain.supabase.opentrust.net"
     TARGET_ANON_KEY="eyJ..."
     TARGET_SERVICE_ROLE_KEY="eyJ..."
     TARGET_DATABASE_URL="postgres://postgres:password@{your-project-id}.supabase.opentrust.net:5432/postgres"
     EOF
     # Load the environment variables
     source migration.env

   • Migrating from a self-hosted Supabase or AnalyticDB Supabase to AnalyticDB Supabase

     # Create a configuration file
     cat > migration.env << 'EOF'
     SOURCE_API_URL="http://localhost:54321"
     SOURCE_ANON_KEY="eyJ..."
     SOURCE_SERVICE_ROLE_KEY="eyJ..."
     SOURCE_DATABASE_URL="postgres://postgres:password@{your-project-id}.supabase.opentrust.net:5432/postgres"
     TARGET_API_URL="https://your-domain.supabase.opentrust.net"
     TARGET_ANON_KEY="eyJ..."
     TARGET_SERVICE_ROLE_KEY="eyJ..."
     TARGET_DATABASE_URL="postgres://postgres:password@{your-project-id}.supabase.opentrust.net:5432/postgres"
     EOF
     # Load the environment variables
     source migration.env

Step 2: Download the tool and log in

1. Download the supabase-cli tool for your operating system and architecture. In the following commands, replace supabase-cli with the name of the downloaded file.

   • supabase-cli-linux-arm64-20260403

   • supabase-cli-linux-arm-20260403

   • supabase-cli-linux-amd64-20260403

   • supabase-cli-linux-386-20260403

   • supabase-cli-windows-amd64-20260403.exe

   • supabase-cli-windows-386-20260403.exe

   • supabase-cli-darwin-amd64-20260403

   • supabase-cli-darwin-arm64-20260403

2. Run the following command and follow the prompts to log in.

   ./supabase-cli login

Step 3: (Optional) Preview the migration

• Migrating from Supabase Cloud to AnalyticDB Supabase

  ./supabase-cli migrate-project \
    --source-project-ref "$SOURCE_PROJECT_REF" \
    --source-anon-key "$SOURCE_ANON_KEY" \
    --source-service-role-key "$SOURCE_SERVICE_ROLE_KEY" \
    --target-api-url "$TARGET_API_URL" \
    --target-anon-key "$TARGET_ANON_KEY" \
    --target-service-role-key "$TARGET_SERVICE_ROLE_KEY" \
    --target-database-url "$TARGET_DATABASE_URL" \
    --dry-run

• Migrating from a self-hosted Supabase or AnalyticDB Supabase to AnalyticDB Supabase

  ./supabase-cli migrate-project \
    --source-hosted \
    --source-api-url "$SOURCE_API_URL" \
    --source-anon-key "$SOURCE_ANON_KEY" \
    --source-service-role-key "$SOURCE_SERVICE_ROLE_KEY" \
    --source-database-url "$SOURCE_DATABASE_URL" \
    --target-api-url "$TARGET_API_URL" \
    --target-anon-key "$TARGET_ANON_KEY" \
    --target-service-role-key "$TARGET_SERVICE_ROLE_KEY" \
    --target-database-url "$TARGET_DATABASE_URL" \
    --dry-run

Step 4: Migrate the Supabase project

Connection refused error

Use the following commands to check the network connection.

# Check network connectivity
ping db.your-project-ref.supabase.co
# Check the database URL format
# Correct format: postgres://postgres:password@host:port/database

Permission denied for schema auth error

• Ensure you are using the Service Role Key, not the Anon Key.

• Verify that the key has sufficient permissions. For requirements, see Prerequisites.

• Confirm that the target database user has administrative privileges.

Extension unavailable error

Install the missing extension in the target database, or remove the unnecessary extension from the source database.

Sequence conflict error

Use the following command:

# Use a safer table cleanup policy
supabase migrate-project ... --preserve-extra-tables=true --allow-truncate=true

Special characters in connection strings

We recommend configuring project information in environment variables. If you do not use environment variables, you must escape any special characters in the connection string as follows:

! : %21
@ : %40
# : %23
$ : %24
% : %25
^ : %5e
& : %26
* : %2a
( : %28
) : %29
_ : %5f
+ : %2b
= : %3d