匯入及匯出資料

本文說明如何使用 Avro 和 CSV 格式，在 Spanner Omni 中遷移、備份及轉移資料。使用 Spanner Omni CLI，在 Spanner Omni 與儲存解決方案 (例如 Cloud Storage、Amazon Simple Storage Service (Amazon S3)、與 S3 相容的本機儲存空間或本機檔案系統 (NFS)) 之間移動資料庫內容。Spanner Omni 中的匯入和匯出資料流不支援模型、區域群組或放置位置。

匯入和匯出作業會在 Spanner Omni 伺服器上執行，並共用可用的系統資源。匯入作業會耗用大量資源，可能導致 RAM、CPU 和磁碟使用率偏高，進而影響現有工作負載。雖然這些工作通常會以低於一般流量的優先順序執行，但您仍應監控部署作業，以免對效能造成影響。

檔案格式比較

下表比較了 Avro 和 CSV 檔案格式在匯入及匯出 Spanner 資料方面的功能。

功能	Avro	CSV
匯入或匯出整個資料庫	是	否
匯入先前匯出的資料表	是	是
匯出過去時間戳記的資料	是	是
使用 Spanner 匯入或匯出	是	是
從其他資料庫匯入資料	否	是

Avro 和 CSV 格式都會匯出資料庫中的所有表格。Avro 格式也會匯出結構定義，方便您再次匯入。CSV 格式不會匯出結構定義。

事前準備

開始匯入或匯出作業前，請先確認權限，並設定資料儲存位置的存取權。

權限

開始前，請確認您具備下列權限：

• spanner.databases.import
• spanner.databases.export

如要進一步瞭解 Spanner Omni 中的 Identity and Access Management (IAM)，請參閱「IAM 總覽」。如要瞭解如何更新使用者的角色，請參閱「更新使用者」。

資料來源和目的地

您可以將資料儲存在 Amazon Simple Storage Service (Amazon S3) bucket、Cloud Storage bucket、與 Amazon S3 相容的本機儲存空間 (例如 MinIO)，或是本機檔案系統 (NFS)。如果您使用本機檔案系統，請確保部署作業中所有伺服器上的資料路徑相同。

您可以透過下列兩種方式提供 Datastore 的存取權：

• 在部署作業中新增外部儲存空間：如果您打算重複使用 bucket，建議採用這個方法。

• 建立一次性憑證：請確保這些憑證的有效時間長於匯入或匯出作業的持續時間 (例如 48 小時)。

憑證必須提供權限，才能列出及讀取 bucket 中的物件以供匯入。如要將資料匯出至 Amazon S3，您還需要下列 Amazon S3 權限：

• s3:PutObject
• s3:AbortMultipartUpload
• s3:ListBucketMultipartUploads

詳情請參閱「IAM 權限」。

匯入 Spanner Avro 檔案

如要匯入先前從其他 Spanner 資料庫 (Spanner 或 Spanner Omni) 匯出的 Avro 格式資料，請按照下列步驟操作。

匯入 Avro 的必要條件

開始匯入 Avro 前，請確認您的環境符合下列需求：

• 您已建立目的地資料庫。

• 您匯入的結構定義物件尚未存在於資料庫中。 Avro 匯入程序會在匯入資料前建立這些資料表。

Avro 匯入說明

找出包含匯出資料的資料夾路徑。資料夾包含下列項目：

• spanner-export.json 檔案。

• 每個匯出實體 (例如資料表、序列或結構定義) 的 ENTITY_NAME-manifest.json 檔案。

• 資訊清單檔案中列出的所有 Avro 檔案。

如果已將資料存放區新增為外部儲存空間，則不必在路徑中加入憑證。您可以直接提供路徑。如果您使用一次性憑證，請使用下列網址格式：

• Cloud Storage： gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]。 使用 HMAC 憑證。詳情請參閱「HMAC 金鑰」。

• Amazon S3： s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]

• 本機檔案資料夾*：file:///PATH_TO_DIR

如要開始匯入，請執行下列指令：

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

