AnalyticDB：如何遷移Supabase專案

遷移路徑

• 從Supabase Cloud遷移至AnalyticDB Supabase。

• 從自託管Supabase專案遷移至AnalyticDB Supabase。

• AnalyticDB Supabase專案之間遷移。

遷移內容

• 資料庫模式：包括Schema、表結構、函數和觸發器等。

• 資料庫資料：包括使用者資料、auth資料及其他系統資料。

• PostgreSQL擴充：自動在目標專案安裝所需外掛程式。

• 儲存物件 (Storage)：儲存桶（Buckets）和其中的檔案。

• 邊緣函數 (Edge Functions)：函數代碼及其相關配置。

• 角色與許可權：資料庫的使用者和使用權限設定。

必選參數

• 源環境配置

  • Supabase Cloud源配置

    --source-project-ref string         # 源專案引用ID (必需)
    --source-anon-key string            # 源專案匿名密鑰 (必需)
    --source-service-role-key string    # 源專案服務角色密鑰 (必需)

  • 自託管Supabase專案或AnalyticDB Supabase

    --source-api-url string             # 源API URL (必需)
    --source-anon-key string            # 源專案匿名密鑰 (必需)
    --source-service-role-key string    # 源專案服務角色密鑰 (必需)
    --source-database-url string        # 來源資料庫URL (必需) 且需要 percent-encoded

• 目標環境配置

  --target-api-url string             # 目標API URL(必需)
  --target-anon-key string            # 目標專案匿名密鑰 (必需) 
  --target-service-role-key string    # 目標專案服務角色密鑰 (必需)
  --target-database-url string        # 目標資料庫URL(必需)且需要 percent-encoded

選擇性參數

• Supabase Cloud源配置

  --source-database-url string        # 來源資料庫URL (可選) 需要 percent-encoded

• 遷移內容

  --include-data                     # 包含資料庫資料（預設：true）
  --include-storage                  # 包含儲存物件（預設：true）
  --include-functions                # 包含Edge Functions（預設：true）
  --include-system-data              # 包含系統模組資料（預設：true）

• 執行選項

  --use-local-exec                   # 使用本地執行器，不依賴Docker容器，需要本地按轉pgdump等工具
  --concurrency int                  # 並行作業數（預設：2）
  --dry-run                          # 預覽模式，不執行實際遷移
  --resume-from string               # 從指定步驟恢複（database|storage|functions）

• 安全選項

  重要

  使用--allow-truncate參數時，請確保源端和目標端配置正確，防止誤操作清理源庫資料。

  --allow-truncate                  # 允許清理表資料（預設：false）
  --preserve-extra-tables           # 保留目標庫額外表（預設：true）

步驟一：擷取專案資訊並配置環境變數

1. 擷取源端配置資訊。

   以Supabase Cloud為例，需從專案設定頁面擷取以下資訊。

   • Project Ref：20字元的專案ID。

     • 訪問 Supabase 控制台。

     • 單擊源端專案，查看URL（例如https://supabase.com/dashboard/project/qeqfhfoebrtkbmwd****），URL末尾即為Project Ref（例如qeqfhfoebrtkbmwd****）。

   • Anon Key：匿名密鑰（以eyJ開頭）。

   • Service Role Key：服務角色密鑰（以eyJ開頭），需要具備讀取所有資料的許可權。

   • Database URL（可選）：PostgreSQL連接字串。

     單擊源端專案頁面上方connect，切換到Connection String頁簽下，Method選擇Transaction pooler。

     

2. 擷取目標端AnalyticDB Supabase配置資訊。具體操作，請參見擷取API Keys。

   • API URL：完整的API地址（如 https://your-domain.supabase.opentrust.net）。

   • Anon Key：目標環境的匿名密鑰。

   • Service Role Key：目標環境的服務角色密鑰，需要具備完整的系統管理權限。

   • Database URL：PostgreSQL連接字串，目標資料庫使用者需要建立表、外掛程式等許可權。

3. （可選）建議將專案資訊配置到環境變數中，避免在命令列中暴露敏感資訊。

   • 從Supabase Cloud遷移至AnalyticDB Supabase

     # 建立設定檔
     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
     
     # 載入環境變數
     source migration.env

   • 從自託管Supabase或AnalyticDB Supabase遷移至AnalyticDB Supabase

     # 建立設定檔
     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
     
     # 載入環境變數
     source migration.env

步驟二：下載遷移工具並登入

1. 請根據作業系統和架構，下載對應的supabase-cli工具。後續執行相關命令時，請將supabase-cli替換為下載的cli工具名稱。

   • 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. 執行以下命令，並根據提示資訊完成登入。

   ./supabase-cli login

步驟三：（可選）預覽遷移

• 從Supabase Cloud遷移至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

• 從自託管Supabase或AnalyticDB Supabase遷移至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

步驟四：遷移Supabase專案

串連來源資料庫報錯“connections refused”，如何解決？

使用以下命令檢查網路連接。

# 檢查網路連接
ping db.your-project-ref.supabase.co

# 檢查資料庫URL格式
# 正確格式：postgres://postgres:password@host:port/database

許可權報錯“permission denied for schema auth”，如何解決？

• 確保使用的是Service role key，而不是Anon key。

• 檢查密鑰是否有足夠的許可權，許可權要求請參見前提條件。

• 確認目標資料庫使用者具有管理員權限。

報錯“外掛程式 xxx 在目標資料庫中不可用”，如何解決？

安裝缺失的外掛程式，或在來源資料庫中移除不必要的外掛程式。

序列衝突報錯“relation "test_id_seq" already exists”，如何解決？

參考以下命令：

# 使用更安全的表清理策略
supabase migrate-project ... --preserve-extra-tables=true --allow-truncate=true

資料庫連接串中存在特殊字元，如何處理？

建議您將專案配置到環境變數中。如果未配置環境變數，則需對特殊字元轉義處理，轉義規則如下：

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