AnalyticDB:How to migrate a Supabase project

From Supabase Cloud

Get the following from your Supabase dashboard:

• Project Ref — the 20-character ID at the end of your project URL. For example, in https://supabase.com/dashboard/project/qeqfhfoebrtkbmwd**`, the Project Ref is `qeqfhfoebrtkbmwd**.

• Anon Key — starts with eyJ. Find it in project settings.

• Service Role Key — starts with eyJ. This key must have read access to all data.

• Database URL (optional) — the PostgreSQL connection string. Click Connect at the top of the project page, go to the Connection String tab, and set Method to Transaction pooler.

From AnalyticDB Supabase (destination)

Get the following from your AnalyticDB Supabase project. See Obtain API keys for detailed steps:

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

• Anon Key — the anonymous key for the destination project

• Service Role Key — must have full administrative permission

• Database URL — the PostgreSQL connection string. The database user must have permission to create tables, extensions, and other objects.

Store credentials as environment variables

Storing credentials in environment variables avoids exposing them on the command line and handles special characters automatically.

Migrating from Supabase Cloud:

# 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 self-hosted Supabase or 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

Required parameters

Supabase Cloud source:

Self-hosted Supabase or AnalyticDB Supabase source:

Destination (all cases):

Optional parameters

How do I resolve connection refused when connecting to the source database?

Check network connectivity with:

ping db.your-project-ref.supabase.co

Make sure the database URL follows this format: postgres://postgres:password@host:port/database

Also verify that the destination database allows external connections and that both the source and destination APIs are reachable from your machine.

How do I resolve permission denied for schema auth?

This error means the tool is using a key without sufficient privileges. Check that you're passing the service role key (not the anon key) via --source-service-role-key or --target-service-role-key. The service role key for the destination must have full administrative permission.

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

Either install the missing extension in the destination database, or remove it from the source database if it's no longer needed.

How do I resolve relation 'test_id_seq' already exists?

This sequence conflict happens when destination tables already have data. Use a safer cleanup policy:

./supabase-cli migrate-project ... --preserve-extra-tables=true --allow-truncate=true

How do I handle special characters in a connection string?

Store credentials in environment variables — this is the simplest approach and avoids escaping entirely. If you must pass the URL directly on the command line, percent-encode any special characters: