从非 Spanner 数据库中导入数据

本页面介绍如何准备您从非 Cloud Spanner 数据库中导出的 Avro 文件,然后将这些文件导入 Spanner。如果要导入之前导出的 Spanner 数据库,请参阅导入 Spanner Avro 文件

该过程会使用 Dataflow,从包含一组 Avro 文件和一个 JSON 清单文件(指定目标表和填充每个表的 Avro 文件)的 Cloud Storage 存储分区导入数据。

准备工作

如需导入 Spanner 数据库,首先需要启用 Spanner、Cloud Storage、Compute Engine 和 Dataflow API:

启用 API

此外,您还需要足够的配额和必要的 IAM 权限。

配额要求

导入作业的配额要求如下:

  • Spanner:您必须有足够的计算容量来支持要导入的数据量。导入数据库不需要额外计算容量,但您可能需要增加更多计算容量,以便在合理的时间内完成作业。如需了解详情,请参阅优化作业
  • Cloud Storage:要导入,您必须拥有一个包含之前导出文件的存储分区。您无需为存储分区设置大小。
  • Dataflow:导入作业与其他 Dataflow 作业具有相同的 CPU、磁盘用量和 IP 地址 Compute Engine 配额
  • Compute Engine:在运行导入作业之前,必须为 Compute Engine 设置初始配额,以供 Dataflow 使用。这些配额表示允许 Dataflow 针对作业使用的资源用量上限。建议使用以下初始值:

    • CPU 数:200
    • 使用中的 IP 地址数:200
    • 标准永久性磁盘:50 TB

    通常情况下,您不必进行其他调整。 Dataflow 提供自动扩缩功能,因此您只需支付导入期间实际使用的资源费用。如果您的作业可能会使用更多资源,Dataflow 界面会显示警告图标。出现警告图标不会影响作业的完成。

IAM 要求

要导入数据库,您还需要有具备足够权限的 IAM 角色,以便使用导入作业中涉及的所有服务。如需了解如何授予角色和权限,请参阅应用 IAM 角色

要导入数据库,您需要以下角色:

  • 在 Google Cloud 项目级层:
    • Spanner 查看器
    • Dataflow Admin
    • Storage Admin
  • 在 Spanner 数据库或实例级别,或在 Google Cloud 项目级别:
    • Spanner 阅读器
    • Spanner 数据库管理员(仅导入作业需要)

将数据从非 Spanner 数据库导出到 Avro 文件

导入过程从位于 Cloud Storage 存储分区的 Avro 文件中提取数据。您可以从任何来源导出采用 Avro 格式的数据,也可以使用任何可用的方法来执行此操作。

如需将非 Spanner 数据库中的数据导出到 Avro 文件,请按以下步骤操作:

导出数据时,请注意以下事项:

  • 您可以使用任何 Avro 原始类型以及数组复杂类型执行导出。
  • Avro 文件中的每一列必须使用以下列类型之一:

    • ARRAY
    • BOOL
    • BYTES*
    • DOUBLE
    • FLOAT
    • INT
    • LONG
    • STRING

    * 类型为 BYTES 的列用于导入 Cloud Spanner NUMERIC;如需了解详情,请参阅下方的推荐映射

    †,‡ 可以将存储时间戳的 LONG 或存储时间戳的 STRING 作为 Spanner TIMESTAMP 导入;如需了解详情,请参阅下面的建议的映射

  • 导出 Avro 文件时,您不必包括或生成任何元数据。

  • 您的文件不必遵循任何特定的命名惯例。

如果您不将文件直接导出到 Cloud Storage,则必须将 Avro 文件上传到 Cloud Storage 存储分区。如需了解详细说明,请参阅将对象上传到 Cloud Storage

将非 Spanner 数据库中的 Avro 文件导入 Spanner

如需将非 Avro 数据库文件从非 Spanner 数据库导入 Spanner,请按以下步骤操作:

  1. 创建目标表并定义您的 Spanner 数据库的架构。
  2. 在 Cloud Storage 存储分区中创建 spanner-export.json 文件。
  3. 使用 gcloud CLI 运行 Dataflow 导入作业。

第 1 步:为 Spanner 数据库创建架构

在运行导入之前,您必须在 Spanner 中创建目标表并定义其架构。

您必须为 Avro 文件中的每一列创建一个使用适当列类型的架构。

Google 标准 SQL

Avro 列类型 Spanner 列类型
ARRAY ARRAY
BOOL BOOL
BYTES

