使用 CSV 文件导出和导入

本页面介绍如何将 Cloud SQL 实例数据导出为 CSV 文件以及使用 CSV 文件将数据导入 Cloud SQL 实例。

须知事项

在开始导出或导入操作之前，请先做好以下准备工作：

  • 确保您的数据库具有足够的可用空间。

    • 导出和导入操作会使用数据库资源，但不会干扰正常的数据库操作，除非实例预配不足。

  • 验证 CSV 文件是否包含预期数据，并且数据采用正确的格式。在 CSV 文件中，必须每行数据字段占用一行。
  • 遵循导出和导入数据的最佳做法。

从 Cloud SQL for PostgreSQL 导出数据

从 Cloud SQL for PostgreSQL 导出所需的角色和权限

如需将数据从 Cloud SQL 导出到 Cloud Storage 中，启动导出的用户必须拥有以下角色之一：

此外，Cloud SQL 实例的服务账号必须拥有以下角色之一：

  • storage.objectAdmin Identity and Access Management (IAM) 角色
  • 包括以下权限的自定义角色：
    • storage.objects.create
    • storage.objects.list（仅用于并行导出文件）
    • storage.objects.delete（仅用于并行导出文件）

如需有关 IAM 角色的帮助，请参阅 Identity and Access Management。

从 Cloud SQL for PostgreSQL 导出数据到 CSV 文件

您可使用 CSV 格式导出数据，以供其他工具和环境使用。导出操作在数据库级层进行。在 CSV 导出期间，您可以指定要导出的架构。数据库级层下的所有架构都可以导出。

如需将 Cloud SQL 实例上的数据库数据导出到 Cloud Storage 存储桶中的 CSV 文件，请执行以下操作：

控制台

  1. 在 Google Cloud 控制台中，转到 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 如需打开实例的概览页面，请点击实例名称。
  3. 点击导出。
  4. 选择分流导出，允许在导出过程中进行其他操作。
  5. 在 Cloud Storage 导出位置部分，添加存储桶、文件夹和要导出的文件的名称，或者点击浏览查找或创建存储桶、文件夹或文件。

    如果点击了浏览：

    1. 在位置部分，为导出选择 Cloud Storage 存储桶或文件夹。

    2. 在名称框中，添加 CSV 文件的名称，或者从位置部分的列表中选择现有文件。

      您可以使用 .gz 文件扩展名（完整扩展名为 .csv.gz）来压缩导出文件。

    3. 点击选择。
  6. 在格式部分，点击 CSV。
  7. 在要导出的数据库部分，从下拉菜单中选择数据库的名称。

  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. 使用 gsutil iam 向 Cloud SQL 实例服务账号授予 storage.objectAdmin IAM 角色。如需有关设置 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. 为导出创建一个存储桶：
    gsutil mb -p PROJECT_NAME -l LOCATION_NAME gs://BUCKET_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 属性仅指定一个数据库；如果 select 查询指定了数据库，则该数据库必须与之相同。

  4. 如果您不需要保留之前设置的 IAM 权限，请立即移除这些权限。
如需查看请求的完整参数列表，请参阅 instances:export 页面。

REST v1beta4

  1. 为导出创建一个存储桶：
    gsutil mb -p PROJECT_NAME -l LOCATION_NAME gs://BUCKET_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 属性仅指定一个数据库；如果 select 查询指定了数据库，则该数据库必须与之相同。

  4. 如果您不需要保留之前设置的 IAM 角色，请立即撤消该角色。
如需查看请求的完整参数列表，请参阅 instances:export 页面。

自定义 CSV 导出文件的格式

您可以使用 gcloud 或 REST API 自定义 CSV 文件格式。执行导出时，您可以指定以下格式设置选项：

CSV 选项 默认值 gcloud 标志 REST API 属性 说明
转义

"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]');

将数据导入到 Cloud SQL for PostgreSQL

导入到 Cloud SQL for PostgreSQL 所需的角色和权限

如需将数据从 Cloud Storage 导入到 Cloud SQL 中，启动导入的用户必须拥有以下角色之一：

此外，Cloud SQL 实例的服务账号必须拥有以下角色之一：

  • storage.objectAdmin IAM 角色
  • 包括以下权限的自定义角色：
    • storage.objects.get
    • storage.objects.list（仅用于并行导入文件）

如需有关 IAM 角色的帮助，请参阅 Identity and Access Management。

将数据从 CSV 文件导入 Cloud SQL for PostgreSQL

  • 您要向其中导入数据的数据库和表必须已经存在于 Cloud SQL 实例上。如需有关创建数据库方面的帮助，请参阅创建数据库。
  • 您的 CSV 文件必须符合 CSV 文件格式要求。

CSV 文件格式要求

在 CSV 文件中，必须每行数据占用一行，而且必须使用英文逗号分隔字段。

要使用 CSV 文件将数据导入 Cloud SQL 实例，请按如下所述操作：

控制台

  1. 在 Google Cloud 控制台中，转到 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 如需打开实例的概览页面，请点击实例名称。
  3. 点击导入。
  4. 在选择您要从中导入数据的文件部分中，输入要用于导入的存储桶和 CSV 文件的路径。或者，浏览到该文件：
    1. 点击浏览。
    2. 在位置部分，双击列表中存储桶的名称。
    3. 在列表中选择该文件。
    4. 点击选择。

    您可以导入经过压缩 (.gz) 或未经压缩 (.csv) 的文件。

  5. 在格式部分，选择 CSV。
  6. 指定要将 CSV 文件导入 Cloud SQL 实例中的哪个数据库和表。
  7. 您可以选择为导入操作指定用户。
  8. 点击导入以开始导入。

gcloud

  1. 创建 Cloud Storage 存储桶。

  2. 将文件上传到存储桶。

    如需有关将文件上传到存储桶方面的帮助，请参阅上传对象。

  3. 将数据从 CSV 文件上传到存储桶。
  4. 确定要从中导出数据的 Cloud SQL 实例的服务账号。为此，您可以运行指定了实例名称的 gcloud sql instances describe 命令。在输出中查找 serviceAccountEmailAddress 字段。
    gcloud sql instances describe INSTANCE_NAME
  5. 复制 serviceAccountEmailAddress 字段。
  6. 使用 gsutil iam 向 Cloud SQL 实例服务账号授予该存储桶的 storage.objectAdmin IAM 角色。如需有关设置 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 权限，请使用 gsutil iam 移除这些权限。

REST v1

  1. 创建 Cloud Storage 存储桶。

  2. 将文件上传到存储桶。

    如需有关将文件上传到存储桶方面的帮助，请参阅上传对象。

  3. 为您的实例提供存储桶的 legacyBucketWriter 和 objectViewer 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 权限，请移除这些权限。

为 Cloud SQL for PostgreSQL 自定义 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。

后续步骤