並行匯出及匯入檔案

本頁說明如何平行匯出及匯入 Cloud SQL 執行個體中的檔案。

事前準備

開始匯出或匯入作業前,請先完成下列事項:

  • 確認資料庫有足夠的可用空間。
  • 匯出和匯入作業會使用資料庫資源,但除非執行個體資源不足,否則不會干擾一般資料庫作業。

  • 請遵循匯出及匯入資料的最佳做法
  • 完成匯入作業後,請驗證結果。

從 PostgreSQL 適用的 Cloud SQL 將資料平行匯出至多個檔案

以下各節說明如何將 PostgreSQL 適用的 Cloud SQL 資料平行匯出至多個檔案。

從 PostgreSQL 適用的 Cloud SQL 匯出資料至多個檔案時,所需的角色和權限

如要將資料從 Cloud SQL 匯出至 Cloud Storage,發起匯出作業的使用者必須具備下列其中一個角色:

此外,Cloud SQL 執行個體的服務帳戶必須具備下列其中一個角色:

  • storage.objectAdmin身分與存取權管理 (IAM) 角色
  • 自訂角色,包括下列權限:
    • storage.objects.create
    • storage.objects.list (僅適用於平行匯出檔案)
    • storage.objects.delete (僅適用於平行匯出檔案)

如需 IAM 角色的相關說明,請參閱「身分與存取權管理」。

將資料平行匯出至多個檔案

您可以從 Cloud SQL 中的多個檔案並行匯出資料至 Cloud Storage。如要執行這項操作,請使用 pg_dump 公用程式和 --jobs 選項。

如果您打算將資料匯入 Cloud SQL,請按照「從外部資料庫伺服器匯出資料」一文中的操作說明,確保檔案格式符合 Cloud SQL 的要求。

gcloud

如要從 Cloud SQL 平行匯出資料至多個檔案,請完成下列步驟:

  1. 建立 Cloud Storage bucket
  2. 如要找出要匯出檔案的 Cloud SQL 執行個體服務帳戶,請使用
    gcloud sql instances describe 指令。
    gcloud sql instances describe INSTANCE_NAME
  3. INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

    在輸出中,找出與 serviceAccountEmailAddress 欄位相關聯的值。

  4. 如要將 storage.objectAdmin IAM 角色授予服務帳戶,請使用 gcloud storage buckets add-iam-policy-binding 指令。如需設定 IAM 權限的說明,請參閱「使用 IAM 權限」。
  5. 如要從 Cloud SQL 匯出資料至多個檔案,請使用 gcloud sql export sql 指令:
    gcloud sql export sql INSTANCE_NAME gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME \
    --offload \
    --parallel \
    --threads=THREAD_NUMBER \
    --database=DATABASE_NAME \
    --table=TABLE_EXPRESSION
    

    請將下列項目改為對應的值:

    • INSTANCE_NAME:要從中平行匯出檔案的 Cloud SQL 執行個體名稱。
    • BUCKET_NAME:Cloud Storage bucket 的名稱。
    • BUCKET_PATH:儲存匯出檔案的 bucket 路徑。
    • FOLDER_NAME:儲存匯出檔案的資料夾。
    • THREAD_NUMBER:Cloud SQL 用於平行匯出檔案的執行緒數量。舉例來說,如要同時平行匯出三個檔案,請將這個參數的值指定為 3
    • DATABASE_NAME (選用):Cloud SQL 執行個體內的資料庫名稱,用於匯出資料。如果未指定資料庫,Cloud SQL 會匯出執行個體中的所有使用者資料庫。詳情請參閱「匯出整個執行個體」一文。
    • TABLE_EXPRESSION:要從指定資料庫匯出的資料表。

    export sql 指令不含觸發條件或預存程序,但包含檢視畫面。如要匯出觸發程序或預存程序,請使用單一執行緒進行匯出。這個對話串使用 pg_dump 工具。

    匯出完成後,您應該會在 Cloud Storage 值區的資料夾中,看到 pg_dump 目錄格式的檔案。

  6. 如果您不需要「從 PostgreSQL 適用的 Cloud SQL 匯出資料的必要角色和權限」中設定的 IAM 角色,請撤銷該角色。

