本頁說明如何使用 CSV 檔案,將資料匯出及匯入 Cloud SQL 執行個體。
事前準備
開始匯出或匯入作業前,請先完成下列事項:
- 確認資料庫有足夠的可用空間。
- 確認 CSV 檔案包含預期資料,且格式正確無誤。CSV 檔案的每一列資料欄位必須有一行。
- 請遵循匯出及匯入資料的最佳做法。
匯出和匯入作業會使用資料庫資源,但除非執行個體資源不足,否則不會干擾正常的資料庫作業。
從 PostgreSQL 適用的 Cloud SQL 匯出資料
從 PostgreSQL 適用的 Cloud SQL 匯出資料時所需的角色和權限
如要將資料從 Cloud SQL 匯出至 Cloud Storage,發起匯出作業的使用者必須具備下列其中一個角色:
- Cloud SQL 編輯者角色
- 自訂角色,包括下列權限:
cloudsql.instances.get
cloudsql.instances.export
此外,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 檔案,請按照下列步驟操作:
控制台
-
前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。
- 如要開啟執行個體的「總覽」頁面,請按一下執行個體名稱。
- 按一下 [匯出]。
- 選取「卸載匯出作業」,允許在匯出作業進行期間執行其他作業。
-
在「Cloud Storage export location」(Cloud Storage 匯出位置) 部分,新增要匯出的 bucket、資料夾和檔案名稱,或按一下「Browse」(瀏覽) 尋找或建立 bucket、資料夾或檔案。
按一下「瀏覽」:
- 在「位置」部分,選取匯出的 Cloud Storage 值區或資料夾。
在「名稱」方塊中,新增
CSV
檔案的名稱,或從「位置」專區的清單中選取現有檔案。您可以使用
.gz
的副檔名 (完整副檔名為.csv.gz
) 壓縮匯出檔案。- 按一下 [選取]。
- 在「格式」部分中,按一下「CSV」。
- 在「Database for export」(要匯出的資料庫) 部分,從下拉式選單中選取資料庫名稱。
-
如果是SQL 查詢,請輸入 SQL 查詢,指定要從哪個資料表匯出資料。
舉例來說,如要匯出
guestbook
資料庫中entries
表格的完整內容,請輸入 查詢必須指定資料庫中的資料表。您無法匯出 CSV 格式的完整資料庫。SELECT * FROM guestbook.entries;
- 按一下 [匯出] 即可開始匯出。
- 系統會開啟「匯出資料庫?」方塊,並顯示訊息,指出大型資料庫的匯出程序可能需要一小時以上。匯出期間,您只能查看執行個體的資訊,匯出作業開始後,您可以取消作業。如果現在適合開始匯出,請按一下「匯出」。否則請按一下「取消」。
gcloud
- 建立 Cloud Storage 值區。
上傳檔案至值區。
如需將檔案上傳至值區的說明,請參閱上傳物件。
- 找出要匯出資料的 Cloud SQL 執行個體服務帳戶。如要這麼做,請執行
gcloud sql instances describe
指令。在輸出內容中尋找serviceAccountEmailAddress
欄位。gcloud sql instances describe INSTANCE_NAME
- 使用
gcloud storage buckets add-iam-policy-binding
將storage.objectAdmin
IAM 角色授予 Cloud SQL 執行個體服務帳戶。如需設定 IAM 權限的說明,請參閱「使用 IAM 權限」。 - 匯出資料庫:
gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \ --database=DATABASE_NAME \ --offload \ --query=SELECT_QUERY
如要瞭解如何使用
export csv
指令,請參閱sql export csv
指令參考資料頁面。 - 如果您不需要保留先前設定的 IAM 角色,請立即撤銷該角色。
REST v1
- 建立匯出的值區:
gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME
這並不是必要的步驟,但我們強烈建議您這麼做,以避免開放其他資料的存取權限。
- 為執行個體提供值區的
legacyBucketWriter
IAM 角色。如需設定 IAM 權限的相關說明,請參閱「使用 IAM 權限」。 -
匯出您的資料庫:
使用任何要求資料之前,請先替換以下項目:
- 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
屬性指定一個資料庫,且如果選取查詢指定了資料庫,則必須是同一個資料庫。 - 如果您不需要保留先前設定的 IAM 權限,請立即予以移除。
REST v1beta4
- 建立匯出的值區:
gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME
這並不是必要的步驟,但我們強烈建議您這麼做,以避免開放其他資料的存取權限。
- 為執行個體提供值區的
storage.objectAdmin
IAM 角色。如需設定 IAM 權限的相關說明,請參閱「使用 IAM 權限」。 -
匯出您的資料庫:
使用任何要求資料之前,請先替換以下項目:
- 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
屬性指定一個資料庫,且如果選取查詢指定了資料庫,則必須是同一個資料庫。 - 如果您不需要保留先前設定的 IAM 角色,請立即撤銷該角色。
自訂 CSV 匯出檔案的格式
您可以使用 gcloud
或 REST API 自訂 CSV 檔案格式。匯出時,您可以指定下列格式選項:
CSV 選項 | 預設值 | gcloud 標記 | REST API 屬性 | 說明 |
---|---|---|---|---|
Esc 鍵 |
檔案分隔符的 ASCII 十六進位碼。 |
--escape |
escapeCharacter |
需要逸出資料字元前的字元。 僅適用於 MySQL 和 PostgreSQL。 |
引述 |
雙引號的 ASCII 十六進位碼。 |
--quote |
quoteCharacter |
用來括住字串資料類型資料欄值的字元。 僅適用於 MySQL 和 PostgreSQL。 |
欄位分隔符號 |
逗號的 ASCII 十六進位碼。 |
--fields-terminated-by |
fieldsTerminatedBy |
用來分隔資料欄值的字元。 僅適用於 MySQL 和 PostgreSQL。 |
換行字元 |
換行的 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 管理員角色
- 自訂角色,包括下列權限:
cloudsql.instances.get
cloudsql.instances.import
此外,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 執行個體:
控制台
-
前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。
- 如要開啟執行個體的「總覽」頁面,請按一下執行個體名稱。
- 按一下「匯入」。
- 在「選擇匯入資料的來源檔案」部分,輸入要用於匯入作業的 bucket 和 CSV 檔案路徑。如要瀏覽檔案:
- 按一下「瀏覽」。
- 在「位置」部分,按兩下清單中的 bucket 名稱。
- 在清單中選取檔案。
- 按一下 [選取]。
您可以匯入壓縮 (
.gz
) 或未壓縮 (.csv
) 的檔案。 - 在「格式」部分中,選取「CSV」。
- 在您要匯入 CSV 檔案的目標 Cloud SQL 執行個體中,指定「Database」(資料庫)與「Table」(資料表)。
- 您也可以指定使用者,進行匯入作業。
- 按一下 [Import] (匯入) 即可開始匯入。
gcloud
- 建立 Cloud Storage 值區。
上傳檔案至值區。
如需將檔案上傳至值區的說明,請參閱上傳物件。
- 將 CSV 檔案中的資料上傳至值區。
- 找出要匯出資料的 Cloud SQL 執行個體服務帳戶。如要這麼做,請使用執行個體名稱執行
gcloud sql instances describe
指令。在輸出內容中尋找serviceAccountEmailAddress
欄位。gcloud sql instances describe INSTANCE_NAME
- 複製 serviceAccountEmailAddress 欄位。
- 使用
gcloud storage buckets add-iam-policy-binding
將storage.objectAdmin
身分與存取權管理角色授予 Cloud SQL 執行個體服務帳戶。如需設定 IAM 權限的說明,請參閱使用 IAM 權限。 - 匯入檔案:
gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \ --database=DATABASE_NAME \ --table=TABLE_NAME
如要瞭解如何使用
import csv
指令,請參閱sql import csv
指令參考資料頁面。 - 如果您不需要保留先前設定的 IAM 權限,請使用
gcloud storage buckets remove-iam-policy-binding
移除這些權限。
REST v1
- 建立 Cloud Storage 值區。
上傳檔案至值區。
如需將檔案上傳至值區的說明,請參閱上傳物件。
- 為執行個體提供值區的
legacyBucketWriter
和objectViewer
IAM 角色。如需設定 IAM 權限的說明,請參閱使用 IAM 權限。 - 匯入檔案:
<
使用任何要求資料之前,請先替換以下項目:
- 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 頁面。 - 如果您不需要保留先前設定的 IAM 權限,請移除這些權限。
REST v1beta4
- 建立 Cloud Storage 值區。
上傳檔案至值區。
如需將檔案上傳至值區的說明,請參閱上傳物件。
- 為執行個體提供值區的
storage.objectAdmin
IAM 角色 。如需設定 IAM 權限的說明,請參閱使用 IAM 權限。 - 匯入檔案:
<
使用任何要求資料之前,請先替換以下項目:
- 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 頁面。 - 如果您不需要保留先前設定的 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 中存取權控管的說明,請參閱「
建立及管理存取權控管清單」。
後續步驟
- 瞭解如何檢查匯入與匯出作業的狀態。
- 進一步瞭解匯入及匯出資料的最佳做法。
- 匯入及匯出作業的已知問題。