将 Amazon S3 数据导入到 Aurora PostgreSQL 数据库集群 - Amazon Aurora
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

将 Amazon S3 数据导入到 Aurora PostgreSQL 数据库集群

您可以将数据从 Amazon S3 导入到属于 Aurora PostgreSQL 数据库集群的表中。为此,您可以使用 Aurora PostgreSQL 提供的 aws_s3 PostgreSQL 扩展。

注意

要从 Amazon S3 导入到 Aurora PostgreSQL,您的数据库必须运行 PostgreSQL 版本 10.7 或更高版本。

有关使用 Amazon S3 存储数据的更多信息,请参阅 Amazon Simple Storage Service 用户指南中的创建存储桶。有关如何将文件上传到 Amazon S3 存储桶的说明,请参阅 Amazon Simple Storage Service 用户指南中的向存储桶添加对象

Amazon S3 数据导入概述

要将 Amazon S3 存储桶中存储的数据导入到 PostgreSQL 数据库表,请执行以下步骤。

将 S3 数据导入到 Aurora PostgreSQL

  1. 安装所需的 PostgreSQL 扩展。这些包括 aws_s3aws_commons 扩展。为此,请启动 psql 并使用以下命令。

    psql=> CREATE EXTENSION aws_s3 CASCADE; NOTICE: installing required extension "aws_commons"

    aws_s3 扩展提供用于导入 Amazon S3 数据的 aws_s3.table_import_from_s3 函数。aws_commons 扩展提供了额外的帮助程序函数。

  2. 指定要使用的数据库表和 Amazon S3 文件。

    aws_s3.table_import_from_s3 函数需要使用要将数据导入到的 PostgreSQL 数据库表的名称。该函数还要求您指定要导入的 Amazon S3 文件。要提供该信息,请执行以下步骤。

    1. 标识要将数据放入其中的 PostgreSQL 数据库表。例如,以下是本主题的示例中使用的示例 t1 数据库表。

      psql=> CREATE TABLE t1 (col1 varchar(80), col2 varchar(80), col3 varchar(80));
    2. 获取以下信息以标识要导入的 Amazon S3 文件:

      • 存储桶名称 – 存储桶是 Amazon S3 对象或文件的容器。

      • 文件路径 – 文件路径查找 Amazon S3 存储桶中的文件。

      • Amazon区域 – Amazon区域是 Amazon S3 存储桶的位置。例如,如果 S3 存储桶位于 US East (N. Virginia) 区域中,请使用 us-east-1。有关 Amazon 区域名称和关联值的列表,请参阅 区域及可用区

      要了解如何获取此信息,请参阅 Amazon Simple Storage Service 用户指南中的查看对象。您可以使用 Amazon CLI 命令 aws s3 cp 确认该信息。如果该信息正确无误,该命令将下载 Amazon S3 文件的副本。

      aws s3 cp s3://sample_s3_bucket/sample_file_path ./
    3. 使用 aws_commons.create_s3_uri 函数创建一个 aws_commons._s3_uri_1 结构以保存 Amazon S3 文件信息。您可以在对 aws_commons._s3_uri_1 函数的调用中将该 aws_s3.table_import_from_s3 结构作为参数提供。

      有关 psql 示例,请参阅以下内容。

      psql=> SELECT aws_commons.create_s3_uri( 'sample_s3_bucket', 'sample.csv', 'us-east-1' ) AS s3_uri \gset
  3. 提供权限以访问 Amazon S3 文件。

    要从 Amazon S3 文件中导入数据,请为 Aurora PostgreSQL 数据库集群提供权限以访问该文件所在的 Amazon S3 存储桶。为此,您可以使用 Amazon Identity and Access Management (IAM) 角色或安全凭证。有关更多信息,请参阅“设置 Amazon S3 存储桶的访问权限”。

  4. 调用 aws_s3.table_import_from_s3 函数以导入 Amazon S3 数据。

    在完成以前的准备任务后,使用 aws_s3.table_import_from_s3 函数导入 Amazon S3 数据。有关更多信息,请参阅“使用 aws_s3.table_import_from_s3 函数导入 Amazon S3 数据”。