REST v1

如要從 Cloud SQL 平行匯出資料至多個檔案,請完成下列步驟:

  1. 建立 Cloud Storage bucket:
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    
    進行下列替換:
    • BUCKET_NAME:值區名稱,必須遵守命名要求。例如:my-bucket
    • PROJECT_NAME:包含您要建立的 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • LOCATION_NAME:您要儲存匯出檔案的值區位置。例如:us-east1
  2. 為執行個體提供值區的 legacyBucketWriter IAM 角色。如需設定 IAM 權限的相關說明,請參閱「使用 IAM 權限」。
  3. 從 Cloud SQL 匯出資料至多個檔案 (平行作業):

    使用任何要求資料之前,請先替換以下項目:

    • PROJECT_NAME:包含您所建立 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • INSTANCE_NAME:要平行匯出檔案的 Cloud SQL 執行個體名稱。
    • BUCKET_NAME:Cloud Storage bucket 的名稱。
    • BUCKET_PATH:儲存匯出檔案的 bucket 路徑。
    • FOLDER_NAME:儲存匯出檔案的資料夾。
    • DATABASE_NAME:Cloud SQL 執行個體內的資料庫名稱,匯出作業會從該資料庫進行。如要從執行個體匯出所有使用者資料庫,請從要求主體中移除這個欄位。
    • THREAD_NUMBER:Cloud SQL 用於平行匯出檔案的執行緒數量。舉例來說,如要同時平行匯出三個檔案,請將這個參數的值指定為 3

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_NAME/instances/INSTANCE_NAME/export

    JSON 要求主體:

    {
     "exportContext":
       {
          "fileType": "SQL",
          "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
          "databases": ["DATABASE_NAME"],
          "offload": [TRUE|FALSE],
          "sqlExportOptions": {
            "parallel": [TRUE|FALSE],
            "threads": [THREAD_NUMBER]
           }
       }
    }
    

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

  4. 匯出完成後,您應該會在 Cloud Storage 值區的資料夾中,看到 pg_dump 目錄格式的檔案。

  5. 如果您不需要「從 PostgreSQL 適用的 Cloud SQL 匯出資料的必要角色和權限」中設定的 IAM 角色,請撤銷該角色。
如需此要求的完整參數清單,請參閱 Cloud SQL Admin API 頁面。

REST v1beta4

如要從 Cloud SQL 平行匯出資料至多個檔案,請完成下列步驟:

  1. 建立 Cloud Storage bucket:
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    進行下列替換:
    • BUCKET_NAME:值區名稱,必須遵守命名要求。例如:my-bucket
    • PROJECT_NAME:包含您要建立的 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • LOCATION_NAME:您要儲存匯出檔案的值區位置。例如:us-east1
  2. 為執行個體提供值區的 storage.objectAdmin IAM 角色。如需設定 IAM 權限的相關說明,請參閱「使用 IAM 權限」。
  3. 從 Cloud SQL 匯出資料至多個檔案 (平行作業):

    使用任何要求資料之前,請先替換以下項目:

    • PROJECT_NAME:包含您所建立 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • INSTANCE_NAME:要平行匯出檔案的 Cloud SQL 執行個體名稱。
    • BUCKET_NAME:Cloud Storage bucket 的名稱。
    • BUCKET_PATH:儲存匯出檔案的 bucket 路徑。
    • FOLDER_NAME:儲存匯出檔案的資料夾。
    • DATABASE_NAME:Cloud SQL 執行個體中的資料庫名稱,匯出作業會從該資料庫進行。如要從執行個體匯出所有使用者資料庫,請從要求主體中移除這個欄位。
    • THREAD_NUMBER:Cloud SQL 用於平行匯出檔案的執行緒數量。舉例來說,如要同時平行匯出三個檔案,請將這個參數的值指定為 3

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_NAME/instances/INSTANCE_NAME/export

    JSON 要求主體:

    {
     "exportContext":
       {
          "fileType": "SQL",
          "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
          "databases": ["DATABASE_NAME"],
          "offload": [TRUE|FALSE],
          "sqlExportOptions": {
            "parallel": [TRUE|FALSE],
            "threads": [THREAD_NUMBER]
           }
       }
    }
    

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

  4. 匯出完成後,您應該會在 Cloud Storage 值區的資料夾中,看到 pg_dump 目錄格式的檔案。

  5. 如果您不需要「從 PostgreSQL 適用的 Cloud SQL 匯出資料的必要角色和權限」中設定的 IAM 角色,請撤銷該角色。
