AnalyticDB:How to 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 schemas, functions, and triggers.

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

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

• Storage: Buckets and the files they contain.

• Edge Functions: Function code and related configurations.

• Roles and permissions: Database user roles and permissions.

Required parameters

• Source environment configuration

  • Supabase Cloud source configuration

    --source-project-ref string         # Source project reference ID (required)
    --source-anon-key string            # Source project anonymous key (required)
    --source-service-role-key string    # Source project service role key (required)

  • Self-hosted Supabase project or AnalyticDB Supabase

    --source-api-url string             # Source API URL (required)
    --source-anon-key string            # Source project anonymous key (required)
    --source-service-role-key string    # Source project service role key (required)
    --source-database-url string        # Source database URL (required and must be percent-encoded)

• Destination environment configuration

  --target-api-url string             # Destination API URL (required)
  --target-anon-key string            # Destination project anonymous key (required) 
  --target-service-role-key string    # Destination project service role key (required)
  --target-database-url string        # Destination database URL (required and must be percent-encoded)

Optional parameters

• Supabase Cloud source configuration

  --source-database-url string        # Source database URL (optional) and must be percent-encoded

• Migration content

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

• Execution options

  --use-local-exec                   # Uses a local executor and does not rely on a Docker container. Tools such as pg_dump must be installed locally.
  --concurrency int                  # Number of concurrent operations (default: 2)
  --dry-run                          # Preview mode. Does not perform the actual migration.
  --resume-from string               # Resumes from a specified step (database|storage|functions)

• Security options

  Important

  When you use the --allow-truncate parameter, ensure that the source and destination configurations are correct to prevent accidental data deletion from the source database.

  --allow-truncate                  # Allows clearing table data (default: false)
  --preserve-extra-tables           # Preserves extra tables in the destination database (default: true)

Step 1: Obtain 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.

     • Go to the Supabase console.

     • Click the source project and view the URL. For example, in the URL https://supabase.com/dashboard/project/qeqfhfoebrtkbmwd****, the Project Ref is the last part 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 permissions to read all data.

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

     Click Connect at the top of the source project page. On the Connection String tab, set Method to Transaction pooler.

     

2. Obtain the destination 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 destination environment.

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

   • Database URL: The PostgreSQL connection string. The destination database user must have permissions to create tables, extensions, and other objects.

3. (Optional) Configure the project information as environment variables to avoid exposing sensitive information on the command line.

   • 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 migration tool and log on

1. Download the supabase-cli tool for your operating system and architecture. When you run the commands, replace supabase-cli with the name of the downloaded CLI tool.

   • supabase-cli-linux-arm64-20260120

   • supabase-cli-linux-arm-20260120

   • supabase-cli-linux-amd64-20260120

   • supabase-cli-linux-386-20260120

   • supabase-cli-windows-amd64.exe

   • supabase-cli-windows-386.exe

   • supabase-cli-darwin-amd64-20260120

   • supabase-cli-darwin-arm64-20260120

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

   ./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

How do I resolve the "connections refused" error when connecting to the source database?

Use the following command to check network connectivity.

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

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

How do I resolve the "permission denied for schema auth" error?

• Ensure that you are using the Service role key, not the Anon key.

• Check that the key has sufficient permissions. For more information about permission requirements, see Prerequisites.

• Confirm that the destination database user has administrative permission.

How do I resolve the "plugin xxx is not available in the target database" error?

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

How do I resolve the sequence conflict error "relation "test_id_seq" already exists"?

Use the following command:

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

How do I handle special characters in a database connection string?

Configure the project information as an environment variable. If you do not configure an environment variable, escape the special characters as follows:

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