BYTES

NUMERIC(当列类型为 BYTESlogicalType=decimalprecision=38scale=9 时)。如果省略了这些确切的规范,则该字段将被视为 Cloud Spanner BYTES 值。如需了解详情,请参阅 Avro 十进制逻辑类型文档。)

DOUBLE FLOAT64
FLOAT FLOAT64
INT INT64
LONG

INT64

TIMESTAMP,当 LONG 表示自 1970-01-01 00:00:00 UTC 以来的微秒数时间戳时

STRING

STRING

如果 STRING 表示采用 SQL 查询规范格式的时间戳,则为 TIMESTAMP

PostgreSQL

Avro 列类型 Spanner 列类型
ARRAY ARRAY
BOOL BOOLEAN
BYTES

BYTEA

NUMERIC(当列类型为 BYTEAlogicalType=decimalprecision=147455scale=16383 时)。如果省略这些确切规范,则该字段会被视为 BYTEA 值。如需了解详情,请参阅 Avro 十进制逻辑类型文档。)

DOUBLE DOUBLE PRECISION
FLOAT DOUBLE PRECISION
INT BIGINT
LONG

BIGINT

TIMESTAMP,当 LONG 表示自 1970-01-01 00:00:00 UTC 以来的微秒数时间戳时

STRING

CHARACTER VARYING

TIMESTAMP,当 STRING 表示规范查询格式的时间戳时,例如 '2022-05-28T07:08:21.123456789Z' 或 '2021-12-19T16:39:57-08:00'。

第 2 步:创建 spanner-export.json 文件

您还必须在 Cloud Storage 存储分区中创建名为 spanner-export.json 的文件。此文件指定了数据库方言,并包含一个 tables 数组,其中列出了每个表的名称和数据文件位置。

该文件的内容格式如下:

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL} 时

如果方言元素缺失,则方言默认为 GOOGLE_STANDARD_SQL

第 3 步:使用 gcloud CLI 运行 Dataflow 导入作业

要开始导入作业,请借助 Avro to Spanner 模板,按照使用 Google Cloud CLI 运行作业的说明进行操作。

启动导入作业后,您可以在 Google Cloud Console 中查看作业的详细信息

导入作业完成后,添加所有必要的二级索引外键

为导入作业选择一个区域

您可能需要根据 Cloud Storage 存储分区的位置选择其他区域。为避免产生网络出站流量费用,请选择与 Cloud Storage 存储分区位置匹配的区域。

  • 如果您的 Cloud Storage 存储分区位置是区域,您可以通过为导入作业选择相同区域(假设该区域可用)来利用免费网络使用

  • 如果您的 Cloud Storage 存储分区位置是双区域,则可以选择为导入作业的两个区域之一(假设其中一个区域可用)来利用免费网络使用

  • 如果导入作业没有位于同一地区的区域,或者您的 Cloud Storage 存储分区位置是多区域,则会收取出站流量费用。请参阅 Cloud Storage 网络出站流量价格,选择出站网络流量费用最低的区域。

在 Dataflow 界面中查看作业或对作业进行问题排查

启动导入作业后,您可以在 Google Cloud Console 的 Dataflow 部分中查看作业的详细信息,包括日志。

查看 Dataflow 作业详情

如需查看过去一周内运行的任何导入/导出作业(包括当前正在运行的任何作业)的详细信息,请执行以下操作:

  1. 转到数据库的数据库概览页面。
  2. 点击左侧窗格中的导入/导出菜单项。数据库导入/导出页面会显示最近的作业列表。
  3. 在数据库导入/导出页面中,点击 Dataflow 作业名称列中的作业名称:

    运行中作业的状态消息

    Google Cloud Console 会显示 Dataflow 作业的详细信息。

如需查看超过一周前运行的作业,请执行以下操作:

  1. 转到 Google Cloud Console 中的 Dataflow 作业页面。

    转到作业页面

  2. 在列表中找到您的作业,然后点击其名称。

    Google Cloud Console 会显示 Dataflow 作业的详细信息。

查看您的作业的 Dataflow 日志

如需查看 Dataflow 作业的日志,请按上文所述转到作业的详细信息页面,然后点击作业名称右侧的日志

如果作业失败,请查看日志了解错误。如果有错误,日志旁边会显示错误计数:

“日志”按钮旁边的错误计数示例

