本页面介绍如何将 Cloud SQL 实例数据导出为 CSV 文件以及使用 CSV 文件将数据导入 Cloud SQL 实例。
须知事项
在开始导出或导入操作之前,请先做好以下准备工作:
- 确保您的数据库具有足够的可用空间。
- 验证 CSV 文件是否包含预期数据,并且数据采用正确的格式。在 CSV 文件中,必须每行数据字段占用一行。
- 遵循导出和导入数据的最佳做法。
导出和导入操作会使用数据库资源,但不会干扰正常的数据库操作,除非实例预配不足。
从 Cloud SQL for PostgreSQL 导出数据
从 Cloud SQL for PostgreSQL 导出所需的角色和权限
如需将数据从 Cloud SQL 导出到 Cloud Storage 中,启动导出的用户必须拥有以下角色之一:
- Cloud SQL Editor 角色
- 包括以下权限的自定义角色:
cloudsql.instances.get
cloudsql.instances.export
此外,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 文件,请执行以下操作:
控制台
-
在 Google Cloud 控制台中,转到 Cloud SQL 实例页面。
- 如需打开实例的概览页面,请点击实例名称。
- 点击导出。
- 选择分流导出,允许在导出过程中进行其他操作。
-
在 Cloud Storage 导出位置部分,添加存储桶、文件夹和要导出的文件的名称,或者点击浏览查找或创建存储桶、文件夹或文件。
如果点击了浏览:
- 在位置部分,为导出选择 Cloud Storage 存储桶或文件夹。
在名称框中,添加
CSV
文件的名称,或者从位置部分的列表中选择现有文件。您可以使用
.gz
文件扩展名(完整扩展名为.csv.gz
)来压缩导出文件。- 点击选择。
- 在格式部分,点击 CSV。
- 在要导出的数据库部分,从下拉菜单中选择数据库的名称。
-
在 SQL 查询下,输入 SQL 查询,以指定要从中导出数据的表。
例如,如需导出
guestbook
数据库中entries
表的全部内容,请输入以下内容:SELECT * FROM guestbook.entries;
您的查询必须在指定的数据库中指定一个表。您无法以 CSV 格式导出整个数据库。 - 点击导出以开始导出。
- 系统会打开“导出数据库?”方框,提示大型数据库的导出过程可能需要一个小时或更长时间。在导出期间,您可在实例上执行的唯一操作是查看信息。导出开始后,您可以取消操作。如果此时适合开始导出,请点击导出。否则,请点击取消。
gcloud
- 创建 Cloud Storage 存储桶。
将文件上传到存储桶。
如需有关将文件上传到存储桶方面的帮助,请参阅上传对象。
- 找到要从中导出数据的 Cloud SQL 实例的服务账号。为此,您可以运行
gcloud sql instances describe
命令。在输出中查找serviceAccountEmailAddress
字段。gcloud sql instances describe INSTANCE_NAME
- 使用
gsutil iam
向 Cloud SQL 实例服务账号授予storage.objectAdmin
IAM 角色。如需有关设置 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
- 为导出创建一个存储桶:
gsutil mb -p PROJECT_NAME -l LOCATION_NAME gs://BUCKET_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
属性仅指定一个数据库;如果 select 查询指定了数据库,则该数据库必须与之相同。 - 如果您不需要保留之前设置的 IAM 权限,请立即移除这些权限。
REST v1beta4
- 为导出创建一个存储桶:
gsutil mb -p PROJECT_NAME -l LOCATION_NAME gs://BUCKET_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
属性仅指定一个数据库;如果 select 查询指定了数据库,则该数据库必须与之相同。 - 如果您不需要保留之前设置的 IAM 角色,请立即撤消该角色。
自定义 CSV 导出文件的格式
您可以使用 gcloud
或 REST API 自定义 CSV 文件格式。执行导出时,您可以指定以下格式设置选项:
CSV 选项 | 默认值 | gcloud 标志 | REST API 属性 | 说明 |
---|---|---|---|---|
转义 |
文件分隔符的 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]');
将数据导入到 Cloud SQL for PostgreSQL
导入到 Cloud SQL for PostgreSQL 所需的角色和权限
如需将数据从 Cloud Storage 导入到 Cloud SQL 中,启动导入的用户必须拥有以下角色之一:
- Cloud SQL Editor 角色
- 包括以下权限的自定义角色:
cloudsql.instances.get
cloudsql.instances.import
此外,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 实例,请按如下所述操作:
控制台
-
在 Google Cloud 控制台中,转到 Cloud SQL 实例页面。
- 如需打开实例的概览页面,请点击实例名称。
- 点击导入。
- 在选择您要从中导入数据的文件部分中,输入要用于导入的存储桶和 CSV 文件的路径。或者,浏览到该文件:
- 点击浏览。
- 在位置部分,双击列表中存储桶的名称。
- 在列表中选择该文件。
- 点击选择。
您可以导入经过压缩 (
.gz
) 或未经压缩 (.csv
) 的文件。 - 在格式部分,选择 CSV。
- 指定要将 CSV 文件导入 Cloud SQL 实例中的哪个数据库和表。
- 您可以选择为导入操作指定用户。
- 点击导入以开始导入。
gcloud
- 创建 Cloud Storage 存储桶。
将文件上传到存储桶。
如需有关将文件上传到存储桶方面的帮助,请参阅上传对象。
- 将数据从 CSV 文件上传到存储桶。
- 确定要从中导出数据的 Cloud SQL 实例的服务账号。为此,您可以运行指定了实例名称的
gcloud sql instances describe
命令。在输出中查找serviceAccountEmailAddress
字段。gcloud sql instances describe INSTANCE_NAME
- 复制 serviceAccountEmailAddress 字段。
- 使用
gsutil iam
向 Cloud SQL 实例服务账号授予该存储桶的storage.objectAdmin
IAM 角色。如需有关设置 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 权限,请使用
gsutil iam
移除这些权限。
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 权限,请移除这些权限。
为 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 中配置访问权限控制方面的帮助,请参阅创建和管理访问控制列表。
后续步骤
- 了解如何查看导入和导出操作的状态。
- 详细了解导入和导出数据的最佳做法。
- 导入和导出的已知问题。