使用 CSV 檔案匯出及匯入

本頁說明如何使用 CSV 檔案,將資料匯出及匯入 Cloud SQL 執行個體。

事前準備

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

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

  • 確認 CSV 檔案包含預期資料,且格式正確無誤。CSV 檔案的每一列資料欄位必須有一行。
  • 請遵循匯出及匯入資料的最佳做法

從 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 角色的相關說明,請參閱「身分與存取權管理」。

從 PostgreSQL 適用的 Cloud SQL 將資料匯出為 CSV 檔案

您可以將資料匯出為 CSV 格式,以供其他工具和環境使用。匯出作業會在資料庫層級進行。匯出 CSV 檔案時,您可以指定要匯出的結構定義。資料庫層級的所有結構定義都可匯出。

如要將 Cloud SQL 執行個體資料庫中的資料匯出至 Cloud Storage 值區的 CSV 檔案,請按照下列步驟操作:

控制台

  1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

    前往 Cloud SQL 執行個體

  2. 如要開啟執行個體的「總覽」頁面,請按一下執行個體名稱。
  3. 按一下 [匯出]
  4. 選取「卸載匯出作業」,允許在匯出作業進行期間執行其他作業。
  5. 在「Cloud Storage export location」(Cloud Storage 匯出位置) 部分,新增要匯出的 bucket、資料夾和檔案名稱,或按一下「Browse」(瀏覽) 尋找或建立 bucket、資料夾或檔案。

    按一下「瀏覽」

    1. 在「位置」部分,選取匯出的 Cloud Storage 值區或資料夾。
    2. 在「名稱」方塊中,新增 CSV 檔案的名稱,或從「位置」專區的清單中選取現有檔案。

      您可以使用 .gz 的副檔名 (完整副檔名為 .csv.gz) 壓縮匯出檔案。

    3. 按一下 [選取]。
  6. 在「格式」部分中,按一下「CSV」
  7. 在「Database for export」(要匯出的資料庫) 部分,從下拉式選單中選取資料庫名稱。
  8. 如果是SQL 查詢,請輸入 SQL 查詢,指定要從哪個資料表匯出資料。

    舉例來說,如要匯出 guestbook 資料庫中 entries 表格的完整內容,請輸入

    SELECT * FROM guestbook.entries;
    查詢必須指定資料庫中的資料表。您無法匯出 CSV 格式的完整資料庫。

  9. 按一下 [匯出] 即可開始匯出。
  10. 系統會開啟「匯出資料庫?」方塊,並顯示訊息,指出大型資料庫的匯出程序可能需要一小時以上。匯出期間,您只能查看執行個體的資訊,匯出作業開始後,您可以取消作業。如果現在適合開始匯出,請按一下「匯出」。否則請按一下「取消」

gcloud

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

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

  3. 找出要匯出資料的 Cloud SQL 執行個體服務帳戶。如要這麼做,請執行 gcloud sql instances describe 指令。在輸出內容中尋找 serviceAccountEmailAddress 欄位。
    gcloud sql instances describe INSTANCE_NAME
  4. 使用 gcloud storage buckets add-iam-policy-bindingstorage.objectAdmin IAM 角色授予 Cloud SQL 執行個體服務帳戶。如需設定 IAM 權限的說明,請參閱「使用 IAM 權限」。
  5. 匯出資料庫:
    gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
    --database=DATABASE_NAME \
    --offload \
    --query=SELECT_QUERY
    

    如要瞭解如何使用 export csv 指令,請參閱 sql export csv 指令參考資料頁面。

  6. 如果您不需要保留先前設定的 IAM 角色,請立即撤銷該角色。

REST v1

  1. 建立匯出的值區:
    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME
    

    這並不是必要的步驟,但我們強烈建議您這麼做,以避免開放其他資料的存取權限。

  2. 為執行個體提供值區的 legacyBucketWriter IAM 角色。如需設定 IAM 權限的相關說明,請參閱「使用 IAM 權限」。
  3. 匯出您的資料庫:

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

    • project-id:專案 ID
    • instance-id:執行個體 ID
    • bucket_name:Cloud Storage 值區名稱
    • path_to_csv_file:CSV 檔案的路徑
    • database_name:Cloud SQL 執行個體內的資料庫名稱
    • offload:啟用無伺服器匯出。設為 true 即可使用無伺服器匯出功能。
    • select_query:用於匯出的 SQL 查詢 (選用)
    • escape_character:應顯示在需要逸出的資料字元前。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「22」代表雙引號。(選填)
    • quote_character:用來括住字串資料類型資料欄值的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「22」代表雙引號。(選填)
    • fields_terminated_by:用來分割資料欄值的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「2C」代表逗號。(選填)
    • lines_terminated_by:用來分割行記錄的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「0A」代表新行。(選填)

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/export

    JSON 要求主體:

    {
     "exportContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "databases": "database_name",
          "offload": true | false
          "csvExportOptions":
           {
               "selectQuery":"select_query",
               "escapeCharacter":"escape_character",
               "quoteCharacter":"quote_character",
               "fieldsTerminatedBy":"fields_terminated_by",
               "linesTerminatedBy":"lines_terminated_by"
           }
       }
    }
    

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

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

    您必須使用 databases 屬性指定一個資料庫,且如果選取查詢指定了資料庫,則必須是同一個資料庫。

  4. 如果您不需要保留先前設定的 IAM 權限,請立即予以移除。
