将 Amazon S3 数据导入到 Aurora PostgreSQL 数据库集群
您可以将数据从 Amazon S3 导入到属于 Aurora PostgreSQL 数据库集群的表中。为此,您可以使用 Aurora PostgreSQL 提供的 aws_s3
PostgreSQL 扩展。要从 Amazon S3 导入到 ,您的数据库必须运行 PostgreSQL 版本 10.7 或更高版本。Aurora PostgreSQL – 您只能导入到预配置的数据库实例中。也就是说,Aurora Serverless v1 不支持这些步骤。
有关使用 Amazon S3 存储数据的更多信息,请参阅 Amazon Simple Storage Service 用户指南中的创建存储桶。有关如何将文件上传到 Amazon S3 存储桶的说明,请参阅 Amazon Simple Storage Service 用户指南中的向存储桶添加对象。
Amazon S3 数据导入概述
要将 Amazon S3 存储桶中存储的数据导入到 PostgreSQL 数据库表,请执行以下步骤。
将 S3 数据导入到 Aurora PostgreSQL
-
安装所需的 PostgreSQL 扩展。这些包括
aws_s3
和aws_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
扩展提供了额外的帮助程序函数。 -
指定要使用的数据库表和 Amazon S3 文件。
aws_s3.table_import_from_s3 函数需要使用要将数据导入到的 PostgreSQL 数据库表的名称。该函数还要求您指定要导入的 Amazon S3 文件。要提供该信息,请执行以下步骤。
-
标识要将数据放入其中的 PostgreSQL 数据库表。例如,以下是本主题的示例中使用的示例
t1
数据库表。psql=> CREATE TABLE t1 (col1 varchar(80), col2 varchar(80), col3 varchar(80));
-
获取以下信息以标识要导入的 Amazon S3 文件:
-
存储桶名称 – 存储桶是 Amazon S3 对象或文件的容器。
-
文件路径 – 文件路径查找 Amazon S3 存储桶中的文件。
-
Amazon区域 – Amazon区域是 Amazon S3 存储桶的位置。例如,如果 S3 存储桶位于美国东部(弗吉尼亚北部)区域中,请使用
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
./ -
-
使用 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
-
-
提供权限以访问 Amazon S3 文件。
要从 Amazon S3 文件中导入数据,请为 Aurora PostgreSQL 数据库集群提供权限以访问该文件所在的 Amazon S3 存储桶。为此,您可以使用 Amazon Identity and Access Management (IAM) 角色或安全凭证。有关更多信息,请参阅“设置 Amazon S3 存储桶的访问权限”。
-
调用
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 Serverless v1 数据库集群关联,因此以下步骤不适用。
通过 IAM 角色授予 Aurora PostgreSQL 数据库集群访问 Amazon S3 的权限
-
创建一个 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
/*" ] } ] }' -
-
创建一个 IAM 角色。
这样,Aurora PostgreSQL 就可以担任该 IAM 角色以访问您的 Amazon S3 存储桶。有关更多信息,请参阅 IAM 用户指南中的创建向 IAM 用户委派权限的角色。
我们建议在基于资源的策略中使用
aws:SourceArn
和aws:SourceAccount
全局条件上下文键,以限制对特定资源的服务权限。这是防范混淆代理人问题最有效的方法。如果同时使用全局条件上下文键和包含账户 ID 的
aws:SourceArn
值,则aws:SourceAccount
值和aws:SourceArn
值中的账户在同一策略语句中使用时,必须使用相同的账户 ID。如果您想对单个资源进行跨服务访问,请使用
aws:SourceArn
。-
如果您想允许该账户中的任何资源与跨服务使用操作相关联,请使用
aws:SourceAccount
。
在策略中,确保使用具有资源的完整 ARN 的
aws:SourceArn
全局条件上下文键。以下示例说明了如何使用 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", "Condition": { "StringEquals": { "aws:SourceAccount": "
111122223333
", "aws:SourceArn": "arn:aws:rds:us-east-1:111122223333:db:dbname
" } } } ] }'对于 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", "Condition": { "StringEquals": { "aws:SourceAccount": "
111122223333
", "aws:SourceArn": "arn:aws:rds:us-east-1:111122223333:db:dbname
" } } } ] }' -
将您创建的 IAM 策略附加到您创建的 IAM 角色。
以下 Amazon CLI 命令将上一步中创建的策略附加到一个名为
rds-s3-import-role
的角色。请将
替换为您在前面的步骤中记下的策略 ARN。your-policy-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 -
将该 IAM 角色添加到数据库集群中。
您可以使用 Amazon Web Services Management Console 或 Amazon CLI 执行该操作,如下所述。
使用控制台为 PostgreSQL 数据库集群添加 IAM 角色
登录Amazon Web Services Management Console并通过以下网址打开 Amazon RDS 控制台:https://console.aws.amazon.com/rds/
。 -
选择 PostgreSQL 数据库集群名称以显示其详细信息。
-
在连接性和安全性选项卡上的管理 IAM 角色部分中,在向此集群添加 IAM 角色下选择要添加的角色。
-
在 Feature (功能) 下,选择 s3Import。
-
选择 Add role (添加角色)。
使用 CLI 为 PostgreSQL 数据库实例添加 IAM 角色
-
使用以下命令将角色添加到名为
my-db-cluster
的 PostgreSQL 数据库集群中。将
替换为您在上一步中记下的角色 ARN。使用your-role-arn
s3Import
作为--feature-name
选项的值。例
对于 Linux、macOS 或 Unix:
aws rds add-role-to-db-cluster \ --db-cluster-identifier
my-db-cluster
\ --feature-name s3Import \ --role-arnyour-role-arn
\ --regionyour-region
对于 Windows:
aws rds add-role-to-db-cluster ^ --db-cluster-identifier
my-db-cluster
^ --feature-name s3Import ^ --role-arnyour-role-arn
^ --regionyour-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 文件数据时遇到连接问题,请参阅以下内容以了解相应的建议:
-
Amazon Simple Storage Service 用户指南中的排查 Amazon S3 的问题
-
IAM 用户指南中的排查 Amazon S3 和 IAM 的问题
使用 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。
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 ...
导入使用自定义分隔符的文件
-
在数据库中为导入的数据创建一个表。
psql=> CREATE TABLE test (a text, b text, c text, d text, e text);
-
使用以下形式的 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 Web Services Management Console 上传文件,则元数据通常由系统应用。有关使用 Amazon Web Services Management Console、Amazon CLI 或 API 将文件上传到 Amazon S3 的信息,请参阅《Amazon Simple Storage Service 用户指南》中的上传对象。
有关 Amazon S3 元数据的更多信息以及有关系统提供的元数据的详细信息,请参阅《Amazon Simple Storage Service 用户指南》中的在 Amazon 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
函数。返回值为文本。
语法
必需的参数为 table_name
、column_list
和 options
。这些标识数据库表并指定如何将数据复制到表中。
您还可以使用以下参数:
-
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 )
参数
- 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_info
和 credentials
参数。下面是 aws_s3.table_import_from_s3
函数的其他语法变化。
-
不使用
s3_info
参数来标识 Amazon S3 文件,而使用bucket
、file_path
和region
参数的组合。使用此形式的函数,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_key
、session_key
和session_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 )
替代参数
- bucket
-
包含 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 函数的结果。
语法
aws_commons.create_s3_uri( bucket text, file_path text, region text )
参数
- 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 函数的结果。
语法
aws_commons.create_aws_credentials( access_key text, secret_key text, session_token text )
参数
- access_key
-
包含用于导入 Amazon S3 文件的访问密钥的必需文本字符串。默认值为 NULL。
- secret_key
-
包含用于导入 Amazon S3 文件的私有密钥的必需文本字符串。默认值为 NULL。
- session_token
-
包含用于导入 Amazon S3 文件的会话令牌的可选文本字符串。默认值为 NULL。如果您提供了可选的
session_token
,则可以使用临时凭证。