设置 Amazon S3 存储桶的访问权限

要从 Amazon S3 文件中导入数据,请为 Aurora PostgreSQL 数据库集群提供权限以访问该文件所在的 Amazon S3 存储桶。您可以通过两种方式提供 Amazon S3 存储桶的访问权限,如以下主题中所述。

使用 IAM 角色访问 Amazon S3 存储桶

从 Amazon S3 文件中加载数据之前,请为 Aurora PostgreSQL 数据库集群提供权限以访问该文件所在的 Amazon S3 存储桶。这样,您无需管理其他凭证信息或在 aws_s3.table_import_from_s3 函数调用中提供该信息。

为此,请创建一个 IAM 策略以提供 Amazon S3 存储桶的访问权限。创建一个 IAM 角色并将策略附加到该角色。然后,将该 IAM 角色分配给数据库集群

通过 IAM 角色向 Aurora PostgreSQL 数据库集群授予访问 Amazon S3 的权限

  1. 创建一个 IAM 策略。

    该策略提供存储桶和对象权限,以允许 Aurora PostgreSQL 数据库集群访问 Amazon S3。

    在策略中包含以下必需操作,以允许将文件从 Amazon S3 存储桶传输到 Aurora PostgreSQL

    • s3:GetObject

    • s3:ListBucket

    在策略中包含以下资源以标识 Amazon S3 存储桶以及存储桶中的对象。这会显示用于访问 Amazon S3 的 Amazon Resource Name (ARN) 格式。

    • arn:aws:s3:::your-s3-bucket

    • arn:aws:s3:::your-s3-bucket/*

    有关为 Aurora PostgreSQL 创建 IAM 策略的更多信息,请参阅 创建和使用适用于 IAM 数据库访问的 IAM 策略。另请参阅 IAM 用户指南中的教程:创建和附加您的第一个客户托管策略

    以下 Amazon CLI 命令使用这些选项创建一个名为 rds-s3-import-policy 的 IAM 策略。它授予访问名为 your-s3-bucket 的存储桶的权限。

    注意

    在您创建策略之后,请记下策略的 Amazon Resource Name (ARN)。在将策略附加到 IAM 角色时,您在后面的步骤中需要使用 ARN。

    对于 Linux、macOS 或 Unix:

    aws iam create-policy \ --policy-name rds-s3-import-policy \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "s3import", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::your-s3-bucket", "arn:aws:s3:::your-s3-bucket/*" ] } ] }'

    对于 Windows:

    aws iam create-policy ^ --policy-name rds-s3-import-policy ^ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "s3import", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::your-s3-bucket", "arn:aws:s3:::your-s3-bucket/*" ] } ] }'
  2. 创建一个 IAM 角色。

    这样,Aurora PostgreSQL 就可以担任该 IAM 角色以代表您访问 Amazon S3 存储桶。有关更多信息,请参阅 IAM 用户指南中的创建向 IAM 用户委派权限的角色

    以下示例说明了如何使用 Amazon CLI 命令创建一个名为 rds-s3-import-role 的角色。

    对于 Linux、macOS 或 Unix:

    aws iam create-role \ --role-name rds-s3-import-role \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }'

    对于 Windows:

    aws iam create-role ^ --role-name rds-s3-import-role ^ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }'
  3. 将您创建的 IAM 策略附加到您创建的 IAM 角色。

    以下 Amazon CLI 命令将以前创建的策略附加到一个名为 rds-s3-import-role 的角色。请将 your-policy-arn 替换为您在前面的步骤中记下的策略 ARN。

    对于 Linux、macOS 或 Unix:

    aws iam attach-role-policy \ --policy-arn your-policy-arn \ --role-name rds-s3-import-role

    对于 Windows:

    aws iam attach-role-policy ^ --policy-arn your-policy-arn ^ --role-name rds-s3-import-role
  4. 将该 IAM 角色添加到数据库集群中。

    您可以使用 Amazon Web Services Management Console 或 Amazon CLI 执行该操作,如下所述。

    注意

    您无法将 IAM 角色与 Aurora Serverless 数据库集群关联。有关更多信息,请参阅“使用 Amazon Aurora Serverless v1”。

    此外,请确保您使用的数据库没有 将 Amazon S3 数据导入到 Aurora PostgreSQL 数据库集群 中注明的任何限制。

使用控制台为 PostgreSQL 数据库 cluster 添加 IAM 角色

  1. 登录Amazon Web Services Management Console并通过以下网址打开 Amazon RDS 控制台:https://console.aws.amazon.com/rds/

  2. 选择 PostgreSQL 数据库集群名称以显示其详细信息。

  3. 连接性和安全性选项卡上的管理 IAM 角色部分中,在向此集群添加 IAM 角色下选择要添加的角色。

  4. Feature (功能) 下,选择 s3Import

  5. 选择 Add role (添加角色)

使用 CLI 为 PostgreSQL 数据库实例添加 IAM 角色

  • 使用以下命令将角色添加到名为 my-db-cluster 的 PostgreSQL 数据库集群中。将 your-role-arn 替换为您在上一步中记下的角色 ARN。使用 s3Import 作为 --feature-name 选项的值。

    对于 Linux、macOS 或 Unix:

    aws rds add-role-to-db-cluster \ --db-cluster-identifier my-db-cluster \ --feature-name s3Import \ --role-arn your-role-arn \ --region your-region

    对于 Windows:

    aws rds add-role-to-db-cluster ^ --db-cluster-identifier my-db-cluster ^ --feature-name s3Import ^ --role-arn your-role-arn ^ --region your-region

要使用 Amazon RDS API 为 PostgreSQL 数据库集群添加 IAM 角色,请调用 AddRoleToDBCluster 操作。

使用安全凭证访问 Amazon S3 存储桶

如果愿意,您可以使用安全凭证提供 Amazon S3 存储桶的访问权限,而不是使用 IAM 角色提供访问权限。为此,请在 credentials 函数调用中使用 aws_s3.table_import_from_s3 参数。

credentials 参数是 aws_commons._aws_credentials_1 类型的结构,其中包含 Amazon 凭证。使用 aws_commons.create_aws_credentials 函数设置 aws_commons._aws_credentials_1 结构中的访问密钥和私有密钥,如下所示。

psql=> SELECT aws_commons.create_aws_credentials( 'sample_access_key', 'sample_secret_key', '') AS creds \gset

在创建 aws_commons._aws_credentials_1 结构后,请将 aws_s3.table_import_from_s3 函数与 credentials 参数结合使用来导入数据,如下所示。

psql=> SELECT aws_s3.table_import_from_s3( 't', '', '(format csv)', :'s3_uri', :'creds' );

也可以在 aws_commons.create_aws_credentials 函数调用中以内联方式包括 aws_s3.table_import_from_s3 函数调用。

psql=> SELECT aws_s3.table_import_from_s3( 't', '', '(format csv)', :'s3_uri', aws_commons.create_aws_credentials('sample_access_key', 'sample_secret_key', '') );

Amazon S3 访问故障排除

如果在尝试导入 Amazon S3 文件数据时遇到连接问题,请参阅以下内容以了解相应的建议:

使用 aws_s3.table_import_from_s3 函数导入 Amazon S3 数据

通过调用 aws_s3.table_import_from_s3 函数来导入 Amazon S3 数据。

注意

以下示例使用 IAM 角色方法提供 Amazon S3 存储桶的访问权限。因此,aws_s3.table_import_from_s3 函数调用不包括凭据参数。

下面显示使用 psql 的典型 PostgreSQL 示例。

psql=> SELECT aws_s3.table_import_from_s3( 't1', '', '(format csv)', :'s3_uri' );

下面是参数:

  • t1 – 将数据复制到的 PostgreSQL 数据库集群中的表的名称。

  • '' – 数据库表中的列的可选列表。您可以使用此参数来指示哪些 S3 数据列进入哪些表列中。如果未指定任何列,则会将所有列复制到表中。有关使用列列表的示例,请参阅 导入使用自定义分隔符的 Amazon S3 文件

  • (format csv) – PostgreSQL COPY 参数。复制过程使用 PostgreSQL COPY 命令的参数和格式。在上一个示例中,COPY 命令使用逗号分隔值 (CSV) 文件格式来复制数据。

  • s3_uri – 包含标识 Amazon S3 文件的信息的结构。有关使用 aws_commons.create_s3_uri 函数创建 s3_uri 结构的示例,请参阅 Amazon S3 数据导入概述

返回值为文本。有关该函数的完整参考,请参阅 aws_s3.table_import_from_s3

以下示例说明了如何在导入 Amazon S3 数据时指定不同类型的文件。

导入使用自定义分隔符的 Amazon S3 文件

以下示例说明了如何导入使用自定义分隔符的文件。它还说明如何使用 column_list 函数的 aws_s3.table_import_from_s3 参数来控制将数据放置在数据库表中的哪个位置。

在此示例中,假定将以下信息组织到 Amazon S3 文件中的竖线分隔列中。

1|foo1|bar1|elephant1 2|foo2|bar2|elephant2 3|foo3|bar3|elephant3 4|foo4|bar4|elephant4 ...

导入使用自定义分隔符的文件

  1. 在数据库中为导入的数据创建一个表。

    psql=> CREATE TABLE test (a text, b text, c text, d text, e text);
  2. 使用以下形式的 aws_s3.table_import_from_s3 函数从 Amazon S3 文件导入数据。

    您可以在 aws_commons.create_s3_uri 函数调用中以内联方式包括 aws_s3.table_import_from_s3 函数调用来指定文件。

    psql=> SELECT aws_s3.table_import_from_s3( 'test', 'a,b,d,e', 'DELIMITER ''|''', aws_commons.create_s3_uri('sampleBucket', 'pipeDelimitedSampleFile', 'us-east-2') );

数据现在位于表的以下列中。

psql=> SELECT * FROM test; a | b | c | d | e ---+------+---+---+------+----------- 1 | foo1 | | bar1 | elephant1 2 | foo2 | | bar2 | elephant2 3 | foo3 | | bar3 | elephant3 4 | foo4 | | bar4 | elephant4

导入 Amazon S3 压缩 (gzip) 文件

以下示例说明如何从 Amazon S3 导入使用 gzip 压缩的文件。

确保该文件包含以下 Amazon S3 元数据:

  • 键:Content-Encoding

  • 值:gzip

有关将这些值添加到 Amazon S3 元数据的更多信息,请参阅 Amazon Simple Storage Service 用户指南中的如何向 S3 对象添加元数据?

将 gzip 文件导入到 Aurora PostgreSQL 数据库集群,如下所示。

psql=> CREATE TABLE test_gzip(id int, a text, b text, c text, d text); psql=> SELECT aws_s3.table_import_from_s3( 'test_gzip', '', '(format csv)', 'myS3Bucket', 'test-data.gz', 'us-east-2' );

导入编码的 Amazon S3 文件

以下示例说明如何从 Amazon S3 导入具有 Windows-1252 编码的文件。

psql=> SELECT aws_s3.table_import_from_s3( 'test_table', '', 'encoding ''WIN1252''', aws_commons.create_s3_uri('sampleBucket', 'SampleFile', 'us-east-2') );

函数参考

aws_s3.table_import_from_s3

将 Amazon S3 数据导入到 Aurora PostgreSQL 表中。aws_s3 扩展提供 aws_s3.table_import_from_s3 函数。返回值为文本。

Syntax

必需的参数为 table_namecolumn_listoptions。这些标识数据库表并指定如何将数据复制到表中。

您还可以使用以下参数:

  • s3_info 参数指定要导入的 Amazon S3 文件。在您使用此参数时,IAM 角色为 PostgreSQL 数据库集群提供访问 Amazon S3 的权限。

    aws_s3.table_import_from_s3 ( table_name text, column_list text, options text, s3_info aws_commons._s3_uri_1 )
  • credentials 参数指定凭证以访问 Amazon S3。在您使用此参数时,不使用 IAM 角色。

    aws_s3.table_import_from_s3 ( table_name text, column_list text, options text, s3_info aws_commons._s3_uri_1, credentials aws_commons._aws_credentials_1 )

Parameters

table_name

包含要将数据导入到的 PostgreSQL 数据库表的名称的必需文本字符串。

column_list

包含要将数据复制到的 PostgreSQL 数据库表列的可选列表的必需文本字符串。如果此字符串为空,将使用表的所有列。有关示例,请参阅导入使用自定义分隔符的 Amazon S3 文件

选项

包含 PostgreSQL COPY 命令的参数的必需文本字符串。这些参数指定如何将数据复制到 PostgreSQL 表中。有关更多详细信息,请参阅 PostgreSQL COPY 文档

s3_info

包含有关 S3 对象的以下信息的 aws_commons._s3_uri_1 复合类型:

  • bucket – 包含文件的 Amazon S3 存储桶的名称。

  • file_path – 包含文件路径的 Amazon S3 文件名。

  • region – 文件所在的Amazon区域。有关 Amazon 区域名称和关联值的列表,请参阅 区域及可用区

凭证

包含以下用于导入操作的凭证的 aws_commons._aws_credentials_1 复合类型:

  • 访问密钥

  • 私有密钥

  • 会话令牌

有关创建 aws_commons._aws_credentials_1 复合结构的信息,请参阅 aws_commons.create_aws_credentials

替代语法

为帮助进行测试,您可以使用一组扩展的参数,而非 s3_infocredentials 参数。下面是 aws_s3.table_import_from_s3 函数的其他语法变化。

  • 不使用 s3_info 参数来标识 Amazon S3 文件,而使用 bucketfile_pathregion 参数的组合。使用此形式的函数,IAM 角色在 PostgreSQL 数据库实例上提供访问 Amazon S3 的权限。

    aws_s3.table_import_from_s3 ( table_name text, column_list text, options text, bucket text, file_path text, region text )
  • 不使用 credentials 参数来指定 Amazon S3 访问权限,而使用 access_keysession_keysession_token 参数的组合。

    aws_s3.table_import_from_s3 ( table_name text, column_list text, options text, bucket text, file_path text, region text, access_key text, secret_key text, session_token text )

替代参数

存储桶

包含 Amazon S3 存储桶(其中包含文件)的名称的文本字符串。

file_path

包含 Amazon S3 文件名(包含文件路径)的文本字符串。

.region

包含文件所在的 Amazon 区域的文本字符串。有关 Amazon 区域名称和关联值的列表,请参阅 区域及可用区

access_key

包含用于导入操作的访问密钥的文本字符串。默认值为 NULL。

secret_key

包含用于导入操作的私有密钥的文本字符串。默认值为 NULL。

session_token

(可选)包含用于导入操作的会话密钥的文本字符串。默认值为 NULL。

aws_commons.create_s3_uri

创建 aws_commons._s3_uri_1 结构来保存 Amazon S3 文件信息。在 aws_commons.create_s3_uri 函数的 s3_info 参数中使用 aws_s3.table_import_from_s3 函数的结果。

Syntax

aws_commons.create_s3_uri( bucket text, file_path text, region text )

Parameters

bucket

包含文件的 Amazon S3 存储桶名称的必需文本字符串。

file_path

包含 Amazon S3 文件名(包含文件路径)的必填文本字符串。

.region

一个包含文件所在的 Amazon 区域的必需文本字符串。有关 Amazon 区域名称和关联值的列表,请参阅 区域及可用区

aws_commons.create_aws_credentials

aws_commons._aws_credentials_1 结构中设置访问密钥和私有密钥。在 aws_commons.create_aws_credentials 函数的 credentials 参数中使用 aws_s3.table_import_from_s3 函数的结果。

Syntax

aws_commons.create_aws_credentials( access_key text, secret_key text, session_token text )

Parameters

access_key

包含用于导入 Amazon S3 文件的访问密钥的必需文本字符串。默认值为 NULL。

secret_key

包含用于导入 Amazon S3 文件的私有密钥的必需文本字符串。默认值为 NULL。

session_token

包含用于导入 Amazon S3 文件的会话令牌的可选文本字符串。默认值为 NULL。如果您提供了可选的 session_token,则可以使用临时凭证。