如需此要求的完整參數清單,請參閱 Cloud SQL Admin API 頁面。

匯出及匯入整個執行個體

您可以使用目錄格式的平行匯出作業,匯出或匯入整個執行個體中的所有使用者資料庫。

如要匯出或匯入整個執行個體,請使用「平行匯出」和「平行匯入」章節中顯示的相同指令,並分別移除 databasesdatabase 欄位。如果未指定資料庫,Cloud SQL 會對執行個體中的所有使用者資料庫執行平行匯出或匯入作業。這不包括系統資料庫,以及用於管理內部作業的 Cloud SQL 資料庫。

以目錄格式平行匯出至 Cloud Storage 時,匯出作業成功完成後,與每個資料庫相關聯的資料會儲存在以每個資料庫命名的子目錄中,類似於下列情況:

gs://example-bucket/test-folder/
    |---- postgres/
    |    |---- 3929.dat.gz (table data file)
    |    |---- toc.dat (metadata file)
    |
    |---- second_database/
    |    |---- 3930.dat.gz
    |    |---- 3931.dat.gz
    |    |---- toc.dat

如要為整個執行個體執行平行匯入作業,且執行個體的檔案是在 Cloud SQL 外部建立,則必須使用這個子目錄結構,作業才能順利完成。

如果系統偵測到整個執行個體傾印結構,就會忽略 API 中指定的匯入資料庫。這項作業會從目錄名稱偵測整個執行個體的結構。

您無法匯出或匯入其他檔案格式的整個執行個體。

您無法將整個執行個體匯出或匯入為單一 SQL 檔案或 CSV 檔案。

將多個檔案中的資料平行匯入 PostgreSQL 適用的 Cloud SQL

以下各節說明如何從多個檔案平行匯入資料至 PostgreSQL 適用的 Cloud SQL。

從多個檔案平行匯入資料至 PostgreSQL 適用的 Cloud SQL 時,所需的角色和權限

如要將資料從 Cloud Storage 匯入 Cloud SQL,發起匯入作業的使用者必須具備下列其中一個角色:

此外,Cloud SQL 執行個體的服務帳戶必須具備下列其中一個角色:

  • storage.objectAdmin IAM 角色
  • 自訂角色,包括下列權限:
    • storage.objects.get
    • storage.objects.list (僅限平行匯入檔案)

如需 IAM 角色的相關說明,請參閱「身分與存取權管理」。

將資料匯入 PostgreSQL 適用的 Cloud SQL

您可以從 Cloud Storage 中多個檔案平行匯入資料至資料庫。如要執行這項操作,請使用 pg_restore 公用程式和 --jobs 選項。

gcloud