如需查看作业错误,请执行以下操作:

  1. 点击日志旁边的错误计数。

    Google Cloud Console 将显示作业日志。您可能需要向下滚动才能看到错误。

  2. 找到带错误图标 “错误”图标 的条目。

  3. 点击各个日志条目以展开其内容。

如需详细了解如何对 Dataflow 作业进行问题排查,请参阅对流水线进行问题排查

排查导入作业失败问题

如果您在作业日志中看到以下错误,请执行以下操作:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

在 Google Cloud Console 中,查看 Cloud Spanner 数据库的 Monitoring 标签页的 99% 写入延迟时间。如果显示的值较大(几秒钟),则表示实例已过载,导致写入超时并失败。

高延迟的一个原因是 Dataflow 作业运行时使用的工作器过多,导致 Cloud Spanner 实例负载过高。

如需指定 Dataflow 工作器的数量限制,您必须使用 Dataflow Cloud Storage Avro to Cloud Spanner 模板开始导入,而不是指定 Google Cloud Console 中 Cloud Spanner 数据库的实例详情页面中的“导入/导出”标签页, 并指定工作器数量上限,具体说明如下:
  • 如果您使用的是 Dataflow 控制台,则工作器数量上限参数位于基于模板创建作业页面上的可选参数部分。

  • 如果您使用的是 gcloud,请指定 max-workers 参数。例如:

    gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10
    

优化运行缓慢的导入作业

如果您已按照初始设置中的建议配置,则通常不必进行其他调整。如果作业运行缓慢,则可以尝试以下优化操作:

  • 优化作业和数据位置:在 Spanner 实例和 Cloud Storage 存储分区所在的同一区域中运行 Dataflow 作业。

  • 确保有足够的 Dataflow 资源:如果相关的 Compute Engine 配额限制了您的 Dataflow 作业的资源,则 Google Cloud Console 中的作业 Dataflow 页面会显示警告图标 警告图标 和日志消息:

    配额限制警告的屏幕截图

    在这种情况下,为 CPU、使用中的 IP 地址和标准永久性磁盘增加配额或许可以缩短作业的运行时间,但可能会因此产生更多的 Compute Engine 费用。

  • 检查 Spanner 的 CPU 利用率:如果您发现某个实例的 CPU 使用率超过 65%,则可以为该实例提高计算容量。容量会增加更多 Spanner 资源,并且作业速度应该会加快,但会产生更多 Spanner 费用。

影响导入作业性能的因素

以下几个因素会影响完成导入作业所需的时间。

  • Spanner 数据库大小:处理更多数据需要更多时间和资源。

  • Spanner 数据库架构,包括:

    • 表格数量
    • 行的大小
    • 二级索引的数量
    • 外键的数量
    • 变更流数量

  • 数据位置:数据使用 Spanner 在 Cloud Storage 和 Cloud Storage 之间传输。理想情况下,这三个组件全都位于同一区域。如果这些组件不在同一区域,则跨区域移动数据会减慢作业运行速度。

  • Dataflow 工作器数量:最佳 Dataflow 工作器是实现良好性能所必需的。Dataflow 使用自动扩缩功能,根据需要完成的工作量选择作业的工作器数量。但是,工作器数量会受到 CPU、使用中的 IP 地址和标准永久性磁盘的配额的限制。如果工作器数量达到配额上限,Dataflow 界面中会显示一个警告图标。在这种情况下,运行速度会减慢,但作业仍会完成。自动扩缩功能可能会导致 Spanner 过载,进而在需要导入大量数据时引发错误。

  • Spanner 上的现有负载:导入作业会给 Spanner 实例增加大量 CPU 负载。如果该实例原本已有大量负载,则作业的运行速度会较慢。

  • Spanner 计算容量:如果实例的 CPU 利用率超过 65%,则作业的运行速度会减慢。

调整工作器以实现良好的导入性能

启动 Spanner 导入作业时,您必须将 Dataflow 工作器设置为最佳值,以实现良好的性能。如果工作器过多,Spanner 会过载,而工作器过少会导致导入性能不佳。

工作器的数量上限与数据大小密切相关,但理想情况下,Spanner 的总 CPU 利用率应在 70% 到 90% 之间。这可以实现 Spanner 效率和无错误地完成作业之间的良好平衡。

如需在大多数架构/场景中实现该利用率目标,我们建议最大工作器 vCPU 数量在 Spanner 节点数量的 4-6 倍之间。

例如,对于使用 n1-standard-2 工作器的 10 个节点 spanner 实例,您需要将最大工作器数量设置为 25 个,从而提供 50 个 vCPU。