如需此要求的完整參數清單,請參閱執行個體:匯出頁面。

REST v1beta4

  1. 建立匯出的值區:
    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME

    這並不是必要的步驟,但我們強烈建議您這麼做,以避免開放其他資料的存取權限。

  2. 為執行個體提供值區的 storage.objectAdmin IAM 角色。如需設定 IAM 權限的相關說明,請參閱「使用 IAM 權限」。
  3. 匯出您的資料庫:

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

    • project-id:專案 ID
    • instance-id:執行個體 ID
    • bucket_name:Cloud Storage 值區名稱
    • path_to_csv_file:CSV 檔案的路徑
    • database_name:Cloud SQL 執行個體內的資料庫名稱
    • offload:啟用無伺服器匯出。設為 true 即可使用無伺服器匯出功能。
    • select_query:用於匯出的 SQL 查詢 (選用)
    • escape_character:應顯示在需要逸出的資料字元前。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「22」代表雙引號。(選填)
    • quote_character:用來括住字串資料類型資料欄值的字元。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「22」代表雙引號。(選填)
    • fields_terminated_by:用來分隔資料欄值的字元,這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「2C」代表逗號。(選填)
    • lines_terminated_by:用來分割行記錄的字元。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「0A」代表新行。(選填)

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    JSON 要求主體:

    {
     "exportContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "databases": "database_name",
          "offload": true | false
          "csvExportOptions":
           {
               "selectQuery": "select_query",
               "escapeCharacter":  "escape_character",
               "quoteCharacter": "quote_character",
               "fieldsTerminatedBy": "fields_terminated_by",
               "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    

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

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

    您必須使用 databases 屬性指定一個資料庫,且如果選取查詢指定了資料庫,則必須是同一個資料庫。

  4. 如果您不需要保留先前設定的 IAM 角色,請立即撤銷該角色。
如需此要求的完整參數清單,請參閱執行個體:匯出頁面。

自訂 CSV 匯出檔案的格式

您可以使用 gcloud 或 REST API 自訂 CSV 檔案格式。匯出時,您可以指定下列格式選項:

CSV 選項 預設值 gcloud 標記 REST API 屬性 說明
Esc 鍵

"5C"

檔案分隔符的 ASCII 十六進位碼。

--escape escapeCharacter

需要逸出資料字元前的字元。

僅適用於 MySQL 和 PostgreSQL。

引述

"22"

雙引號的 ASCII 十六進位碼。

--quote quoteCharacter

用來括住字串資料類型資料欄值的字元。

僅適用於 MySQL 和 PostgreSQL。

欄位分隔符號

"2C"

逗號的 ASCII 十六進位碼。

--fields-terminated-by fieldsTerminatedBy

用來分隔資料欄值的字元。

僅適用於 MySQL 和 PostgreSQL。

換行字元

"0A"

換行的 ASCII 十六進位碼。

--lines-terminated-by linesTerminatedBy

用來分割行記錄的字元。

僅適用於 MySQL。

舉例來說,使用所有這些引數的 gcloud 指令可能如下所示:

gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--offload \
--query=SELECT_QUERY \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

對等的 REST API 要求主體如下所示:

{
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": "DATABASE_NAME",
      "offload": true,
      "csvExportOptions":
       {
           "selectQuery": "SELECT_QUERY",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

根據預設,CSV 匯出作業會建立標準 CSV 輸出內容。如果需要比 Cloud SQL 提供的更多選項,您可以在 psql 用戶端中使用下列陳述式:

      \copy [table_name] TO '[csv_file_name].csv' WITH
          (FORMAT csv, ESCAPE '[escape_character]', QUOTE '[quote_character]',
          DELIMITER '[delimiter_character]', ENCODING 'UTF8', NULL '[null_marker_string]');

將資料匯入 PostgreSQL 適用的 Cloud SQL

匯入 PostgreSQL 適用的 Cloud SQL 時所需的角色和權限

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

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

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

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

從 CSV 檔案將資料匯入 PostgreSQL 適用的 Cloud SQL

  • 您要匯入的目標資料庫與資料表必須存在於您的 Cloud SQL 執行個體上。如需建立資料庫的說明,請參閱建立資料庫
  • CSV 檔案必須符合CSV 檔案格式規定

CSV 檔案格式規定

CSV 檔案的每一列資料必須有一行,並使用以逗號分隔的欄位。

使用 CSV 檔案將資料匯入 Cloud SQL 執行個體:

控制台

  1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

    前往 Cloud SQL 執行個體

  2. 如要開啟執行個體的「總覽」頁面,請按一下執行個體名稱。
  3. 按一下「匯入」
  4. 在「選擇匯入資料的來源檔案」部分,輸入要用於匯入作業的 bucket 和 CSV 檔案路徑。如要瀏覽檔案:
    1. 按一下「瀏覽」
    2. 在「位置」部分,按兩下清單中的 bucket 名稱。
    3. 在清單中選取檔案。
    4. 按一下 [選取]。

    您可以匯入壓縮 (.gz) 或未壓縮 (.csv) 的檔案。

  5. 在「格式」部分中,選取「CSV」
  6. 在您要匯入 CSV 檔案的目標 Cloud SQL 執行個體中,指定「Database」(資料庫)與「Table」(資料表)
  7. 您也可以指定使用者,進行匯入作業。
  8. 按一下 [Import] (匯入) 即可開始匯入。

gcloud

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

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

  3. 將 CSV 檔案中的資料上傳至值區。
  4. 找出要匯出資料的 Cloud SQL 執行個體服務帳戶。如要這麼做,請使用執行個體名稱執行 gcloud sql instances describe 指令。在輸出內容中尋找 serviceAccountEmailAddress 欄位。
    gcloud sql instances describe INSTANCE_NAME
  5. 複製 serviceAccountEmailAddress 欄位。
  6. 使用 gcloud storage buckets add-iam-policy-bindingstorage.objectAdmin 身分與存取權管理角色授予 Cloud SQL 執行個體服務帳戶。如需設定 IAM 權限的說明,請參閱使用 IAM 權限
  7. 匯入檔案:
    gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
    --database=DATABASE_NAME \
    --table=TABLE_NAME

    如要瞭解如何使用 import csv 指令,請參閱 sql import csv 指令參考資料頁面。

  8. 如果您不需要保留先前設定的 IAM 權限,請使用 gcloud storage buckets remove-iam-policy-binding 移除這些權限。

REST v1

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

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

  3. 為執行個體提供值區的 legacyBucketWriterobjectViewer IAM 角色。如需設定 IAM 權限的說明,請參閱使用 IAM 權限
  4. 匯入檔案: <

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

    • project-id:專案 ID
    • instance-id:執行個體 ID
    • bucket_name:Cloud Storage 值區名稱
    • path_to_csv_file:CSV 檔案的路徑
    • database_name:Cloud SQL 執行個體內的資料庫名稱
    • table_name:資料庫表格名稱
    • escape_character:應顯示在需要逸出的資料字元前。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「22」代表雙引號。(選填)
    • quote_character:用來括住字串資料類型資料欄值的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「22」代表雙引號。(選填)
    • fields_terminated_by:用來分割資料欄值的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「2C」代表逗號。(選填)
    • lines_terminated_by:用來分割行記錄的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說,「0A」代表新行。(選填)

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/import

    JSON 要求主體:

    {
     "importContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "database": "database_name",
          "csvImportOptions":
           {
             "table": "table_name",
             "escapeCharacter": "escape_character",
             "quoteCharacter": "quote_character",
             "fieldsTerminatedBy": "fields_terminated_by",
             "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    
    

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

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

    如需此要求的完整參數清單,請參閱 instances:import 頁面。
  5. 如果您不需要保留先前設定的 IAM 權限,請移除這些權限。

REST v1beta4

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

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

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

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

    • project-id:專案 ID
    • instance-id:執行個體 ID
    • bucket_name:Cloud Storage 值區名稱
    • path_to_csv_file:CSV 檔案的路徑
    • database_name:Cloud SQL 執行個體內的資料庫名稱
    • table_name:資料庫表格名稱
    • escape_character:應顯示在需要逸出的資料字元前。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「22」代表雙引號。(選填)
    • quote_character:用來括住字串資料類型資料欄值的字元。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「22」代表雙引號。(選填)
    • fields_terminated_by:用來分割資料欄值的字元。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「2C」代表逗號。(選填)
    • lines_terminated_by:用來分割行記錄的字元。這個引數的值必須採用 ASCII 十六進位格式。舉例來說,「0A」代表新行。(選填)

    HTTP 方法和網址:

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/import

    JSON 要求主體:

    {
     "importContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "database": "database_name",
          "csvImportOptions":
           {
             "table": "table_name",
             "escapeCharacter": "escape_character",
             "quoteCharacter": "quote_character",
             "fieldsTerminatedBy": "fields_terminated_by",
             "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    
    

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

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

    如需此要求的完整參數清單,請參閱 instances:import 頁面。
  5. 如果您不需要保留先前設定的 IAM 權限,請移除這些權限。

自訂 PostgreSQL 適用的 Cloud SQL 的 CSV 檔案格式

您可以使用 gcloud 或 REST API 自訂 CSV 檔案格式。

以下是 gcloud 指令的範例:

gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

對等的 REST API 要求主體如下所示:

{
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": "DATABASE_NAME",
      "csvImportOptions":
       {
           "table": "TABLE_NAME",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

如果看到類似 ERROR_RDBMS 的錯誤,請確認該資料夾確實存在。如果資料表存在,請確認您對該值區擁有正確的權限。如需設定 Cloud Storage 中存取權控管的說明,請參閱「 建立及管理存取權控管清單」。

如要瞭解如何建立該工作的基礎 REST API 要求,請參閱 instances:import 頁面中的 APIs Explorer

後續步驟