如要將多個檔案中的資料平行匯入 Cloud SQL,請完成下列步驟:

  1. 建立 Cloud Storage 值區
  2. 將檔案上傳至值區。

    如需將檔案上傳至值區的說明,請參閱「從檔案上傳物件」。

  3. 如要找出要匯入檔案的 Cloud SQL 執行個體服務帳戶,請使用
    gcloud sql instances describe 指令。
    gcloud sql instances describe INSTANCE_NAME
  4. INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

    在輸出中,找出與 serviceAccountEmailAddress 欄位相關聯的值。

  5. 如要將 storage.objectAdmin IAM 角色授予服務帳戶,請使用 gcloud storage buckets add-iam-policy-binding 公用程式。如需設定 IAM 權限的說明,請參閱「使用 IAM 權限」一文。
  6. 如要將多個檔案中的資料平行匯入 Cloud SQL,請使用 gcloud sql import sql 指令:
    gcloud sql import sql INSTANCE_NAME gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME \
    --parallel \ 
    --threads=THREAD_NUMBER \
    --database=DATABASE_NAME
    

    請將下列項目改為對應的值:

    • INSTANCE_NAME:要平行匯入檔案的 Cloud SQL 執行個體名稱。
    • BUCKET_NAME:Cloud Storage bucket 的名稱。
    • BUCKET_PATH:儲存匯入檔案的 bucket 路徑。
    • FOLDER_NAME:儲存匯入檔案的資料夾。
    • THREAD_NUMBER:Cloud SQL 用於平行匯入檔案的執行緒數量。舉例來說,如要同時平行匯入三個檔案,請將這個參數的值指定為 3
    • DATABASE_NAME:Cloud SQL 執行個體內的資料庫名稱,匯入作業會從該資料庫進行。您只能指定一個資料庫。

    如果指令傳回類似 ERROR_RDBMS 的錯誤,請重新檢視權限,因為這個錯誤通常是因權限問題所致。

  7. 如果您不需要將資料匯入 PostgreSQL 適用的 Cloud SQL 時所需的角色和權限,請使用 gcloud storage buckets remove-iam-policy-binding 移除這些權限。

REST v1

如要將多個檔案中的資料平行匯入 Cloud SQL,請完成下列步驟:

  1. 建立 Cloud Storage bucket:
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    
    進行下列替換:
    • BUCKET_NAME:值區名稱,必須遵守命名要求。例如:my-bucket
    • PROJECT_NAME:包含您要建立的 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • LOCATION_NAME:要儲存匯入檔案的值區位置。例如:us-east1
  2. 將檔案上傳至值區。

    如需將檔案上傳至值區的說明,請參閱「從檔案上傳物件」。

  3. 為執行個體提供值區的 storage.objectAdmin IAM 角色。如需設定 IAM 權限的說明,請參閱使用 IAM 權限
  4. 將多個檔案中的資料平行匯入 Cloud SQL:

    使用任何要求資料之前,請先替換以下項目:

    • PROJECT_NAME:包含您所建立 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • INSTANCE_NAME:要平行匯入檔案的 Cloud SQL 執行個體名稱。
    • BUCKET_NAME:Cloud Storage bucket 的名稱。
    • BUCKET_PATH:儲存匯入檔案的 bucket 路徑。
    • FOLDER_NAME:儲存匯入檔案的資料夾。
    • DATABASE_NAME:Cloud SQL 執行個體內的資料庫名稱,匯入作業會從該資料庫進行。您只能指定一個資料庫。
    • THREAD_NUMBER:Cloud SQL 用於平行匯入檔案的執行緒數量。舉例來說,如要同時平行匯入三個檔案,請將這個參數的值指定為 3

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_NAME/instances/INSTANCE_NAME/import

    JSON 要求主體:

    
    {
      "importContext":
        {
           "fileType": "SQL",
           "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
           "databases": ["DATABASE_NAME"],
           "offload": [TRUE|FALSE],
           "sqlImportOptions": {
             "parallel": [TRUE|FALSE],
             "clean": [TRUE|FALSE],
             "ifExists": [TRUE|FALSE],
             "threads": [THREAD_NUMBER]
            }
        }
     }
    

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

    如要使用不同的使用者匯入,請指定 importContext.importUser 屬性。

    如需此要求的完整參數清單,請參閱 Cloud SQL Admin API 頁面。
  5. 如果您不需要將資料匯入 PostgreSQL 適用的 Cloud SQL 時所需的角色和權限,請使用 gcloud storage buckets remove-iam-policy-binding 移除這些權限。

