AnalyticDB: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 content

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

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

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

• Storage objects: buckets and the files they contain.

• Edge Functions: Function code and related configurations.

• Roles and permissions: database user and permission settings.

Required parameters

• Source environment configuration

  • Supabase Cloud source configuration

    --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 project or AnalyticDB Supabase

    --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, must be 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, must be percent-encoded)

Optional parameters

• Supabase Cloud source configuration

  --source-database-url string        # Source Database URL (Optional, must be 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 a local executor instead of a Docker container. Requires local installation of tools like pg_dump.
  --concurrency int                  # Number of concurrent operations (Default: 2)
  --dry-run                          # Preview the migration without executing it.
  --resume-from string               # Resume from a specified step (database|storage|functions).

• Security options

  Important

  When using the --allow-truncate parameter, verify the source and target configurations to prevent accidental data deletion from the source database.

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

Step 1: Get project information and configure environment variables

1. Obtain the source configuration information.

   For Supabase Cloud, obtain the following information from the project settings page.

   • Project Ref: A 20-character project ID.

     • Navigate to the Supabase console.

     • Click the source project and view its URL. For example, in the URL https://supabase.com/dashboard/project/qeqfhfoebrtkbmwd****, the Project Ref is at the end: 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 the source project page, click connect, go to the Connection String tab, and select Transaction pooler for the Method.

2. Obtain the target AnalyticDB Supabase configuration information. For more information, see Obtain 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, plugins, and other objects.

3. (Optional) To avoid exposing sensitive information on the command line, configure project information as environment variables.

   • Migrate 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

   • Migrate from a self-hosted Supabase project or an AnalyticDB Supabase project 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 migration tool and log in

1. Download the supabase-cli tool for your operating system and architecture. In subsequent commands, use the filename of the downloaded tool instead of supabase-cli.

   • 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 complete the login.

   ./supabase-cli login

Step 3 (Optional): Preview migration

• Migrate 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

• Migrate from a self-hosted Supabase project or an AnalyticDB Supabase project 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

Run the following command to check the network connection.

# Check the network connection
ping db.your-project-ref.supabase.co

# Check the Database URL format
# Correct format: postgres://postgres:password@host:port/database

'Permission denied' error

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

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

• Confirm that the target database user has administrative permissions.

Plugin not available error

Install the missing plugin in the target database, or remove the unnecessary plugin 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 using environment variables for project information. If you pass the connection string directly, you must escape any special characters as follows:

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