其他注意事項

匯入 Avro 檔案時，請注意下列事項：

• Spanner 說明文件：匯入產生的資料欄和變更串流

• 匯入序列相關注意事項 請參閱 Spanner 文件。

• Spanner 說明文件：匯入交錯資料表和外鍵的注意事項。

• 如要略過匯入特定實體，請從 spanner-export.json 檔案中移除這些實體。

• 如果是大型資料集，建立索引可能需要相當長的時間。如要略過等待索引建立的程序，請使用選用的 --avro-skip-wait-for-index-creation 標記。

匯入作業順利開始後，系統會傳回長時間執行的作業 ID。使用這個 ID 追蹤作業狀態。

匯入 CSV 檔案

如要匯入從其他資料庫匯出的文字資料，請按照下列步驟操作。

匯入 CSV 檔案的先決條件

開始匯入 CSV 檔案前，請務必完成下列步驟：

• 請確認資料表採用下列其中一種支援的資料類型：BOOL、INT64、FLOAT64、NUMERIC、STRING、DATE、TIMESTAMP、BYTES 和 JSON。

• 建立目的地資料庫。

• 建立要匯入資料的所有資料表。CSV 匯入程序不會建立資料表。

• 請確認 CSV 檔案不含標頭列。

CSV 匯入說明

如要匯入 CSV 檔案，請建立資訊清單檔案，說明要匯入的資料。 資訊清單檔案採用以下結構，以 protobuf 格式定義如下：

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a path or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

以下是資訊清單範例：

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

下列匯入指令中的網址必須指向包含 JSON 格式資訊清單檔案的資料夾，如資訊清單範例所述。這個檔案可以位於 Cloud Storage、Amazon S3 或本機檔案資料夾，使用與 Avro 匯入說明中相同的憑證網址格式。如要開始匯入，請執行下列指令：

spanner databases import DATABASE_ID --url="URL" --format=csv

CSV 匯入選項

使用下列旗標自訂 Spanner Omni 處理文字檔案的方式：

• --csv-date-format：覆寫日期資料欄的格式。預設值為 %Y-%m-%d。範例：%d/%m/%Y。

• --csv-timestamp-format：覆寫時間戳記資料欄的格式。只有在 Spanner Omni 不支援 CSV 中的格式時，才使用這個選項。範例：%d/%m/%Y %H:%M:%S%Ez。

• --csv-delimiter：覆寫分隔字元。預設值為半形逗號。

• --csv-quote-char：覆寫引號字元。預設為雙引號。

• --csv-escape-char：覆寫逸出字元。預設為雙引號。

• --csv-null-string：覆寫代表 NULL 值的字串。預設值為 \N。

• --csv-has-trailing-delimiters：指定 CSV 檔案是否含有尾端分隔符。預設值為 false。

匯出為 Avro 檔案

如要將資料匯出至 Avro 檔案，請按照「Avro 匯入說明」中的網址格式操作。

部署作業中的任何伺服器都可以將資料寫入提供的資料存放區。如果使用本機檔案資料夾做為目的地，請確保所有伺服器都能存取相同路徑，並可平行寫入。

系統會匯出資料庫中的所有資料表和實體。請務必提供匯出資料的新空白資料夾路徑。

如要開始匯出，請執行下列指令：

spanner databases export DATABASE_ID --url="URL" --format=avro

CSV 匯出功能僅支援表格，不會匯出資料庫結構。

匯出為 CSV 檔案

CSV 匯出作業不會匯出資料庫結構定義，只會匯出支援的資料表。如要將資料匯出為 CSV 檔案，請執行下列指令：

spanner databases export DATABASE_ID --url="URL" --format=csv

疑難排解

如果匯入失敗，系統不會自動還原結構定義更新和匯入的資料。請先手動清理資料庫，再重試作業。

匯入作業的速度取決於多項因素，包括資料夾中的檔案數量、部署作業中可用的運算資源，以及磁碟速度。如果可用資源充足，系統會平行匯入檔案。