REST v1beta4

如要將多個檔案中的資料平行匯入 Cloud SQL,請完成下列步驟:

  1. 建立 Cloud Storage bucket:
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    
    進行下列替換:
    • BUCKET_NAME:值區名稱,必須遵守命名要求。例如:my-bucket
    • PROJECT_NAME:包含您要建立的 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • LOCATION_NAME:要儲存匯入檔案的值區位置。例如:us-east1
  2. 將檔案上傳至值區。

    如需將檔案上傳至值區的說明,請參閱「從檔案上傳物件」。

  3. 為執行個體提供值區的 storage.objectAdmin IAM 角色。如需設定 IAM 權限的說明,請參閱使用 IAM 權限
  4. 將多個檔案中的資料平行匯入 Cloud SQL:

    使用任何要求資料之前,請先替換以下項目:

    • PROJECT_NAME:包含您所建立 Cloud Storage bucket 的 Google Cloud 專案名稱。
    • INSTANCE_NAME:要從中平行匯入檔案的 Cloud SQL 執行個體名稱。
    • BUCKET_NAME:Cloud Storage bucket 的名稱。
    • BUCKET_PATH:儲存匯入檔案的 bucket 路徑。
    • FOLDER_NAME:儲存匯入檔案的資料夾。
    • DATABASE_NAME:Cloud SQL 執行個體內的資料庫名稱,匯入作業會從該資料庫進行。您只能指定一個資料庫。
    • THREAD_NUMBER:Cloud SQL 用於平行匯入檔案的執行緒數量。舉例來說,如要同時平行匯入三個檔案,請將這個參數的值指定為 3

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_NAME/instances/INSTANCE_NAME/import

    JSON 要求主體:

    
     {
       "importContext":
         {
            "fileType": "SQL",
            "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
            "databases": ["DATABASE_NAME"],
            "offload": [TRUE|FALSE],
            "sqlImportOptions": {
              "parallel": [TRUE|FALSE],
              "clean": [TRUE|FALSE],
              "ifExists": [TRUE|FALSE],
              "threads": [THREAD_NUMBER]
             }
         }
      }
    

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

    如要使用不同的使用者匯入,請指定 importContext.importUser 屬性。

    如需此要求的完整參數清單,請參閱 Cloud SQL Admin API 頁面。
  5. 如果您不需要將資料匯入 PostgreSQL 適用的 Cloud SQL 時所需的角色和權限,請使用 gcloud storage buckets remove-iam-policy-binding 移除這些權限。

限制

  • 如果您從多個檔案平行匯入或匯出資料時指定過多執行緒,使用的記憶體可能會超出 Cloud SQL 執行個體的容量。如果發生這種情況,系統會顯示內部錯誤訊息。檢查執行個體的記憶體用量,並視需要增加執行個體的大小。詳情請參閱「關於執行個體設定」。

  • 執行匯出作業時,系統不支援 databasestables 欄位中的資料庫名稱或表格名稱含有半形逗號。

  • 請確認您有足夠的磁碟空間,可供下載初始傾印檔案。 否則會顯示 no space left on disk 錯誤。

  • 如果執行個體只有一個虛擬 CPU (vCPU),就無法平行匯入或匯出多個檔案。執行個體的 vCPU 數量不得少於匯入或匯出作業使用的執行緒數量,且執行緒數量至少須為 2。

  • 多執行緒 (平行) 匯入和匯出作業與單一執行緒匯入和匯出作業不相容。舉例來說,單一執行緒匯出作業產生的傾印檔案,只能透過單一執行緒匯入作業匯入。同樣地,平行匯出作業產生的傾印檔案只能透過平行匯入作業匯入。

  • pg_dump 公用程式無法將匯出的任何資料表分塊。因此,如果有一個非常大的資料表,可能會成為匯出作業速度的瓶頸。

後續步驟