导入和导出数据

本文档介绍了如何使用 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) 存储桶、Cloud Storage 存储桶、与 Amazon S3 兼容的本地存储空间（例如 MinIO）或本地文件系统 (NFS) 中。如果您使用本地文件系统，请确保部署中的所有服务器上都可通过同一路径访问数据。

您可以通过以下两种方式授予对数据存储区的访问权限：

向部署中添加外部存储空间：如果您计划重复使用存储桶，这是首选方法。
创建一次性凭据：确保这些凭据的有效期长于导入或导出操作的持续时间（例如 48 小时）。

凭据必须提供列出和读取存储桶中对象的权限，以便进行导入。对于导出到 Amazon S3 的操作，您需要以下额外的 Amazon S3 权限：

s3:PutObject
s3:AbortMultipartUpload
s3:ListBucketMultipartUploads

如需了解详情，请参阅 IAM 权限。

导入 Spanner Avro 文件

如需导入您之前以 Avro 格式从其他 Spanner 数据库（Spanner 或 Spanner Omni）导出的数据，请按以下步骤操作。

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"}
      ]
    }
  ]
}

以下 CSV 文件不包含标题行的导入命令中的网址必须指向包含 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

问题排查

如果导入失败，架构更新和导入的数据不会自动恢复。请先手动清理数据库，然后再重试操作。

导入操作的速度取决于多种因素，包括文件夹中的文件数量、部署中可用的计算资源以及磁盘速度。如果有足够的资源，系统会并行导入文件。