从补丁 198 开始，Amazon Redshift 将不再支持创建新的 Python UDF。现有的 Python UDF 将继续正常运行至 2026 年 6 月 30 日。有关更多信息，请参阅[博客文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。 # 查询数据库 要查询 Amazon Redshift 集群托管的数据库，您有两种选择： + 连接到您的集群，并使用查询编辑器在 AWS 管理控制台上运行查询。 如果您在 Amazon Redshift 控制台上使用查询编辑器，则无需下载和设置 SQL 客户端应用程序。 + 通过 SQL 客户端工具（如 SQL Workbench/J）连接到集群。 Amazon Redshift 支持通过 Java 数据库连接 (JDBC) 和开放式数据库连接 (ODBC) 来连接 SQL 客户端工具。Amazon Redshift 不提供或安装任何 SQL 客户端工具或库，因此您必须将其安装到您的客户端计算机或 Amazon EC2 实例上才能使用它们。您可以使用支持 JDBC 或 ODBC 驱动程序的大多数 SQL 客户端工具。 **注意** 在编写存储过程时，我们建议使用最佳实践来保护敏感值： 不要在存储过程逻辑中对任何敏感信息进行硬编码。例如，不要在存储过程主体的 CREATE USER 语句中分配用户密码。这会带来安全风险，因为硬编码值可以作为架构元数据记录在目录表中。而是应通过参数将诸如密码之类的敏感值作为参量传递给存储过程。 有关存储过程的更多信息，请参阅 [CREATE PROCEDURE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_PROCEDURE.html) 和[在 Amazon Redshift 中创建存储过程](https://docs.aws.amazon.com/redshift/latest/dg/stored-procedure-overview.html)。有关目录表的更多信息，请参阅[系统目录表](https://docs.aws.amazon.com/redshift/latest/dg/c_intro_catalog_views.html)。 # 连接到 Amazon Redshift 您可以使用以下语法连接到数据库。 ``` cluster-name.account-number.aws-region.redshift.amazonaws.com/database-name ``` 语法元素定义如下。 + `cluster-name` 您的集群名称。 + `account-number` 在给定 AWS 区域中，与您的 AWS 账号关联的唯一标识符。由给定账户在给定 AWS 区域中创建的所有集群都具有相同的 `account-number`。 + `aws-region` 集群所在的 AWS 区域的代码。 + `database-name` 您的数据库名称。 例如，以下连接字符串指定 AWS 区域 us-east-1 的 `my-cluster` 集群中的 `my-db` 数据库。 ``` my-cluster.123456789012.us-east-1.redshift.amazonaws.com/my-db ``` # 使用查询编辑器 v2 查询数据库 查询编辑器 v2 是一个单独的基于 Web 的 SQL 客户端应用程序，用于在 Amazon Redshift 数据仓库上创作和运行查询。查询编辑器 v2 主要用于编辑和运行查询、可视化结果以及与团队共享您的工作。使用查询编辑器 v2，您可以创建数据库、架构、表和用户定义的函数 (UDF)。在树视图面板中，对于每个数据库，您都可以查看其架构。对于每个架构，您都可以查看其表、视图、UDF 和存储过程。查询编辑器 v2 是以前的查询编辑器的替代品。 **注意** 已在商业 AWS 区域提供查询编辑器 v2。有关提供了查询编辑器 v2 的 AWS 区域的列表，请参阅《Amazon Web Services 一般参考》**中为 [Redshift 查询编辑器 v2](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 列出的端点。 要了解查询编辑器 v2 的演示，请观看以下视频。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/IwZNIroJUnc/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/IwZNIroJUnc) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/4EIV4XTE9iI/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/4EIV4XTE9iI) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/7y-f1wlyVhI/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/7y-f1wlyVhI) 查询编辑器 v2 具有一组丰富的功能来管理和运行 SQL 语句。以下各部分中的主题可让您使用其中的许多功能。请亲自浏览查询编辑器 v2 以熟悉其功能。 # 配置您的 AWS 账户 可以执行这组任务，来将查询编辑器 v2 配置为查询 Amazon Redshift 数据库。使用适当的权限，您可以访问当前 AWS 区域中您的 AWS 账户拥有的 Amazon Redshift 集群或工作组中的数据。 管理员第一次为您的 AWS 账户配置查询编辑器 v2 时，他们会选择用于加密查询编辑器 v2 资源的 AWS KMS key。默认情况下，AWS 拥有的密钥用于加密资源。或者，管理员可在配置页面中为密钥选择 Amazon 资源名称（ARN）来使用客户托管密钥。 配置账户后，AWS KMS 无法更改加密设置。有关通过查询编辑器 v2 创建和使用客户托管式密钥的更多信息，请参阅[创建用于查询编辑器 v2 的 AWS KMS 客户托管式密钥](#query-editor-v2-kms-key)。（可选）管理员还可以选择用于某些功能（例如从文件加载数据）的 S3 桶和路径。有关更多信息，请参阅 [从本地文件设置和工作流加载数据](query-editor-v2-loading-data-local.md)。 Amazon Redshift 查询编辑器 v2 支持身份验证、加密、隔离和合规性，以确保静态数据和传输中的数据安全。有关数据安全性和查询编辑器 v2 的更多信息，请参阅以下内容： + [静态加密](security-server-side-encryption.md) + [传输中加密](security-encryption-in-transit.md) + [Amazon Redshift 中的配置和漏洞分析](security-vulnerability-analysis-and-management.md) AWS CloudTrail 捕获由您的 AWS 账户 或代表该账户发出的 API 调用和相关事件，并将日志文件传输到您指定的 Amazon S3 存储桶。您可以标识哪些用户和账户调用了 AWS、发出调用的源 IP 地址以及调用的发生时间。要了解有关查询编辑器 v2 如何在 AWS CloudTrail 上运行的更多信息，请参阅[使用 Cloudtrail 进行日志记录](logging-with-cloudtrail.md)。有关 CloudTrail 的更多信息，请参阅《AWS CloudTrail 用户指南》[https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)。 查询编辑器 v2 对其部分资源具有可调配额。有关更多信息，请参阅[Amazon Redshift 对象的配额](amazon-redshift-limits.md#amazon-redshift-limits-quota)。 ## 使用查询编辑器 v2 创建的资源 在查询编辑器 v2 中，您可以创建资源，例如保存的查询和图表。查询编辑器 v2 中的所有资源都与 IAM 角色或用户关联。我们建议将策略附加到 IAM 角色并将该角色分配给用户。 在查询编辑器 v2 中，您可以添加和删除已保存查询和图表的标签。您可以在设置自定义 IAM 策略或搜索资源时使用这些标签。您还可以使用 AWS Resource Groups 标签编辑器来管理标签。 您可以使用 IAM 策略设置 IAM 角色，以便与 AWS 区域中相同 AWS 账户中的其他人共享查询。 ## 创建用于查询编辑器 v2 的 AWS KMS 客户托管式密钥 **创建对称加密客户托管式密钥**： 使用 AWS KMS 控制台或 AWS KMS API 操作，您可以创建对称加密客户托管式密钥来加密查询编辑器 v2 资源。有关创建密钥的说明，请参阅《AWS Key Management Service Developer Guide》**中的 [Creating symmetric encryption AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk)。 **密钥策略** 密钥策略控制对客户托管密钥的访问。每个客户托管式密钥必须只有一个密钥策略，其中包含确定谁可以使用密钥以及如何使用密钥的声明。创建客户托管式密钥时，可以指定密钥策略。有关更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[管理对 AWS KMS 密钥的访问](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html#managing-access)。 要将您的客户托管式密钥与 Amazon Redshift 查询编辑器 v2 一起使用，密钥策略中必须允许以下 API 操作： + `kms:GenerateDataKey` – 生成唯一的对称数据密钥以加密您的数据。 + `kms:Decrypt` – 解密客户托管式密钥加密的数据。 + `kms:DescribeKey` – 提供客户托管式密钥详细信息以允许验证密钥服务。 以下是 AWS 账户 `111122223333` 的示例 AWS KMS 策略。在第一部分中，`kms:ViaService` 限制对查询编辑器 v2 服务的密钥使用（在策略中名为 `sqlworkbench.region.amazonaws.com`）。使用密钥的 AWS 账户 必须为 `111122223333`。在第二部分中，AWS 账户 `111122223333`的根用户和主要管理员可以访问密钥。 当您创建 AWS 账户 时，最初使用的是一个对所有 AWS 服务和资源拥有完全访问权限的登录身份（称为 AWS 账户*根用户*）。我们强烈建议不要使用根用户进行日常任务。有关要求根用户凭证的任务，请参阅*《IAM 用户指南》*中的[需要根用户凭证的任务](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "key-consolepolicy", "Statement": [ { "Sid": "Allow access to principals authorized to use Amazon Redshift Query Editor V2", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "kms:GenerateDataKey", "kms:Decrypt", "kms:DescribeKey" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": "sqlworkbench.us-east-1.amazonaws.com", "kms:CallerAccount": "111122223333" } } }, { "Sid": "Allow access for key administrators", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": [ "kms:*" ], "Resource": "arn:aws:kms:us-east-1:111122223333:key/key_ID" } ] } ``` ------ 以下资源提供有关 AWS KMS 密钥的更多信息： + 有关 AWS KMS 策略的更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[在策略中指定权限](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html#overview-policy-elements)。 + 有关 AWS KMS 策略故障排除的信息，请参阅《AWS Key Management Service 开发人员指南》**中的[密钥访问故障排除](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html#example-no-iam)。 + 有关密钥的更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的 [AWS KMS 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys)。 ## 访问查询编辑器 v2 如要访问查询编辑器 v2，您需要相应权限。管理员可以将下面的任何一种 AWS 托管式策略附加到该角色以授予权限。（我们建议将策略附加到 IAM 角色并将该角色分配给用户。） 这些 AWS 托管式策略使用不同的选项编写，可控制标记资源允许共享查询的方式。您可以使用 IAM 控制台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) 附加 IAM 策略。 + **AmazonRedshiftQueryEditorV2FullAccess** – 授予 Amazon Redshift 查询编辑器 v2 操作和资源的完全访问权限。此策略还授予访问其它所需服务的权限。 + **AmazonRedshiftQueryEditorV2NoSharing** – 授予在不共享资源的情况下使用 Amazon Redshift 查询编辑器 v2 的权限。此策略还授予访问其它所需服务的权限。 + **AmazonRedshiftQueryEditorV2ReadSharing** – 授予在共享有限制资源的情况下使用 Amazon Redshift 查询编辑器 v2 的权限。授予主体可以阅读与其团队共享的资源，但无法更新它们。此策略还授予访问其它所需服务的权限。 + **AmazonRedshiftQueryEditorV2ReadWriteSharing** – 授予在共享资源的情况下使用 Amazon Redshift 查询编辑器 v2 的权限。授予主体可以读取和更新与其团队共享的资源。此策略还授予访问其它所需服务的权限。 您还可以根据提供的托管式策略中允许和拒绝的权限创建您自己的策略。如果您使用 IAM 控制台策略编辑器创建自己的策略，请选择 **SQL Workbench** 作为您在可视化编辑器中创建策略的服务。查询编辑器 v2 使用可视化编辑器和 IAM policy simulator 中的服务名称 AWS SQL Workbench。 要让主体（分配了 IAM 角色的用户）能够连接到 Amazon Redshift 集群，他们需要其中一个查询编辑器 v2 托管式策略中的权限。他们还需要对集群的 `redshift:GetClusterCredentialsWithIAM` 或 `redshift:GetClusterCredentials` 权限之一。要获得此权限，具有管理权限的人员可以使用临时凭证，将策略附加到用于连接到集群的 IAM 角色。您可以将策略范围限定为特定集群，也可以设为常规范围。有关使用临时凭证的权限的更多信息，请参阅[创建有权调用 GetClusterCredentialsWithIAM 或 GetClusterCredentials 的 IAM 角色或用户](generating-iam-credentials-steps.md#generating-iam-credentials-role-permissions)。 要让主体（通常是分配了 IAM 角色的用户）能够在**账户设置**页面中为账户中的其他人开启**导出结果集**的功能，他们需要将 `sqlworkbench:UpdateAccountExportSettings` 权限附加到角色。此权限包含在 `AmazonRedshiftQueryEditorV2FullAccess` AWS 托管式策略中。 随着新功能添加到查询编辑器 v2，AWS 托管式策略将根据需要更新。如果您根据提供的托管式策略中允许和拒绝的权限创建自己的策略，请编辑您的策略以使其与托管式策略的更改保持同步。有关 Amazon Redshift 托管式策略的更多信息，请参阅[适用于 Amazon Redshift 的 AWS 托管式策略](redshift-iam-access-control-identity-based.md#redshift-policy-resources.managed-policies)。 要提供访问权限，请为您的用户、组或角色添加权限： + AWS IAM Identity Center 中的用户和群组： 创建权限集合。按照《AWS IAM Identity Center 用户指南》**中[创建权限集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)的说明进行操作。 + 通过身份提供者在 IAM 中托管的用户： 创建适用于身份联合验证的角色。按照《IAM 用户指南》**中[针对第三方身份提供者创建角色（联合身份验证）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)的说明进行操作。 + IAM 用户： + 创建您的用户可以担任的角色。按照《IAM 用户指南》**中[为 IAM 用户创建角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)的说明进行操作。 + （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《IAM 用户指南》**中[向用户添加权限（控制台）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)中的说明进行操作。 **注意** 如果 AWS IAM Identity Center 管理员删除了整个账户中某个特定权限集的所有权限集关联，则最初与所删除权限集关联的所有查询编辑器资源都将无法再访问。如果以后重新创建了相同的权限，系统还会创建一个新的内部标识符。由于内部标识符已更改，因此以前用户拥有的对查询编辑器资源的访问权限将不再有效。在管理员删除权限集之前，建议权限集的用户应导出查询编辑器资源作为备份。 ## 设置主体标签以从查询编辑器 v2 连接到集群或工作组 要使用联合用户选项连接到您的集群或工作组，请使用主体标签设置 IAM 角色或用户。或者，设置身份提供者 (IdP) 以传入 `RedshiftDbUser` 和（可选）`RedshiftDbGroups`。有关使用 IAM 管理标签的更多信息，请参阅《IAM 用户指南》**中的[在 AWS Security Token Service 中传递会话标签](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html)。要使用 AWS Identity and Access Management 设置访问权限，管理员可以使用 IAM 控制台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) 添加标签。 **将主体标签添加到 IAM 角色中** 1. 登录AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。 1. 在导航窗格中选择 **Roles**。 1. 使用联合用户选择需要访问查询编辑器 v2 的角色。 1. 选择**标签**选项卡。 1. 选择**管理标签**。 1. 选择**添加标签**，然后在**键**中输入 `RedshiftDbUser`，并输入联合用户名的**值**。 1. （可选）选择**添加标签**，然后在**键**中输入 `RedshiftDbGroups`，并且输入要与用户关联的组名称的**值**。 1. 选择**保存更改**以查看与您选择的 IAM 角色关联的标签列表。传播更改可能需要几秒时间。 1. 要使用联合用户，请在传播更改后刷新查询编辑器 v2 页面。 **设置身份提供者 (IdP) 以传递主体标签** 使用身份提供者 (IdP) 设置标签的过程因 IdP 而异。有关如何将用户和组信息传递给 SAML 属性的说明，请参阅 IdP 文档。正确进行配置后，以下属性将显示在 SAML 响应中，AWS Security Token Service 使用此响应填充 `RedshiftDbUser` 和 `RedshiftDbGroups` 的主体标签。 ``` db-user-name db-groups ``` 可选的 *db\$1groups* 必须是以冒号分隔的列表，例如 `group1:group2:group3`。 此外，您还可以设置 `TransitiveTagKeys` 属性以在角色链接过程中保留标签。 ``` RedshiftDbUser RedshiftDbGroups ``` 有关设置查询编辑器 v2 的更多信息，请参阅[使用查询编辑器 v2 所需的权限](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 有关如何设置 Active Directory 联合身份验证服务 (AD FS) 的信息，请参阅博客文章：[使用 Active Directory 联合身份验证服务 (AD FS) 进行 Amazon Redshift 查询编辑器 v2 联合访问](https://aws.amazon.com/blogs//big-data/federate-access-to-amazon-redshift-query-editor-v2-with-active-directory-federation-services-ad-fs-part-3/)。 有关如何设置 Okta 的信息，请参阅博客文章：[通过 Okta 对 Amazon Redshift 查询编辑器 v2 进行联合单点登录访问](https://aws.amazon.com/blogs//big-data/federate-single-sign-on-access-to-amazon-redshift-query-editor-v2-with-okta/)。 **注意** 当您使用查询编辑器 v2 的**联合用户**连接选项连接到集群或工作组时，身份提供者 (IdP) 可以为 `RedshiftDbUser` 和 `RedshiftDbGroups` 提供自定义主体标签。目前，AWS IAM Identity Center 不支持将自定义主体标签直接传递给查询编辑器 v2。 # 打开查询编辑器 v2 借助 Amazon Redshift，您可以使用 Amazon Redshift 控制台中的查询编辑器 v2 对数据仓库集群执行 SQL 查询。查询编辑器 v2 是一款基于 Web 的工具，为运行临时查询、探索数据和执行数据分析任务提供了友好的用户界面。以下各个部分将指导您完成在控制台中打开查询编辑器 v2 并有效地利用其功能的过程。 **如要打开查询编辑器 v2** 1. 登录到 AWS 管理控制台并打开 Amazon Redshift 控制台，网址：[https://console.aws.amazon.com/redshiftv2/](https://console.aws.amazon.com/redshiftv2/)。 1. 在导航器菜单中，选择**编辑器**，然后选择**查询编辑器 V2**。此时将在新的浏览器标签页中打开查询编辑器 v2。 查询编辑器页面有一个导航器菜单，您可以在其中选择视图，如下所示： **编辑器 ![\[Horizontal lines representing redacted or censored text.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-align-left.png)** 您可以管理和查询以表形式组织并包含在数据库中的数据。数据库可以包含存储的数据，也可以包含对存储在其他位置（如 Amazon S3）的数据的引用。连接到包含在集群或无服务器工作组中的数据库。 在**编辑器**视图中工作时，您有以下控件： + **集群**或 **工作组**字段显示您当前连接到的集群或工作组的名称。**数据库**字段显示集群或工作组内的数据库。您在**数据库**视图执行的操作默认会对您选择的数据库执行操作。 + 集群或工作组、数据库和架构的树视图层次结构视图。在架构下，您可以使用表、视图、函数和存储过程。树视图中的每个对象都支持上下文菜单来执行相关操作，例如对对象进行**刷新**或**删除**。 + 通过 ![\[The create icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png) **创建**操作来创建数据库、架构、表和函数。 + 通过![\[The upload icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-upload.png)**加载数据**操作将数据从 Amazon S3 或从本地文件加载到数据库。 + 通过 ![\[The floppy disk icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-floppy-disk.png) **保存**图标来保存您的查询。 + 通过 ![\[The shortcut icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-key-command.png) **快捷方式**图标来显示编辑器的键盘快捷键。 + ![\[The more actions icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-more.png) **更多**图标，用于在编辑器中显示更多操作。例如： + **与我的团队共享**，与您的团队共享查询或笔记本。有关更多信息，请参阅 [以团队形式协作和共享](query-editor-v2-team.md)。 + **快捷方式**，显示编辑器的键盘快捷键。 + **选项卡历史记录**，用于在编辑器中显示选项卡的选项卡历史记录。 + **刷新自动完成**，用于在编写 SQL 时刷新显示的建议。 + 可以在 ![\[The editor icon in the AWS Console where can enter and run queries.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png) **编辑器**区域中输入和运行查询。 运行查询后，**结果**选项卡随即显示结果。您可以打开此处的**图表**来可视化您的结果。还可以**导出**结果。 + ![\[The icon in the AWS Console where you can add sections to enter and run SQL or add Markdown.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png) **笔记本**区域，您可以在其中添加各部分，以输入和运行 SQL 或添加 Markdown。 运行查询后，**结果**选项卡随即显示结果。您可以在此处**导出**结果。 **查询 ![\[A folder icon used in the AWS Console used to query databases.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-folder-close.png)** 查询包含用于管理和查询数据库中数据的 SQL 命令。当您使用查询编辑器 v2 加载示例数据时，它还会为您创建和保存示例查询。 在选择了某个已保存的查询时，您可以使用上下文菜单（右键单击）打开、重命名和删除该查询。您可以选择**查询详细信息**，查看已保存查询的属性，例如**查询 ARN**。您还可以查看其版本历史记录、编辑附加到查询的标签，并将其与您的团队共享。 **笔记本 ![\[A book icon used in the AWS Console used as SQL notebook.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-manual.png)** SQL 笔记本包含 SQL 和 Markdown 单元格。使用笔记本可在单个文档中组织、注释及共享多个 SQL 命令。 在选择了某个已保存的笔记本时，您可以使用上下文菜单（右键单击）打开、重命名、复制和删除该笔记本。您可以选择**笔记本详细信息**，查看已保存笔记本的属性，例如**笔记本 ARN**。您还可以查看其版本历史记录、编辑附加到笔记本的标签，并将其与您的团队共享。有关更多信息，请参阅 [Amazon Redshift 中的笔记本笔记本](query-editor-v2-notebooks.md)。 **图表 ![\[Icon of a chart used in the AWS Console as visual representation of data.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-chart.png)** 图表是您的数据的可视化表示。查询编辑器 v2 提供了用于创建多种图表并保存它们的工具。 在选择了某个已保存的图表时，您可以使用上下文菜单（右键单击）打开、重命名和删除该图表。您可以选择**图表详细信息**，查看已保存图表的属性，例如 **图表 ARN**。您也可以编辑附加到图表的标签并将其导出。有关更多信息，请参阅 [可视化查询结果](query-editor-v2-charts.md)。 **历史记录 ![\[Icon of a clock used in the AWS Console for query history.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-clock.png)** 查询历史记录是您使用 Amazon Redshift 查询编辑器 v2 运行的查询的列表。这些查询作为单个查询运行，或作为 SQL 笔记本的一部分运行。有关更多信息，请参阅 [查看查询和选项卡历史记录](query-editor-v2-history.md)。 **计划查询 ![\[Icon of a calendar used in the AWS Console for scheduled queries.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-calendar.png)** 计划查询是设置为在特定时间开始的查询。 所有查询编辑器 v2 视图都有以下图标： + ![\[Icon of a quarter moon used in the AWS Console to switch between light and dark modes.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-moon.png) **可视化模式**图标，可在亮模式和暗模式之间切换。 + ![\[Icon of a gear used in the AWS Console to show settings.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-cog.png) **设置**图标，可显示不同设置屏幕的菜单。 + ![\[Icon used in the AWS Console to show editor preferences.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-properties.png) **编辑器首选项**图标，可在使用查询编辑器 v2 时编辑首选项。在此处，您可以**编辑工作区设置**以更改字体大小、选项卡大小和其它显示设置。您也可以打开（或关闭）**自动完成**，以便在输入 SQL 时显示建议。 + ![\[Icon used in the AWS Console to view connections used in the editor tab.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-connection.png) **连接**图标，可查看编辑器选项卡使用的连接。 连接用于检索数据库中的数据。连接是针对特定数据库创建的。使用隔离连接时，在一个编辑器选项卡中更改数据库的 SQL 命令（例如创建临时表）的结果在另一个编辑器选项卡中不可见。在查询编辑器 v2 中打开编辑器选项卡时，默认为隔离连接。创建共享连接时，即关闭**隔离会话**开关，同一数据库的其他共享连接的结果对彼此可见。但是，使用数据库的共享连接的各编辑器选项卡不会并行运行。使用相同连接的查询必须等到连接可用。与一个数据库的连接不能与另一个数据库共享，因此 SQL 结果在不同的数据库连接之间不可见。 账户中的任何用户可以激活的连接数由查询编辑器 v2 管理员控制。 + ![\[Icon used in the AWS Console used by administrators to change settings of user accounts.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-settings.png) **账户设置**图标，管理员用于更改账户中所有用户的某些设置。有关更多信息，请参阅 [账户设置](#query-editor-v2-settings)。 ## 使用查询编辑器 v2 时的注意事项 使用查询编辑器 v2 时，请注意以下几点。 + 查询的最长持续时间为 24 小时。 + 查询结果的最大大小为 100 MB。如果调用返回的响应数据超过 100 MB，则返回前 100 MB 数据并显示警告。 + 您可以运行最长为 300,000 个字符的查询。 + 您可以保存最长为 30,000 个字符的查询。 + 默认情况下，查询编辑器 v2 会自动提交所运行的每个 SQL 命令。当提供 BEGIN 语句时，BEGIN-COMMIT 或 BEGIN-ROLLBACK 块中的语句将作为单个事务运行。有关事务的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [BEGIN](https://docs.aws.amazon.com/redshift/latest/dg/r_BEGIN.html)。 + 运行 SQL 语句时，查询编辑器 v2 显示的最大警告数为 `10`。例如，运行存储过程时，显示的 RAISE 语句不超过 10 个。 + 查询编辑器 v2 不支持包含逗号（,）的 IAM `RoleSessionName`。您可能会看到类似以下的错误：错误消息：“‘AROA123456789EXAMPLE:mytext,yourtext’不是 TagValue 的有效值 - 它包含非法字符”。当您定义包含逗号的 IAM `RoleSessionName`，然后将查询编辑器 v2 与该 IAM 角色一起使用时，就会出现此问题。 有关 IAM `RoleSessionName` 的更多信息，请参阅《IAM 用户指南》**中的 [RoleSessionName SAML 属性](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-attribute)。 ## 账户设置 拥有正确 IAM 权限的用户可以查看和更改同一 AWS 账户中其他用户的**账户设置**。该管理员可以查看或设置以下内容： + 账户中每个用户的最大并发数据库连接数。这包括用于**隔离会话**的连接。更改此值时，更改可能需要 10 分钟才能生效。 + 允许账户中的用户将整个结果集从 SQL 命令导出到文件中。 + 加载和显示示例数据库以及一些关联的已保存查询。 + 指定账户用户用于从本地文件加载数据的 Amazon S3 路径。 + 查看用于加密查询编辑器 v2 资源的 KMS 密钥 ARN。 # 连接到 Amazon Redshift 数据库 要连接到数据库，请在树视图面板中选择集群或工作组名称。如果出现提示，请输入连接参数。 当您连接到集群或工作组及其数据库时，通常需要提供**数据库**名称。您还提供以下身份验证方法之一所需的参数： **IAM Identity Center 验证** 通过此方法，使用身份提供者 (IdP) 提供的单点登录凭证连接到您的 Amazon Redshift 数据仓库。您必须在 Amazon Redshift 控制台中为 IAM Identity Center 启用集群或工作组。如需帮助设置与 IAM Identity Center 的连接，请参阅 [将 Redshift 与 AWS IAM Identity Center 连接来提供单点登录体验](redshift-iam-access-control-idp-connect.md)。 **联合用户** 使用此方法，您的 IAM 角色或用户的主体标签必须提供连接详细信息。您可以在 AWS Identity and Access Management 或您的身份提供者 (IdP) 中配置这些标签。查询编辑器 v2 依赖以下标签。 + `RedshiftDbUser` – 此标签定义查询编辑器 v2 使用的数据库用户。此标签为必填项。 + `RedshiftDbGroups` – 此标签定义当连接到查询编辑器 v2 时加入的数据库组。此标签是可选的，其值必须是以冒号分隔的列表，例如 `group1:group2:group3`。空值将被忽略，也就是说，`group1::::group2` 被解释为 `group1:group2`。 这些标签将转发到 `redshift:GetClusterCredentials` API 以获取集群的凭证。有关更多信息，请参阅 [设置主体标签以从查询编辑器 v2 连接到集群或工作组](query-editor-v2-getting-started.md#query-editor-v2-principal-tags-iam)。 **使用数据库用户名的临时凭证** 仅在连接到集群时此选项才可用。使用此方法，查询编辑器 v2 会为数据库提供**用户名**。查询编辑器 v2 会生成临时密码，以便使用您的数据库用户名连接到数据库。必须允许使用此方法进行连接的用户对 `redshift:GetClusterCredentials` 拥有 IAM 权限。要防止用户使用此方法，请修改其 IAM 用户或角色以拒绝此权限。 **使用您的 IAM 身份的临时凭证** 仅在连接到集群时此选项才可用。使用此方法，查询编辑器 v2 会将用户名映射到您的 IAM 身份并生成临时密码，以便使用您的 IAM 身份连接到数据库。必须允许使用此方法进行连接的用户对 `redshift:GetClusterCredentialsWithIAM` 拥有 IAM 权限。要防止用户使用此方法，请修改其 IAM 用户或角色以拒绝此权限。 **数据库用户名和密码** 使用这种方法，还需要为要连接的数据库提供**用户名**和**密码**。查询编辑器 v2 代表您创建秘钥并存储在 AWS Secrets Manager 中。此密钥包含用于连接到数据库的凭证。 **AWS Secrets Manager** 使用此方法，不是提供数据库名称，而是提供在 Secrets Manager 中存储的**密钥**，其中包含您的数据库和登录凭证。有关创建密钥的信息，请参阅[为数据库连接凭证创建密钥](redshift-secrets-manager-integration-create.md)。 当您选择具有查询编辑器 v2 的集群或工作组时，根据上下文，您可以使用上下文（右键单击）菜单创建、编辑和删除连接。您可以选择**连接详细信息**，查看连接的属性，例如**连接 ARN**。您还可以编辑附加到连接的标签。 # 浏览 Amazon Redshift 数据库 在数据库中，您可以在树视图面板中管理架构、表、视图、函数和存储过程。在视图中的每个对象都在上下文（右键单击）菜单中都有与之关联的操作。 分层树状图面板显示数据库对象。要刷新树视图面板以显示可能已在上次显示树视图后创建的数据库对象，请选择 ![\[Circular arrow icon representing a refresh or reload action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-refresh.png) 图标。打开对象的上下文（右键单击）菜单，以查看您可以执行的操作。 ![\[Tree-view icons\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/sqlworkbench-tree-view.png) 选择表后，您可以执行以下操作： + 如要在编辑器中开启查询表中所有列的 SELECT 语句启动查询，请使用**选择表**。 + 要查看属性或表格，请使用**显示表定义**。使用此选项可查看列名、列类型、编码、分配键、排序键以及列是否可以包含空值。有关语法的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》[https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html)中的 *CREATE TABLE*。 + 要删除表，请使用**删除**。您可以使用**截断表**从表中删除所有行。或使用**删除表**从数据库中删除表。更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [TRUNCATE](https://docs.aws.amazon.com/redshift/latest/dg/r_TRUNCATE.html) 和 [DROP TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_DROP_TABLE.html)。 选择架构以**刷新**或**删除架构**。 选择视图以**显示视图定义**或**删除视图**。 选择函数以**显示函数定义**或**删除函数**。 选择存储过程以**显示过程定义**或**删除过程**。 # 创建数据库对象 您可以创建数据库对象，包括数据库、架构、表和用户定义的函数 (UDF)。您必须连接到集群或工作组以及数据库才能创建数据库对象。 ## 创建数据库 您可以使用查询编辑器 v2 在集群或工作组中创建数据库。 **创建数据库** 有关数据库的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [CREATE DATABASE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_DATABASE.html)。 1. 选择![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png)**创建**，然后选择**数据库**。 1. 输入**数据库名称**。 1. （可选）选择**用户和组**，然后选择**数据库用户**。 1. （可选）您可以从数据共享或 AWS Glue Data Catalog 创建数据库。有关 AWS Glue 的更多信息，请参阅《*AWS Glue 开发人员指南*》中的[什么是 AWS Glue？](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html)。 + （可选）选择**使用数据共享创建**，然后选择**选择数据共享**。该列表包括可用于在当前集群或工作组中创建使用者数据共享的创建者数据共享。 + （可选）选择**使用 AWS Glue Data Catalog 创建**，然后选择**选择 AWS Glue 数据库**。在**数据目录架构**中，输入在由三部分组成的名称（database.schema.table）中引用数据时将用于架构的名称。 1. 选择**创建数据库**。 新数据库将在树状视图面板中显示。 当您选择此可选步骤查询从数据共享创建的数据库时，请连接到集群或工作组中的 Amazon Redshift 数据库（例如，默认数据库 `dev`），并使用三部分表示法（database.schema.table），该表示法引用您在选择**使用数据共享创建**时创建的数据库名称。数据共享数据库在查询编辑器 v2 编辑器选项卡中列出，但未针对直接连接启用此数据库。 当您选择此可选步骤查询从 AWS Glue Data Catalog 创建的数据库时，请连接到集群或工作组中的 Amazon Redshift 数据库（例如，默认数据库 `dev`），并使用三部分表示法（database.schema.table），该表示法引用您在选择**使用 AWS Glue Data Catalog 创建**时创建的数据库名称、您在**数据目录架构**中命名的架构以及 AWS Glue Data Catalog 中的表。类似于： ``` SELECT * FROM glue-database.glue-schema.glue-table ``` **注意** 确认您已使用连接方法**使用您的 IAM 身份的临时凭证**连接到默认数据库，并且您的 IAM 凭证已被授予 AWS Glue 数据库的使用权限。 ``` GRANT USAGE ON DATABASE glue-database to "IAM:MyIAMUser" ``` AWS Glue 数据库在查询编辑器 v2 编辑器选项卡中列出，但未针对直接连接启用此数据库。 有关查询 AWS Glue Data Catalog 的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[以使用者身份使用 Lake Formation 托管的数据共享](https://docs.aws.amazon.com/redshift/latest/dg/lake-formation-getting-started-consumer.html)和[以创建者身份使用 Lake Formation 托管的数据共享](https://docs.aws.amazon.com/redshift/latest/dg/lake-formation-getting-started-producer.html)。 **示例：以数据共享使用者身份创建数据库** 以下示例描述了使用查询编辑器 v2 从数据共享创建数据库的特定场景。查看此场景，了解如何从环境中的数据共享创建数据库。此场景使用两个集群，即 `cluster-base`（创建者集群）和 `cluster-view`（使用者集群）。 1. 使用 Amazon Redshift 控制台为集群 `cluster-base` 中的 `category2` 表创建数据共享。创建者数据共享命名为 `datashare_base`。 有关创建数据共享的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[在 Amazon Redshift 中跨集群共享数据](https://docs.aws.amazon.com/redshift/latest/dg/datashare-overview.html)。 1. 使用 Amazon Redshift 控制台接受数据共享 `datashare_base` 作为集群 `cluster-view` 中 `category2` 表的使用者。 1. 在查询编辑器 v2 中查看树视图面板，该面板显示了 `cluster-base` 的层次结构，如下所示： + 集群：`cluster-base` + 数据库：`dev` + 架构：`public` + 表：`category2` 1. 选择![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png)**创建**，然后选择**数据库**。 1. 对于**数据库名称**，请输入 `see_datashare_base`。 1. 选择**使用数据共享创建**，然后选择**选择数据共享**。选择 `datashare_base` 以用作正在创建的数据库的来源。 查询编辑器 v2 中的树视图面板显示了 `cluster-view` 的层次结构，如下所示： + 集群：`cluster-view` + 数据库：`see_datashare_base` + 架构：`public` + 表：`category2` 1. 查询数据时，连接到集群 `cluster-view` 的默认数据库（通常命名为 `dev`），但在 SQL 中引用数据共享数据库 `see_datashare_base`。 **注意** 在查询编辑器 v2 编辑器视图中，选定的集群为 `cluster-view`。选定的数据库为 `dev`。数据库 `see_datashare_base` 已列出，但未针对直接连接启用此数据库。您可以在您运行的 SQL 中选择 `dev` 数据库并引用 `see_datashare_base`。 ``` SELECT * FROM "see_datashare_base"."public"."category2"; ``` 该查询从集群 `cluster_base` 中的数据共享 `datashare_base` 检索数据。 **从 AWS Glue Data Catalog 创建数据库的示例** 以下示例描述了使用查询编辑器 v2 从 AWS Glue Data Catalog 创建数据库的特定场景。查看此场景，了解如何从环境中的 AWS Glue Data Catalog 创建数据库。此场景使用一个集群（即 `cluster-view`）以包含您创建的数据库。 1. 选择![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png)**创建**，然后选择**数据库**。 1. 对于**数据库名称**，请输入 `data_catalog_database`。 1. 选择**使用 AWS Glue Data Catalog 创建**，然后选择**选择 AWS Glue 数据库**。选择 `glue_db` 以用作正在创建的数据库的来源。 选择**数据目录架构**，然后输入 `myschema` 作为要在三部分表示法中使用的架构名称。 查询编辑器 v2 中的树视图面板显示了 `cluster-view` 的层次结构，如下所示： + 集群：`cluster-view` + 数据库：`data_catalog_database` + 架构：`myschema` + 表：`category3` 1. 查询数据时，连接到集群 `cluster-view` 的默认数据库（通常命名为 `dev`），但在 SQL 中引用数据库 `data_catalog_database`。 **注意** 在查询编辑器 v2 编辑器视图中，选定的集群为 `cluster-view`。选定的数据库为 `dev`。数据库 `data_catalog_database` 已列出，但未针对直接连接启用此数据库。您可以在您运行的 SQL 中选择 `dev` 数据库并引用 `data_catalog_database`。 ``` SELECT * FROM "data_catalog_database"."myschema"."category3"; ``` 该查询检索由 AWS Glue Data Catalog 编目的数据。 ## 创建架构 您可以使用查询编辑器 v2 在集群或工作组中创建架构。 **创建架构** 有关架构的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Schemas](https://docs.aws.amazon.com/redshift/latest/dg/r_Schemas_and_tables.html)。 1. 选择 ![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png)**创建**，然后选择**架构**。 1. 输入**架构名称**。 1. 选择**本地**或**外部**作为**架构类型**。 有关本地架构的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [CREATE SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_SCHEMA.html)。有关外部架构的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [CREATE EXTERNAL SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。 1. 如果选择**外部**，则可以选择以下外部架构。 + **Glue 数据目录** – 在 Amazon Redshift 中创建引用 AWS Glue 中的表的外部架构。除了选择 AWS Glue 数据库，还可选择与集群关联的 IAM 角色以及与数据目录关联的 IAM 角色。 + **PostgreSQL** – 在 Amazon Redshift 中创建外部架构，此架构引用 Amazon RDS for PostgreSQL 或 Amazon Aurora PostgreSQL 兼容版本的数据库。还提供数据库的连接信息。有关联合查询的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[通过联合查询来查询数据](https://docs.aws.amazon.com/redshift/latest/dg/federated-overview.html)。 + **MySQL** – 在 Amazon Redshift 中创建外部架构，该架构引用 Amazon RDS for MySQL 和/或 Amazon Aurora MySQL 兼容版本的数据库。还提供数据库的连接信息。有关联合查询的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[通过联合查询来查询数据](https://docs.aws.amazon.com/redshift/latest/dg/federated-overview.html)。 1. 选择**创建架构**。 新 Schema 将在树状视图面板中显示。 ## 创建表 您可以使用查询编辑器 v2 在集群或工作组中创建表。 **创建表** 您可以根据您指定或定义表中每列的逗号分隔值 (CSV) 文件创建表。有关表的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Designing tables](https://docs.aws.amazon.com/redshift/latest/dg/c_designing-tables-best-practices.html) 和 [CREATE TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html)。 选择**在编辑器中打开查询**在运行查询以创建表之前查看和编辑 CREATE TABLE 语句。 1. 选择 ![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png) **创建**，然后选择**表**。 1. 选择架构。 1. 输入表名称。 1. 选择 ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png) **添加字段**以添加列。 1. 使用 CSV 文件作为表定义模板： 1. 选择**从 CSV 加载**。 1. 浏览到文件位置。 如果您使用 CSV 文件，请确保该文件的第一行包含列标题。 1. 选择文件，然后选择**打开**。确认列名和数据类型符合您的要求。 1. 对于每一列，选择该列并选择所需的选项： + 为**编码**选择一个值。 + 选择**默认值**。 + 如果您想增加列值，启用**自动增量**。然后为**自动增加种子**和**自动增量步骤**指定值。 + 如果该列应始终包含值，启用**非 NULL**。 + 输入列的**大小**值。 + 如您希望该列成为主密钥，启用**主密钥**。 + 如您希望该列成为唯一密钥，启用**唯一密钥**。 1. （可选）选择**表详细信息**然后选择以下任何选项： + 分配密钥列和样式。 + 对密钥列进行排序和排序类型。 + 启用**备份**将表包含在快照中。 + 启用**临时表**将表创建为临时表。 1. 选择**在编辑器中打开查询**继续指定用于定义表的选项，或选择**创建表**来创建表。 ## 创建函数 您可以使用查询编辑器 v2 在集群或工作组中创建函数。 **创建函数** 1. 选择 ![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png)**创建**，然后选择**函数**。 1. 对于**类型**，选择 **SQL** 或 **Python**。 1. 为**架构**选择一个值。 1. 为函数**名称**输入一个值。 1. 为函数**波动性**输入一个值。 1. 按输入参数的顺序排列的数据类型选择**参数**。 1. 为**返回值**选择一种数据类型。 1. 输入此函数的 **SQL 程序**或 **Python 程序**代码。 1. 选择**创建**。 有关用户定义的函数 (UDF) 的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[创建用户定义的函数](https://docs.aws.amazon.com/redshift/latest/dg/user-defined-functions.html)。 # 查看查询和选项卡历史记录 您可以使用查询编辑器 v2 查看查询历史记录。仅使用查询编辑器 v2 运行的查询出现在查询历史记录中。显示已使用**编辑器**选项卡或**笔记本**选项卡运行的查询。您可以按时间段筛选显示的列表，例如 `This week`，其中周定义为星期一至星期日。查询列表一次将提取符合您的筛选条件的 25 行查询。选择**加载更多**可查看下一组。选择一个查询，在**操作**菜单中，可用的操作取决于是否已保存所选的查询。您还可以选择以下操作： + **查看查询详细信息** - 显示一个查询详细信息页面，其中包含有关已运行的查询的更多信息。 + **在新选项卡中打开查询** - 打开一个新的编辑器选项卡，并在其中填入所选查询。如果仍处于连接状态，则会自动选择集群或工作组和数据库。要运行查询，请先确认已选择正确的集群或工作组和数据库。 + **打开源选项卡** - 如果仍处于打开状态，则在运行查询时导航到包含查询的编辑器或笔记本选项卡。运行查询后，编辑器或笔记本的内容可能已发生更改。 + **打开保存的查询** - 导航到编辑器或笔记本选项卡并打开查询。 您还可以查看**编辑器**选项卡中运行的查询的历史记录或**笔记本**选项卡中运行的查询的历史记录。要在选项卡中查看查询历史记录，请选择**选项卡历史记录**。在选项卡历史记录中，您可以执行以下操作： + **复制查询** - 将查询版本 SQL 内容复制到剪贴板。 + **在新选项卡中打开查询** - 打开一个新的编辑器选项卡，并在其中填入所选查询。要运行查询，您必须选择集群或工作组和数据库。 + **查看查询详细信息** - 显示一个查询详细信息页面，其中包含有关已运行的查询的更多信息。 # 与 Amazon Q 生成式 SQL 交互 **注意** 只有以下 AWS 区域中支持 Amazon Q 生成式 SQL： 美国东部（弗吉尼亚北部）区域 (us-east-1) 美国东部（俄亥俄）区域 (us-east-2) 美国西部（俄勒冈州）区域（us-west-2） 亚太地区（孟买）区域 (ap-south-1) 亚太地区（首尔）区域 (ap-northeast-2) 亚太地区（新加坡）区域 (ap-southeast-1) 亚太地区（悉尼）区域 (ap-southeast-2) 亚太地区（东京）区域（ap-northeast-1） 加拿大（中部）区域 (ca-central-1) 欧洲（法兰克福）区域 (eu-central-1) 欧洲（爱尔兰）区域 (eu-west-1) 欧洲（伦敦）区域 (eu-west-2) 欧洲（巴黎）区域 (eu-west-3) 南美洲（圣保罗）区域 (sa-east-1) 有关数据处理位置的信息，请参阅《Amazon Q 开发者版用户指南》**中的 [Cross region inference in Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/cross-region-inference.html)。 您可以在 Amazon Redshift 查询编辑器 v2 中，与 Amazon Q 生成式 SQL 功能进行交互。这是一个编码助手，可以根据您的提示和数据库架构生成 SQL 语句。当您在查询编辑器 v2 中撰写笔记本时，可以使用这个编码助手。生成的 SQL 用于笔记本所连接的数据库。 在与 Amazon Q 生成式 SQL 交互时，请提出具体问题，在有复杂请求时进行迭代，并验证答案的准确性。 在以自然语言提供分析请求时，请尽可能具体，以便编码助手准确了解您的需求。正确的做法不是询问“查找门票销量最高的前几个场馆”，而是要提供更多详细信息，例如“查找 2008 年门票销量最高的前三个场馆的名称/ID”。如果您知道数据库中对象的名称，请使用一致且具体的名称。例如，使用数据库中定义的架构、表和列名称，而不是以不同的方式引用同一对象，这会让助手不明所以。 将复杂的请求拆分为多个简单的语句，便于助手解释。反复提出跟进问题，让助手提供更详细的分析。例如，首先问“哪个州的场馆最多？” 然后根据回答，问“这个州最受欢迎的场馆是哪个？”。 在运行生成的 SQL 之前，请对其进行检查，以确保准确性。如果生成的 SQL 查询存在错误或与您的意图不符，请向助手提供如何更正查询的说明，而不是以不同的措辞来重述整个请求。例如，如果查询中缺少关于年份的谓词从句，请询问“提供 2008 年的场馆”。 将运行生成的 SQL 时收到的错误文本作为提示提交回 Amazon Q 生成式 SQL。它能从这些错误中学习，从而生成更好的 SQL。 将您的架构添加到 SQL 搜索路径中，以表示应使用该架构。例如，当数据在 tickit 架构而非公共架构中时，添加 tickit 架构。 ``` set search_path to '$user', tickit; ``` ## 与 Amazon Q 生成式 SQL 交互时的注意事项 使用聊天面板时，请注意以下几点。 + 账户的查询编辑器 v2 管理员必须已在**生成式 SQL 设置**页面中开启聊天功能。 + 要使用 Amazon Q 生成式 SQL，除了在查询编辑器 v2 的 AWS 托管策略中指定的其它权限外，还需要在 IAM 策略中指定 `sqlworkbench:GetQSqlRecommendations` 权限。有关 AWS 托管策略的更多信息，请参阅[访问查询编辑器 v2](query-editor-v2-getting-started.md#query-editor-v2-configure)。 + 您必须使用英语撰写问题。 + 问题必须与集群或工作组中连接的数据库有关。为避免空状态错误，数据库中应至少有一个表和一些数据。 + 您的问题必须与所连接数据库中存储的数据有关。它不能引用外部架构。有关所支持架构的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[创建架构](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。 + 如果在任何问题中会导致 SQL 更改所连接数据库，就可能产生警告。 + 生成式人工智能技术是一项全新的技术，其回复中可能会出现错误，有时将这种错误称为幻觉。在您的环境或工作负载中使用代码之前，请对所有代码进行测试并检查是否存在错误和漏洞。 + 您可以通过分享账户中其他用户运行的 SQL 查询来改进建议。账户管理员可以运行以下 SQL 命令来允许访问账户的查询历史记录。 ``` GRANT ROLE SYS:MONITOR to "IAMR:role-name"; GRANT ROLE SYS:MONITOR to "IAM:user-name"; GRANT ROLE SYS:MONITOR to "database-username"; ``` 有关 `SYS:MONITOR` 的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Amazon Redshift 系统定义的角色](https://docs.aws.amazon.com/redshift/latest/dg/r_roles-default.html)。 + 您的数据是安全和私密的。数据不会跨账户共享。您的查询、数据和数据库架构不会用于训练生成式人工智能基础模型 (FM)。您的输入将用作 FM 的上下文提示，仅用于回答您的查询。 # 使用生成式 SQL 配置了正确的权限后，在查询编辑器 v2 中处理笔记本时，您可以选择一个图标开始对话。 **与 Amazon Q 生成式 SQL 聊天进行交互以生成 SQL** 1. 在查询编辑器 v2 的**编辑器**选项卡中，打开笔记本。 1. 选择 ![\[Generative SQL panel\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-amazon-q.png) 生成式 SQL 图标，然后在聊天面板中，按照说明向 Amazon Redshift 查询编辑器 v2 生成式 SQL 提问。 您在提示字段中提出问题，Amazon Q 生成式 SQL 就会给出建议的 SQL。所出现的任何错误都会在聊天面板中返回给您。 1. 选择**添加到笔记本**，在笔记本中添加一个带有您的提示的 Markdown 单元格，以及一个包含建议 SQL 的 SQL 单元格。 1. （可选）选择 ![\[Helpful feedback\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-thumbs-up.png)“有帮助”反馈图标或 ![\[Not helpful feedback\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-thumbs-down.png)“没有作用”反馈图标，针对生成的 SQL 提供反馈。您可以将“没有作用”反馈归类为 `Incorrect tables/columns`、`Incorrect predicates/literals/group bys`、`Incorrect SQL structure` 或 `Other`。此外，您还可以提供一些自由格式的文本，对 SQL 的准确性提出反馈。 1. （可选）选择**重新生成 SQL**，对相同的提示生成另一个回复。您可以选择为当前提示**重新生成 SQL**一次。 1. （可选）在生成式 SQL 聊天面板中，选择 ![\[More\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-vmore.png) **更多**图标，然后选择**刷新数据库**以刷新描述所连接数据库的元数据。此元数据包括数据库中架构、表和列的定义。 # 以管理员身份更新生成式 SQL 设置 拥有正确 IAM 权限的用户可以查看和更改相同 AWS 账户中其他用户的**生成式 SQL 设置**。在查询编辑器 v2 的 AWS 托管策略中指定的其他权限之外，此管理员在其 IAM 策略中还必须拥有 `sqlworkbench:UpdateAccountQSqlSettings` 权限。有关 托管策略的更多信息，请参阅[使用查询编辑器 v2 所需的权限](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 **管理员为账户中的所有用户开启生成式 SQL 聊天** 1. 选择 ![\[Settings\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-cog.png) **设置**图标以显示不同设置屏幕的菜单。 1. 然后选择 ![\[Generative SQL settings\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-amazon-q.png) 生成式 SQL 设置图标以显示 **Q 生成式 SQL 设置**页面。 1. 选择 **Q 生成式 SQL 设置**来为账户中的用户开启生成式 SQL 功能。 开启 Amazon Q 生成式 SQL 后，您可以查看分配中剩余的提示数。查询编辑器 v2 管理员可以让账户中的用户使用 Amazon Q 开发者版专业套餐。要使用专业套餐，请使用 IAM Identity Center 设置用户，并让每个用户订阅 Amazon Q 开发者版专业套餐。有关使用 Amazon Redshift 设置 IAM Identity Center 的信息，请参阅 [将 Redshift 与 AWS IAM Identity Center 连接来提供单点登录体验](redshift-iam-access-control-idp-connect.md)。有关 Amazon Q 开发者版定价的信息，请参阅 [Amazon Q 开发者版定价](https://aws.amazon.com/q/developer/pricing/)。 使用 Amazon Q 开发者版免费套餐时，AWS 账户 所有用户的提示总数在一个月内限制为 1000。使用 Amazon Q 开发者版专业套餐时，单个用户每月可提交的提示总数限制为 1000。您可以在**设置**页面上查看可用的提示数量。有关 Amazon Q 开发者版定价的信息，请参阅 [Amazon Q 开发者版定价](https://aws.amazon.com/q/developer/pricing/)。 ## 自定义上下文 查询编辑器 v2 管理员可以指定*自定义上下文*，以便根据环境定制生成的 SQL。自定义上下文提供领域知识和偏好设置，可对 SQL 生成进行精细控制。自定义上下文在 JSON 文件中定义，可由查询编辑器 v2 管理员上传到 Amazon Q 生成式 SQL。 用于为数据仓库个性化设置生成的 SQL 的 JSON 键如下。 所有表引用均需遵循三部分表示法 `database.schema.table`。 **资源** 资源指定了应用自定义上下文的数据资产的范围或部分。 **ResourceId** 指定资源的唯一标识符。对于 Amazon Redshift 集群，请指定 `cluster id`。对于 Redshift Serverless 工作组，请指定 `workgroup name`。 **ResourceType** 有效值：`REDSHIFT_WAREHOUSE`。 **TablesToInclude** 指定生成 SQL 时要考虑的一组表。如果要将 SQL 查询的范围限制在已定义的可用表子集上，该字段至关重要。该字段可以减少不必要的表引用，有助于优化生成过程。您可以将该字段与 `TablesToExclude` 搭配使用，以便更精细地控制查询的生成。 **TablesToExclude** 指定从 SQL 生成中排除的表集。当某些表无关紧要或不应在查询生成过程中考虑时，请使用该字段。 **TableAnnotations** 提供有关所用表的元数据或补充信息。这些注释可包括表描述、使用说明或任何其它属性，以便于 Amazon Q 生成式 SQL 更好地理解表的上下文或结构。这对于通过增加表定义的清晰度来提高 SQL 生成的准确性非常有价值。 **ColumnsToInclude** 定义在生成 SQL 查询时包含指定表中的哪些列。该字段有助于 Amazon Q 生成式 SQL 将重点放在相关列上，并通过缩小数据检索范围来提高性能。该字段可确保 Amazon Q 生成式 SQL 只提取给定查询上下文所需的数据。 **ColumnsToExclude** 指定在生成 SQL 时不考虑的列。当某些列包含 Amazon Q 生成式 SQL 不应考虑的无关数据或冗余数据时，可以使用该字段。通过管理列的包含和排除，您可以优化结果并保持对检索到的数据的控制。 **ColumnAnnotations** 与 `TableAnnotations` 类似，该字段提供特定于各个列的元数据或注释。这些注释可以提供对列定义或特殊处理说明的深入了解。这些信息有助于指导 SQL 生成过程，并确保在查询中适当使用列。 **CuratedQueries** 一组预定义的问题和答案示例，其中问题是用自然语言（NLQ）编写的，答案是相应的 SQL 查询。这些示例有助于 Amazon Q 生成式 SQL 理解其预期生成的查询类型。它们是提高 Amazon Q 生成式 SQL 输出准确性和相关性的参考点。 **CustomDocuments** 为 Amazon Q 生成式 SQL 提供的附加信息或提示，如定义、特定领域知识或解释。例如，如果您的业务部门使用一种独特的方法来计算某个值，如“制造部门的总销售额为价格 \$1 收入”，则可以在此记录下来。这些文档通过提供额外的上下文，增强了 Amazon Q 生成式 SQL 解释自然语言输入的能力。 **AdditionalTables** 指定生成 SQL 时应考虑但不属于存储在数据仓库中的数据的任何其它表。这使得 Amazon Q 生成式 SQL 能够将外部数据来源整合到其 SQL 生成逻辑中，从而扩大其处理复杂数据环境的能力。 **AppendToPrompt** 为 Amazon Q 生成式 SQL 提供的附加说明或指南，用于指导 SQL 生成过程。这可以包括有关如何构造查询的具体指令、对某些 SQL 构造的偏好，或任何其它可提高 Amazon Q 生成式 SQL 输出质量的高级指令。 下面的自定义上下文示例向您展示了 JSON 文件的格式，并定义了以下内容： + 为集群 `mycluster` 的 Amazon Redshift 数据仓库定义自定义上下文。 + 定义要包含和排除的特定表和列，以便于优化 SQL 生成过程。 + 定义要包含的表和列的注释。 + 定义供 Amazon Q 生成式 SQL 使用的精选查询示例。 + 定义生成 SQL 时要使用的自定义文档和护栏。 + 定义生成 SQL 时要使用的附加表 DDL。 ``` { "resources": [ { "ResourceId": "mycluster", "ResourceType": "REDSHIFT_WAREHOUSE", "TablesToInclude": [ "database.schema.table1", "database.schema.table2" ], "TablesToExclude": [ "database.schema.table3", "database.schema.table4" ], "ColumnsToInclude": { "database.schema.table1": [ "col1", "col2" ], "database.schema.table2": [ "col1", "col2" ] }, "ColumnsToExclude": { "database.schema.table5": [ "col1", "col2" ], "database.schema.table6": [ "col1", "col2" ] }, "TableAnnotations": { "database.schema.table1": "table1 refers to Q3 sales", "database.schema.table2": "table2 refers to Q4 sales" }, "ColumnAnnotations": { "database.schema.table1": { "col1": "col1 refers to Q3 sale total", "col2": "col2 refers to sale location" }, "database.schema.table2": { "col1": "col2 refers to Q4 sale total", "col2": "col2 refers to sale location" } }, "CuratedQueries": [ { "Question": "what is the sales data for Q3", "Answer": "SELECT * FROM table1" }, { "Question": "what is the sales data for Q4", "Answer": "SELECT * FROM table2" } ], "CustomDocuments": [ "in manufacturing division total sales is price * revenue", "in research division total sales is price * revenue" ], "AdditionalTables": { "database.schema.table8": "create table database.schema.table8(col1 int)", "database.schema.table9": "create table database.schema.table9(col1 int)" }, "AppendToPrompt": "Apply these guardrails: Queries should never return the secretId field of a user." } ] } ``` # 教程：对 TICKIT 数据使用 Amazon Q 生成式 SQL 功能 要编写有效的提示来生成 SQL，您必须了解自己的数据库架构和数据。TICKIT 数据包含七个表：两个事实表和五个维度表。样本数据包含 2008 年举办的娱乐活动的观众售票记录。有关 TICKIT 数据的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[示例数据库](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。您可以通过各种方法将 TICKIT 数据加载到数据库中既可以使用 Amazon Redshift 控制台，也可以使用查询编辑器 v2。查询编辑器 v2 提供了将 TICKIT 数据加载到数据库 `sample_data_dev` 的方法。有关信息，请参阅[将数据加载到数据库](query-editor-v2-loading.md)。查询编辑器 v2 还提供了适用于 TICKIT 数据的示例提示。以下场景描述了与生成式 SQL 进行的对话，用以生成有关 TICKIT 样本数据的 SQL。在这个场景中，TICKIT 样本数据已在 Amazon Redshift 集群的 `dev` 数据库中创建。 **注意** 这个例子用于说明对话过程。虽然您使用了相同的提示，但生成式 SQL 的响应并不一致。 **使用 Amazon Q 生成式 SQL 的示例对话** 1. 在**编辑器**中，连接到包含 TICKIT 样本数据的集群或工作组。 1. 创建一个空笔记本，然后选择 ![\[Generative SQL\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-amazon-q.png) 生成式 SQL 图标以打开聊天面板。 1. 输入以下提示，生成 SQL 来验证 `VENUE` 表中的记录数： ``` How many venues are there? ``` ``` SELECT COUNT(*) AS num_venues FROM tickit.venue ``` 选择**添加到笔记本**，将两个单元格添加到打开的笔记本中。一个 Markdown 单元格中为“有多少个场馆？” 另一个单元格包含生成的 SQL。 在 SQL 单元格中，选择**运行**以接收结果： ``` count ------ 202 ``` 1. 要请求另一个版本的 SQL，请选择**重新生成 SQL**并会收到以下答案： ``` SELECT venuestate, COUNT(*) AS num_venues FROM tickit.venue GROUP BY venuestate ``` 选择**添加到笔记本**，再添加两个单元格到打开的笔记本中。一个 Markdown 单元格中为“有多少个场馆？” 另一个单元格包含生成的 SQL。 在 SQL 单元格中，选择**运行** 以接收结果，其中列出了各州的场馆数量： ``` venuestate num_venues ---------------------- MA 4 OH 8 MI 5 ... ``` 1. 生成式 SQL 助手可以对您的要求做出推测。尽管数据库中没有小组件，但您仍然可以询问。在这种情况下，它会给出消息，说明无法生成 SQL。 ``` How many widgets are there? ``` ``` I was not able to generate any SQL ``` 1. 随着对数据库的了解越来越多，您可以提出更具体的问题来生成 SQL。例如，您知道数据库中包含 2008 年几个月的销售数据。输入以下提示以生成 SQL，用于查找 2008 年 11 月的销量： ``` How many sales were there in November 2008? ``` ``` SELECT COUNT(*) AS num_sales FROM tickit.sales s JOIN tickit.date d ON s.dateid = d.dateid WHERE d.month = 'November' AND d.year = 2008 ``` 选择**添加到笔记本**，将两个单元格添加到打开的笔记本中。一个 Markdown 单元格中为“2008 年 11 月的销量是多少？” 另一个单元格包含生成的 SQL。 在 SQL 单元格中，选择**运行**以接收结果： ``` num_sales ----- 0 ``` 您发现这不是所期望的结果。 1. 您注意到谓词 `date.month='November'` 要求在 DATE 表中使用月份名称的缩写来表示月份。将谓词更改为 `d.month='NOV'`，然后重新运行 SQL。 ``` SELECT COUNT(*) FROM sales JOIN date ON sales.dateid = date.dateid WHERE date.month = 'NOV' AND date.year = 2008 ``` 在 SQL 单元格中，选择**运行**以获取新结果。 ``` count ----- 14261 ``` 1. 如果您提出的问题试图更改连接的数据库，则会返回一条警告消息以及所推荐的任何 SQL。输入以下提示以生成将数据插入表中的 SQL： ``` Insert 1 into the venue table. ``` ``` INSERT , UPDATE OR delete data FROM the database AS that could potentially change the data.Please provide a query that ONLY selects data ``` ``` I was not able to generate the correct SQL code. I generated SQL, but you'll have to edit it to work with your database. ``` 如果您选择**添加到笔记本**，将两个单元格添加到打开的笔记本中并运行 SQL，SQL 会失败。 ``` ERROR: syntax error at or near "," Position: 132 [ErrorId: 1-6546764a-011df2691778846219ce6ec2] ``` 此场景仅用于说明与 Amazon Q 生成式 SQL 交互的一些基本方法。您可以使用此生成式 AI 技术进行更多实验，以帮助您开始编写 SQL 来查询数据库。 # 将数据加载到数据库 您可以使用查询编辑器 v2 将数据加载到 Amazon Redshift 集群或工作组的数据库中。本节介绍如何加载示例数据、来自 S3 的数据以及来自本地文件设置和工作流程的数据。 ## 示例数据 查询编辑器 v2 附带可加载到示例数据库和相应 Schema 中的示例数据和笔记本。 要加载示例数据，请选择与要加载的示例数据相关联的 ![\[External\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/external.png) 图标。然后，查询编辑器 v2 会将数据加载到数据库 `sample_data_dev` 的架构中，并创建一个已保存笔记本的文件夹。 提供了以下示例数据集。 **tickit** Amazon Redshift 文档中的大多数示例使用称为 `tickit` 的示例数据。此数据包含七个表：两个事实表和五个维度。当您加载这些数据时，将使用示例数据更新模式 `tickit`。有关 `tickit` 数据的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[示例数据库](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 **tpch** 此数据用于决策支持基准。当您加载这些数据时，将使用示例数据更新模式 `tpch`。有关 `tpch` 数据类型的更多信息，请参阅 [TPC-H](http://www.tpc.org/tpch/)。 **tpcds** 此数据用于决策支持基准。当您加载这些数据时，将使用示例数据更新模式 `tpcds`。有关 `tpcds` 数据的更多信息，请参阅 [TPC-DS](http://www.tpc.org/tpcds/)。 # 从 Simple Storage Service（Amazon S3）加载数据 您可将 Amazon S3 数据加载到现有表或新表中。 **将数据加载到现有表中** 查询编辑器 v2 使用 COPY 命令从 Simple Storage Service（Amazon S3）加载数据。在查询编辑器 v2 加载数据向导中生成和使用的 COPY 命令支持从 Amazon S3 复制的 COPY 命令语法可用的许多参数。有关 COPY 命令及其用于从 Simple Storage Service（Amazon S3）加载数据选项的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Amazon Simple Storage Service 中的 COPY 命令](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 确认表已在要加载数据的数据库中创建。 1. 在继续之前，请在查询编辑器 v2 的树视图面板中确认您已连接到目标数据库。使用上下文菜单（右键单击）创建与将要加载数据的集群或工作组的连接。 选择 ![\[Load\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-upload.png)**Load data**（加载数据） 1. 对于**数据来源**，选择**从 S3 存储桶加载**。 1. 在 **S3 URI**中，选择 **Browse S3**（浏览 S3）以查找包含要加载数据的 Simple Storage Service（Amazon S3）桶。 1. 如果指定的 Amazon S3 桶与目标表不在同一个 AWS 区域中，则针对数据所在的 AWS 区域选择 **S3 file location**（S3 文件位置）。 1. 如果 Simple Storage Service（Amazon S3）文件实际上包含多个 Simple Storage Service（Amazon S3）桶 URI 清单，选择**This file is a manifest file**（此文件是清单文件）。 1. 为要上载的文件选择 **File format**（文件格式）。支持的数据格式有 CSV、JSON、DELIMITER、FIXEDWIDH、SHAPEFILE、AVRO、PARQUET 和 ORC。根据指定的文件格式，您可以选择相应的 **File options**（文件选项）。如果数据已加密，您还可以选择 **Data is encrypted**（数据已加密），并输入用于加密数据的 KMS 密钥 Amazon Resource Name（ARN）。 如果您选择 CSV 或 DELIMITER，则还可以选择**分隔符字符**，以及在指定的行编号实际上是列名而不是要加载的数据时是否**忽略标题行**。 1. 选择压缩方法来压缩文件。原定设置为无压缩。 1. （可选）**Advanced settings**（高级设置）支持各种 **Data conversion parameters**（数据转换参数）和 **Load operations**（加载操作）。根据文件的需要输入此信息。 有关数据转换和数据加载参数的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据转换参数](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[数据加载操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 选择**下一步**。 1. 选择**加载现有表**。 1. 确认或选择**目标表**的位置，包括在其中加载数据的**集群或工作组**、**数据库**、**架构**和**表**名称。 1. 选择具有从 Simple Storage Service（Amazon S3）加载数据所需的权限的 **IAM role**（IAM 角色）。 1. （可选）选择列名称，将其输入到 **Column mapping**（列映射）中，以按输入数据文件的顺序映射列。 1. 选择 **Load data**（加载数据）开启数据加载。 加载完成后，查询编辑器将显示用于加载数据的生成 COPY 命令。将显示 COPY 的 **Result**（结果）。如果成功，您现在可以使用 SQL 从加载的表中选择数据。当出现错误时，请查询系统视图 STL\$1LOAD\$1ERRORS 以获取更多详细信息。有关 COPY 命令错误的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 将数据加载到新表时，查询编辑器 v2 首先在数据库中创建表，然后作为同一个工作流中的单独操作加载数据。 **将数据加载到新表** 查询编辑器 v2 使用 COPY 命令从 Simple Storage Service（Amazon S3）加载数据。在查询编辑器 v2 加载数据向导中生成和使用的 COPY 命令支持从 Amazon S3 复制的 COPY 命令语法可用的许多参数。有关 COPY 命令及其用于从 Simple Storage Service（Amazon S3）加载数据选项的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Amazon Simple Storage Service 中的 COPY 命令](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 在继续之前，请在查询编辑器 v2 的树视图面板中确认您已连接到目标数据库。使用上下文菜单（右键单击）创建与将要加载数据的集群或工作组的连接。 选择 ![\[Load\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-upload.png)**Load data**（加载数据） 1. 对于**数据来源**，选择**从 S3 存储桶加载**。 1. 在 **S3 URI**中，选择 **Browse S3**（浏览 S3）以查找包含要加载数据的 Simple Storage Service（Amazon S3）桶。 1. 如果指定的 Amazon S3 桶与目标表不在同一个 AWS 区域中，则针对数据所在的 AWS 区域选择 **S3 file location**（S3 文件位置）。 1. 如果 Simple Storage Service（Amazon S3）文件实际上包含多个 Simple Storage Service（Amazon S3）桶 URI 清单，选择**This file is a manifest file**（此文件是清单文件）。 1. 为要上载的文件选择 **File format**（文件格式）。支持的数据格式有 CSV、JSON、DELIMITER、FIXEDWIDH、SHAPEFILE、AVRO、PARQUET 和 ORC。根据指定的文件格式，您可以选择相应的 **File options**（文件选项）。如果数据已加密，您还可以选择 **Data is encrypted**（数据已加密），并输入用于加密数据的 KMS 密钥 Amazon Resource Name（ARN）。 如果您选择 CSV 或 DELIMITER，则还可以选择**分隔符字符**，以及在指定的行编号实际上是列名而不是要加载的数据时是否**忽略标题行**。 1. 选择压缩方法来压缩文件。原定设置为无压缩。 1. （可选）**Advanced settings**（高级设置）支持各种 **Data conversion parameters**（数据转换参数）和 **Load operations**（加载操作）。根据文件的需要输入此信息。 有关数据转换和数据加载参数的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据转换参数](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[数据加载操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 选择**下一步**。 1. 选择**加载新表**。 表列根据输入数据推断得出。您可以通过添加列和表详细信息来修改表架构的定义。要恢复到查询编辑器 v2 推断的表架构，请选择**还原为默认值**。 1. 确认或选择**目标表**的位置，包括在其中加载数据的**集群或工作组**、**数据库**和**架构**。输入要创建的**表**的名称。 1. 选择具有从 Simple Storage Service（Amazon S3）加载数据所需的权限的 **IAM role**（IAM 角色）。 1. 选择**创建表**即可使用所示的定义创建表。 此时将显示表定义的复查摘要。系统会在数据库中创建表。以后要删除该表时，请运行 DROP TABLE SQL 命令。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [DROP TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_DROP_TABLE)。 1. 选择 **Load data**（加载数据）开启数据加载。 加载完成后，查询编辑器将显示用于加载数据的生成 COPY 命令。将显示 COPY 的 **Result**（结果）。如果成功，您现在可以使用 SQL 从加载的表中选择数据。当出现错误时，请查询系统视图 STL\$1LOAD\$1ERRORS 以获取更多详细信息。有关 COPY 命令错误的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 # 从本地文件设置和工作流加载数据 您可从本地文件将数据加载到现有表或新表中。 ## 管理员设置从本地文件加载数据 查询编辑器 v2 管理员必须在 **Account settings**（账户设置）窗口中指定常用 Amazon S3 桶。必须为账户用户配置适当的权限。 + 所需的 IAM 权限 – 从本地文件加载的用户必须拥有 `s3:ListBucket`、`s3:GetBucketLocation`、`s3:putObject`、`s3:getObject` 和 `s3:deleteObject` 权限。可以指定 *optional-prefix*，以将查询编辑器 v2 对此桶相关的使用限制为具有此前缀的对象。将同一 Amazon S3 桶用于查询编辑器 v2 以外的用途时，您可以使用此选项。有关桶和前缀的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[管理用户对特定文件夹的访问权限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-folders)。为确保不允许跨用户访问数据，我们建议查询编辑器 v2 管理员使用 Amazon S3 存储桶策略来限制基于 `aws:userid` 的对象访问权限。以下示例允许 Amazon S3 对 ** 拥有权限，并仅对前缀为 `aws:userid` 的 Amazon S3 对象进行读/写访问。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::" ] }, { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::[/]/${aws:userid}/*" ] } ] } ``` ------ + 数据分离 – 我们建议用户不要访问彼此的数据（即使是短暂的访问）。从本地文件加载将使用查询编辑器 v2 管理员设置的暂存 Amazon S3 桶。为暂存桶配置桶策略，以在用户之间提供数据分离。以下示例显示了在 ** 的用户之间分离数据的桶策略。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ {"Sid": "userIdPolicy", "Effect": "Deny", "Principal": "*", "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"], "NotResource": [ "arn:aws:s3:::[/]/${aws:userid}/*" ] } ] } ``` ------ ## 从本地文件加载数据 **将本地文件数据加载到现有表中** 您的查询编辑器 v2 管理员必须在**账户设置**窗口中指定公共 Amazon S3 存储桶。查询编辑器 v2 会自动将本地文件上传到账户使用的公共 Amazon S3 存储桶，然后使用 COPY 命令加载数据。在查询编辑器 v2 加载本地文件窗口中生成和运行的 COPY 命令支持从 Amazon S3 复制的 COPY 命令语法可用的许多参数。有关 COPY 命令及其用于从 Amazon S3 加载数据的选项的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Amazon S3 中的 COPY 命令](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 确认表已在要加载数据的数据库中创建。 1. 在查询编辑器 v2 的树视图面板中确认您已连接到目标数据库。使用上下文菜单（右键单击）创建与将要加载数据的集群或工作组的连接。 1. 选择 ![\[Load\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-upload.png)**Load data**（加载数据） 1. 对于 **Data source**（数据来源），选择 **Load from local file**（从本地文件中加载）。 1. 选择**浏览**以查找包含数据的文件来**加载文件**。默认情况下，会显示扩展名为 `.csv`、`.avro`、`.parquet` 和 `.orc` 的文件，但您可以选择其他文件类型。最大 文件大小为 100MB。 1. 为要上载的文件选择 **File format**（文件格式）。支持的数据格式有 CSV、JSON、DELIMITER、FIXEDWIDH、SHAPEFILE、AVRO、PARQUET 和 ORC。根据指定的文件格式，您可以选择相应的 **File options**（文件选项）。如果数据已加密，您还可以选择 **Data is encrypted**（数据已加密），并输入用于加密数据的 KMS 密钥 Amazon Resource Name（ARN）。 如果您选择 CSV 或 DELIMITER，则还可以选择**分隔符字符**，以及在指定的行编号实际上是列名而不是要加载的数据时是否**忽略标题行**。 1. （可选）**Advanced settings**（高级设置）支持各种 **Data conversion parameters**（数据转换参数）和 **Load operations**（加载操作）。根据文件的需要输入此信息。 有关数据转换和数据加载参数的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据转换参数](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[数据加载操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 选择**下一步**。 1. 选择**加载现有表**。 1. 确认或选择**目标表**的位置，包括在其中加载数据的**集群或工作组**、**数据库**、**架构**和**表**名称。 1. （可选）您可以选择列名称以输入到 **Column mapping**（列映射）中，以按输入数据文件的顺序映射列。 1. 选择 **Load data**（加载数据）开启数据加载。 加载完成后，无论加载成功与否，都会显示一条消息。如果成功，您现在可以使用 SQL 从加载的表中选择数据。当出现错误时，请查询系统视图 STL\$1LOAD\$1ERRORS 以获取更多详细信息。有关 COPY 命令错误的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 用于加载数据的 COPY 命令模板出现在您的 **Query history**（查询历史记录）中。此 COPY 命令模板显示了一些使用的参数，但它不能直接在编辑器选项卡中运行。有关查询历史记录的更多信息，请参阅[查看查询和选项卡历史记录](query-editor-v2-history.md)。 将数据加载到新表时，查询编辑器 v2 首先在数据库中创建表，然后作为同一个工作流中的单独操作加载数据。 **将本地文件数据加载到新表** 查询编辑器 v2 管理员必须在 **Account settings**（账户设置）窗口中指定常用 Amazon S3 桶。本地文件会自动上载到您的账户使用的一个公共 Amazon S3 桶，然后查询编辑器 v2 使用 COPY 命令加载数据。在查询编辑器 v2 加载本地文件窗口中生成和运行的 COPY 命令支持从 Amazon S3 复制的 COPY 命令语法可用的许多参数。有关 COPY 命令及其用于从 Amazon S3 加载数据的选项的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [Amazon S3 中的 COPY 命令](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 在查询编辑器 v2 的树视图面板中确认您已连接到目标数据库。使用上下文菜单（右键单击）创建与将要加载数据的集群或工作组的连接。 1. 选择 ![\[Load\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-upload.png)**Load data**（加载数据） 1. 对于 **Data source**（数据来源），选择 **Load from local file**（从本地文件中加载）。 1. 选择**浏览**以查找包含数据的文件来**加载文件**。默认情况下，会显示扩展名为 `.csv`、`.avro`、`.parquet` 和 `.orc` 的文件，但您可以选择其他文件类型。最大 文件大小为 100MB。 1. 为要上载的文件选择 **File format**（文件格式）。支持的数据格式有 CSV、JSON、DELIMITER、FIXEDWIDH、SHAPEFILE、AVRO、PARQUET 和 ORC。根据指定的文件格式，您可以选择相应的 **File options**（文件选项）。如果数据已加密，您还可以选择 **Data is encrypted**（数据已加密），并输入用于加密数据的 KMS 密钥 Amazon Resource Name（ARN）。 如果您选择 CSV 或 DELIMITER，则还可以选择**分隔符字符**，以及在指定的行编号实际上是列名而不是要加载的数据时是否**忽略标题行**。 1. （可选）**Advanced settings**（高级设置）支持各种 **Data conversion parameters**（数据转换参数）和 **Load operations**（加载操作）。根据文件的需要输入此信息。 有关数据转换和数据加载参数的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据转换参数](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[数据加载操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 选择**下一步**。 1. 选择**加载新表**。 1. 确认或选择**目标表**的位置，包括在其中加载数据的**集群或工作组**、**数据库**和**架构**。输入要创建的**表**的名称。 1. 选择**创建表**即可使用所示的定义创建表。 此时将显示表定义的复查摘要。系统会在数据库中创建表。以后要删除该表时，请运行 DROP TABLE SQL 命令。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [DROP TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_DROP_TABLE)。 1. 选择 **Load data**（加载数据）开启数据加载。 加载完成后，将会显示一条消息，指示加载是否成功。如果成功，您现在可以使用 SQL 从加载的表中选择数据。当出现错误时，请查询系统视图 STL\$1LOAD\$1ERRORS 以获取更多详细信息。有关 COPY 命令错误的信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 用于加载数据的 COPY 命令模板出现在您的 **Query history**（查询历史记录）中。此 COPY 命令模板显示了一些使用的参数，但它不能直接在编辑器选项卡中运行。有关查询历史记录的更多信息，请参阅[查看查询和选项卡历史记录](query-editor-v2-history.md)。 # 使用 Amazon Redshift 编写查询 您可以在编辑器中输入查询，也可以从**查询**中列出并选择**运行**以选择已保存的查询。 默认情况下，设置**限制 100**，将结果限制为 100 行。您可以禁用此选项来返回较大的结果集。禁用此选项时，如要避免非常大型结果集，则可以在 SQL 语句中包含 LIMIT 选项。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [ORDER BY 子句](https://docs.aws.amazon.com/redshift/latest/dg/r_ORDER_BY_clause.html)。 要在结果区域中显示查询计划，请打开**解释**。对结果开启**解释图**，也可显示解释计划的图形表示。 选择**保存**，将查询保存到**查询**文件夹。 查询成功，将显示成功消息。如果查询返回信息，则结果将显示在**结果**部分。如果结果数超过显示区域，则数字将显示在结果区域的顶部。您可以选择数字来显示连续的结果页面。 您可以筛选和排序每一列的**结果**。如要在结果列标题中输入筛选条件，请将鼠标悬停在该列上便可查看筛选条件菜单（![\[Filter menu\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/menu.png)），您可以在此处输入筛选列的条件。 如果查询包含错误，则查询编辑器 v2 将在结果区域中显示错误消息。此消息提供有关如何更正查询的信息。 您可以使用结果区域中的上下文（右键单击）菜单导出或复制查询结果，如下所示： + 选择**复制到**，然后选择 **JSON** 或 **CSV**，以便将选定的行下载到文件中。 + 选择**复制行**以便将选定的行复制到剪贴板。 + 如选择**复制带标题的行**，以便将带有列标题的选定行复制到剪贴板。 还可以在结果区域中选择**导出**，然后选择 **JSON** 或 **CSV**，以便将整组行结果下载到文件中。结果集中的行数可能受到查询中**限制**选项或 SQL `limit` 子句限制。下载结果集的最大大小为 5 MB。 也可以使用快捷方式（Windows 上的 Ctrl\$1C 或 macOS 上的 Cmd\$1C）将数据从当前结果页面复制到剪贴板。如果未选择任何行，则具有焦点的单元格将复制到剪贴板。如果选择了行，则选定的行将复制到剪贴板。 要添加新的查询选项卡，请选择 ![\[New query tab\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png) 图标，然后选择**编辑器**，此编辑器将显示在查询选项卡所在行中。查询选项卡可以使用，也可以不使用 `Isolated session`。对于隔离会话，SQL 命令的结果（例如，在一个编辑器选项卡中创建临时表）在另一个编辑器选项卡中不可见。在查询编辑器 v2 中打开编辑器选项卡时，默认为隔离会话。 **运行查询** 1. 在查询区域中，执行以下任一操作： + 输入查询。 + 粘贴您复制的查询。 + 选择**查询**文件夹中，打开上下文菜单（右键单击）中的保存查询，然后选择**打开查询**。 1. 确认您为计划运行的 SQL 选择了正确的**集群**或**工作组**以及**数据库**值。 最初，您可以在树视图中选择您的**集群**或**工作组**。还可以在树视图中选择您的**数据库**。 您可以使用位于每个编辑器选项卡的**隔离会话**标题附近的下拉控件，更改每个编辑器选项卡中的**集群**或**工作组**以及**数据库**。 对于每个编辑器选项卡，您可以选择是否以**隔离会话**运行 SQL。隔离会话与数据库有自己的连接。使用它来运行与其他查询编辑器会话隔离的 SQL。有关 连接的更多信息，请参阅 [打开查询编辑器 v2](query-editor-v2-open.md)。 1. 选择**运行**。 将打开**结果**区域并显示查询结果。 **显示查询的解释计划** 1. 选择查询。 1. 启用**解释**。 默认情况下，**解释图**也将启动。 1. 选择**运行**。 运行查询，并在查询的**结果**区域中显示解释计划。 查询编辑器 v2 支持以下功能。 + 您可以在一个查询选项卡中使用多个 SQL 语句创作查询。这些查询将连续运行，并为每个查询打开多个结果选项卡。 + 您可以使用会话变量和临时表创作查询。 + 您可以使用由 `${parameter}` 指定的可替换参数创作查询。您可以使用多个可替换参数创作 SQL 查询，并在 SQL 语句的多个位置使用相同的参数。 当查询运行时，会显示一个用来输入参数值的窗口。每次运行查询时，都会显示窗口以输入参数值。 有关示例，请参阅[示例：销售额大于特定参数](#query-editor-v2-example-sales-qtysold-greater-than-parameter)。 + 自动对查询进行版本控制。您可以选择要运行的查询的早期版本。 + 在继续工作流程之前，您无需等待查询完成。即使关闭查询编辑器，查询仍会继续运行。 + 创作查询时，支持自动完成架构、表和列名称。 SQL 编辑器支持以下功能： + SQL 中使用的左方括号和右方括号具有匹配的颜色。编辑器中显示垂直线以帮助您匹配方括号。 + 您可以折叠和展开 SQL 的各个部分。 + 您可以在 SQL 中搜索和替换文本。 + 您可以使用快捷键执行多个常见编辑任务。 + SQL 错误会在编辑器中突出显示，以便于找到问题领域。 有关编辑器功能的演示，请观看以下视频。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/9JAq0yDs0YE/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/9JAq0yDs0YE) ## 查询示例 在下方您可以找到可以运行的各种查询类型的描述。 许多此类查询中使用的数据来自 `tickit` 示例架构。有关加载示例 `tickit` 数据的更多信息，请参阅[将数据加载到数据库](query-editor-v2-loading.md)。有关 `tickit` 示例数据的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[示例数据库](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 运行这些示例查询时，请确认在编辑器中选择了正确的数据库，例如 `sample_data_dev`。 **Topics** + [示例：设置会话变量](#query-editor-v2-example-set-session-variable) + [示例：按总销售额排列的顶事件](#query-editor-v2-example-top-event-sales) + [示例：销售额大于特定参数](#query-editor-v2-example-sales-qtysold-greater-than-parameter) + [示例：创建一个临时表](#query-editor-v2-example-create-temporary-table) + [示例：从临时表中选择](#query-editor-v2-example-select-from-temporary-table) ### 示例：设置会话变量 以下命令将 `search_path` 服务器配置参数设置为会话的*公有*参数。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [SET](https://docs.aws.amazon.com/redshift/latest/dg/r_SET.html) 和 [search\$1path](https://docs.aws.amazon.com/redshift/latest/dg/r_search_path.html)。 ``` set search_path to public; ``` ### 示例：按总销售额排列的顶事件 以下查询查找销售额最多的事件。 ``` select eventname, count(salesid) totalorders, sum(pricepaid) totalsales from sales, event where sales.eventid=event.eventid group by eventname order by 3; ``` 以下是结果的部分清单。 ``` eventname totalorders totalsales White Christmas 20 9352 Joshua Radin 38 23469 Beach Boys 58 30383 Linda Ronstadt 56 35043 Rascal Flatts 76 38214 Billy Idol 67 40101 Stephenie Meyer 72 41509 Indigo Girls 57 45399 ... ``` ### 示例：销售额大于特定参数 以下查询查找销售数量大于 `${numberoforders}` 指定参数的销售额。当参数值为 `7` 时，结果是 60 行。运行查询时，查询编辑器 v2 会显示**运行查询表**窗口来收集 SQL 语句中参数值。 ``` select salesid, qtysold from sales where qtysold > ${numberoforders} order by 2; ``` 以下是结果的部分清单。 ``` salesid qtysold 20005 8 21279 8 130232 8 42737 8 74681 8 67103 8 105533 8 91620 8 121552 8 ... ``` ### 示例：创建一个临时表 通过*销售*和*事件*表，以下语句创建临时表 *eventsalestemp*。 ``` create temporary table eventsalestemp as select eventname, count(salesid) totalorders, sum(pricepaid) totalsales from sales, event where sales.eventid=event.eventid group by eventname; ``` ### 示例：从临时表中选择 按总订单排序，以下语句从临时表 *eventsalestemp* 中选择事件、订单总数和总销售额。 ``` select eventname, totalorders, totalsales from eventsalestemp order by 2; ``` 以下是部分结果列表。 ``` eventname totalorders totalsales White Christmas 20 9352 Joshua Radin 38 23469 Martina McBride 50 52932 Linda Ronstadt 56 35043 Indigo Girls 57 45399 Beach Boys 58 30383 ... ``` # Amazon Redshift 中的笔记本 您可以使用笔记本在单个文档中组织、注释及共享多个 SQL 查询。您可以将多个 SQL 查询和 Markdown 单元格添加到笔记本中。笔记本提供了一种方法：通过使用多个查询和 Markdown 单元格，将与数据分析相关的查询和解释分组到单个文档中。您可以使用 Markdown 语法添加文本并设置外观格式，以便为数据分析任务提供上下文和其它信息。您可以与团队成员共享您的笔记本。 要使用笔记本，您必须为您的 IAM 主体（IAM 用户或 IAM 角色）添加笔记本的权限。作为最佳实践，我们建议将权限策略附加到 IAM 角色，然后根据需要将其分配给用户和组。有关更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。您可以向其中一个查询编辑器 v2 托管策略添加权限。有关更多信息，请参阅 [访问查询编辑器 v2](query-editor-v2-getting-started.md#query-editor-v2-configure)。 可以按顺序运行笔记本的所有单元格。笔记本的 SQL 查询单元格具有大多数与查询编辑器选项卡相同的功能。有关更多信息，请参阅 [使用 Amazon Redshift 编写查询](query-editor-v2-query-run.md)。以下是查询编辑器选项卡和笔记本中的 SQL 单元格之间的差异。 + 在笔记本中，没有用于对 SQL 语句运行 `Explain` 的控件。 + 在笔记本中，每个 SQL 单元格只能创建一个图表。 您可以将笔记本导出和导入到使用查询编辑器 v2 创建的文件中。文件扩展名为 `.ipynb`，文件大小最大可为 5 MB。SQL 和 Markdown 单元格存储在文件中。集群或工作组和数据库不会存储在导出的笔记本中。当您打开导入的笔记本时，您可以选择用于运行该笔记本的集群或工作组和数据库。运行 SQL 单元格后，可以在结果选项卡中选择是否将当前结果页显示为图表。查询的结果集不会存储在笔记本中。 # 创建笔记本 可以创建笔记本来在单个文档中整理、注释及共享多个 SQL 查询。 **创建笔记本** 1. 在导航器菜单中，选择编辑器图标（![\[Horizontal lines representing redacted or censored text.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-align-left.png)）。 1. 选择加号图标（![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png)），然后选择**笔记本**。 默认情况下，笔记本中会显示 SQL 查询单元格。 1. 在 SQL 查询单元格中，执行以下任一操作： + 输入查询。 + 粘贴您复制的查询。 1. （可选）选择加号图标（![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png)），然后选择 **Markdown** 以添加 Markdown 单元格，在其中可以使用标准 Markdown 语法提供描述性或解释性文本。 1. （可选）选择加号图标（![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png)），然后选择 **SQL** 以插入 SQL 单元格。 您可以单击铅笔图标（![\[Pencil icon representing an editing or writing function.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-edit.png)）来重命名笔记本。 在菜单图标（![\[Three dots arranged horizontally, representing an ellipsis or "more" menu icon.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-more.png)）中，您还可以对笔记本执行以下操作： + ![\[Share\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-share.png) **与我的团队分享** – 按照标签的定义，与您的团队分享笔记本。如要与团队分享笔记本，请确保您将主体标签 `sqlworkbench-team` 设置为与账户中其它团队成员相同的值。例如，管理员可以为会计部门的每个人将该值设置为 `accounting-team`。有关示例，请参阅[使用查询编辑器 v2 所需的权限](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 + ![\[Export\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-export.png) **导出** – 将笔记本导出到扩展名为 `.ipynb` 的本地文件。 + ![\[Import query\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-import.png) **导入查询** – 将查询从本地文件导入到笔记本单元格中。您可以导入扩展名为 `.sql` 和 `.txt` 的文件。 + ![\[Save\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-floppy-disk.png) **保存版本** – 创建笔记本的一个版本。要查看笔记本的版本，请导航到已保存的笔记本并打开**版本历史记录**。 + ![\[Duplicate\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-duplicate.png) **复制** – 创建笔记本的副本并在新的笔记本选项卡中将其打开。 + ![\[Shortcuts\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-key-command.png) **快捷方式** – 显示编写笔记本时可用的快捷方式。 # 导入到笔记本 您可以将整个笔记本或单个 SQL 单元格导入到查询编辑器 v2 笔记本中。 要将整个笔记本从本地文件导入到**我的笔记本**，请选择 ![\[Import\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-import.png) **导入**，然后选择**导入笔记本**。导航到包含您的笔记本的 `.ipynb` 文件。笔记本会导入到当前打开的笔记本文件夹。然后您可以在笔记本编辑器中打开笔记本。 要将查询从本地文件导入到笔记本的 SQL 单元格，请选择 ![\[Import\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-import.png) **导入**，然后选择**导入查询**。在**导入查询**窗口中，按照屏幕上的说明，选择可作为查询导入到新笔记本或现有笔记本中的文件和文件夹。这些文件的扩展名必须为 `.sql` 或 `.txt`。每个查询最多可以有 10000 个字符。在您添加到现有笔记本时，可以从**保存的笔记本**列表中的所有笔记本中选择要使用的笔记本。导入的查询将作为 SQL 单元格添加到笔记本的末尾。选择新笔记本时，您需要提供笔记本的名称，该笔记本将在当前打开的已保存笔记本的文件夹中创建。 **注意** 在 macOS 上使用 TextEdit 应用程序创建 `.sql` 文件时，您可能会遇到向文件添加额外的隐藏扩展名的问题。例如，在 TextEdit 中创建的名为 `Test.sql` 的文件最终可能会另存为 `Test.sql.rtf`。查询编辑器 v2 不支持扩展名为 `.rtf` 的文件。但是，如果您使用 TextEdit 创建 `.sql` 文件并将其另存为纯文本文件，则该文件会有一个额外的隐藏扩展名 `.txt`。例如，名为 `Text.sql` 的文件可能会另存为 `Text.sql.txt`。与 `.rtf` 扩展名不同，查询编辑器 v2 确实支持扩展名为 `.txt` 的文件，因此在将查询导入到笔记本时支持 `Text.sql.txt`。 要了解笔记本的演示，请观看以下视频。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/GNahyu7j98M/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/GNahyu7j98M) # 查询 AWS Glue Data Catalog 可以使用查询编辑器 v2 查询在 AWS Glue Data Catalog 中编目的数据，方法是使用特定 SQL 命令并授予本节中概述的权限。默认情况下，AWS Glue Data Catalog 列为名为 `awsdatacatalog` 的查询编辑器 v2 数据库。查询 AWS Glue Data Catalog 并非在所有 Amazon Redshift AWS 区域中都可用。使用 SHOW 命令确定此功能是否可用。有关 AWS Glue 的更多信息，请参阅《AWS Glue 开发人员指南》中的[什么是 AWS Glue？](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html)。 **注意** 查询 AWS Glue Data Catalog 仅在 Amazon Redshift RA3 节点类型集群和 Amazon Redshift Serverless 中受到支持。 您可以使用以下 SQL 命令配置您的数据仓库并查看编目的 AWS Glue 数据库对象： + SHOW – 显示是否为当前连接的数据仓库安装了 `awsdatacatalog`。例如，要显示 `data_catalog_auto_mount` 参数值，请运行： ``` SHOW data_catalog_auto_mount; ``` 有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [SHOW](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW.html)。 + ALTER SYSTEM – 更改 `data_catalog_auto_mount` 的系统级配置。例如，要将 `data_catalog_auto_mount` 参数值更改为 `on`，请运行： ``` ALTER SYSTEM SET data_catalog_auto_mount = on; ``` 当重新引导预置集群或自动暂停并恢复无服务器工作组时，更改将生效。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [ALTER SYSTEM](https://docs.aws.amazon.com/redshift/latest/dg/r_ALTER_SYSTEM.html)。 + SHOW SCHEMAS – 显示架构列表。数据库中名为 `awsdatacatalog` 的架构代表 AWS Glue Data Catalog 中编目的 AWS Glue 数据库。例如，要显示这些架构，请运行： ``` SHOW SCHEMAS FROM DATABASE awsdatacatalog; ``` 有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [SHOW SCHEMAS](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW_SCHEMAS.html)。 + SHOW TABLES – 显示架构中表的列表。例如，要显示名为 `awsdatacatalog` 的 AWS Glue Data Catalog 数据库中的表（这些表位于架构 `myglue` 中），请运行： ``` SHOW TABLES FROM SCHEMA awsdatacatalog.myschema; ``` 有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [SHOW TABLES](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW_TABLES.html)。 + SHOW COLUMNS – 显示表中列的列表。例如，要显示名为 `awsdatacatalog` 的 AWS Glue Data Catalog 数据库中的列（这些列位于架构 `myglue` 和表 `mytable` 中），请运行： ``` SHOW COLUMNS FROM TABLE awsdatacatalog.myglue.mytable; ``` 有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [SHOW COLUMNS](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW_COLUMNS.html)。 **向 IAM 用户或角色授予查询 AWS Glue Data Catalog 的权限** 1. 在树视图窗格中，使用**数据库用户名和密码**身份验证方法，连接到预置集群或无服务器工作组中的初始数据库。例如，使用您在创建集群或工作组时使用的管理员用户和密码连接到 `dev` 数据库。 1. 在编辑器选项卡中，运行以下 SQL 语句以授予 IAM 用户对 AWS Glue Data Catalog 的访问权限。 ``` GRANT USAGE ON DATABASE awsdatacatalog to "IAM:myIAMUser" ``` 其中，*IAM:myIAMUser* 是您想要向其授予对 AWS Glue Data Catalog 的使用权限的 IAM 用户。或者，您可以向 IAM 角色的 *IAMR:myIAMRole* 授予使用权限。 1. 在树视图窗格中，编辑或删除与您之前创建的集群或工作组的连接。通过以下方式之一连接到您的集群或工作组： + 要从集群访问 `awsdatacatalog` 数据库，您必须使用身份验证方法**使用您的 IAM 身份的临时凭证**。有关此身份验证方法的更多信息，请参阅[连接到 Amazon Redshift 数据库](query-editor-v2-connecting.md)。您的查询编辑器 v2 管理员可能需要配置账户的**账户设置**，才能在连接窗口中显示此身份验证方法。 + 要从工作组访问 `awsdatacatalog` 数据库，必须使用身份验证方法**联合用户**。有关此身份验证方法的更多信息，请参阅[连接到 Amazon Redshift 数据库](query-editor-v2-connecting.md)。 1. 通过授予的权限，您可以使用 IAM 身份对您的 AWS Glue Data Catalog 运行 SQL。 连接后，您可以使用查询编辑器 v2 查询在 AWS Glue Data Catalog 中编目的数据。在查询编辑器 v2 树视图窗格上，选择集群或工作组和 `awsdatacatalog` 数据库。在编辑器或笔记本窗格中，确认选择了正确的集群或工作组。选择的数据库应该是初始 Amazon Redshift 数据库，例如 `dev`。有关编写查询的信息，请参阅[使用 Amazon Redshift 编写查询](query-editor-v2-query-run.md)和[Amazon Redshift 中的笔记本笔记本](query-editor-v2-notebooks.md)。预留名为 `awsdatacatalog` 的数据库，用于引用您账户中的外部数据目录数据库。对 `awsdatacatalog` 数据库的查询只能是只读的。使用由三部分组成的表示法来引用 SELECT 语句中的表。其中第一部分是数据库名称，第二部分是 AWS Glue 数据库名称，第三部分是 AWS Glue 表名称。 ``` SELECT * FROM awsdatacatalog..; ``` 您可以执行各种场景来读取 AWS Glue Data Catalog 数据并填充 Amazon Redshift 表。 以下示例 SQL 联接了在 AWS Glue 中定义的两个表。 ``` SELECT pn.emp_id, alias, role, project_name FROM "awsdatacatalog"."empl_db"."project_name_table" pn, "awsdatacatalog"."empl_db"."project_alias_table" pa WHERE pn.emp_id = pa.emp_id; ``` 以下示例 SQL 创建了一个 Amazon Redshift 表，并使用来自两个 AWS Glue 表联接的数据填充该表。 ``` CREATE TABLE dev.public.glue AS SELECT pn.emp_id, alias, role, project_name FROM "awsdatacatalog"."empl_db"."project_name_table" pn, "awsdatacatalog"."empl_db"."project_alias_table" pa WHERE pn.emp_id = pa.emp_id; ``` ## 查询 Amazon S3 表（预览版） 可以使用查询编辑器 V2 查询挂载到 AWS Glue Data Catalog 的 Amazon S3 表目录中保存的数据。Amazon S3 表目录在创建时挂载到 AWS Glue Data Catalog，并自动以外部数据库的形式出现在相同 AWS 区域中同一个账户下的所有预置集群和无服务器工作组上。有关使用 Amazon Redshift 访问 Amazon S3 表的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的 [Accessing Amazon S3 tables with Amazon Redshift](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-integrating-redshift.html)。 # 查询数据湖 可以按照本教程中的任务集查询 Amazon S3 数据湖中的数据。首先，您可以创建一个外部架构来引用在 [AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/components-overview.html#data-catalog-intro) 中的外部数据库。然后，您可以在 Simple Storage Service（Amazon S3）数据湖中查询数据。 ## 演示：查询数据湖 要了解如何查询数据湖，请观看以下视频。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/-pyy0qNmEKo/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/-pyy0qNmEKo) ## 先决条件 在查询编辑器 v2 中使用数据湖之前，请确认您在 Amazon Redshift 环境中进行了以下设置： + 使用 AWS Glue 爬取您的 Amazon S3 数据并为 AWS Lake Formation 启用 Data Catalog。 + 使用为 AWS Lake Formation 启用的 AWS Glue Data Catalog，为 Amazon Redshift 创建 IAM 角色。有关此过程的详细信息，请参阅[使用为 AWS Lake Formation 启用的 AWS Glue Data Catalog 为 Amazon Redshift 创建 IAM 角色](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum-create-role.html#spectrum-get-stared-create-role-lake-formation)。有关使用 Redshift Spectrum 和 Lake Formation 的详细信息，请参阅[将 Redshift Spectrum 与 AWS Lake Formation 结合使用](https://docs.aws.amazon.com/redshift/latest/dg/spectrum-lake-formation.html)。 + 授予对表的 SELECT 权限，以便在 Lake Formation 数据库中进行查询。有关此过程的详细信息，请参阅[授予对表的 SELECT 权限以在 Lake Formation 数据库中进行查询](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum-create-role.html#spectrum-get-started-grant-lake-formation-table)。 您可以在 Lake Formation 控制台（https://console.aws.amazon.com/lakeformation/）中的**权限**部分的**数据湖权限**页面，验证该 IAM 角色、AWS Glue 数据库和表具有正确的权限。 + 确认连接的用户有权在 Amazon Redshift 数据库中创建架构以及访问数据湖中的数据。在查询编辑器 v2 中连接到数据库时，您可以选择包含凭证的身份验证方法（可以是数据库用户或 IAM 用户）。连接的用户必须具有合适的权限和数据库权限，例如 `superuser`。创建集群或工作组的 Amazon Redshift `admin` 用户拥有 `superuser` 权限，可以创建架构和管理 Redshift 数据库。有关使用查询编辑器 v2 连接到数据库的更多信息，请参阅 [连接到 Amazon Redshift 数据库](query-editor-v2-connecting.md)。 ## 创建外部架构 要查询 Amazon S3 数据湖中的数据，请先创建外部架构。外部架构引用了 [AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/components-overview.html#data-catalog-intro) 中的外部数据库。 1. 在查询编辑器 v2 的**编辑器**视图中，选择 ![\[Create\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png) **创建**，然后选择**架构**。 1. 输入**架构名称**。 1. 对于**架构类型**，选择**外部**。 1. 在 **Data Catalog** 详细信息下，**区域**默认为 Redshift 数据库所在的 AWS 区域。 1. 选择外部架构将映射的 **AWS Glue 数据库**，该数据库还应包含对 AWS Glue 表的引用。 1. 为 Amazon Redshift 选择相应的 **IAM 角色**，该角色应具有从 Amazon S3 查询数据所需的权限。 1. （可选）选择具有 Data Catalog 权限的 **IAM 角色**。 1. 选择**创建架构**。 该架构将显示在树视图面板中您的数据库下方。 创建架构时，如果您收到数据库权限被拒绝错误，请检查连接的用户是否具有创建架构的数据库权限。 ## 在 Simple Storage Service（Amazon S3）数据湖中查询数据 您可以使用在前一个过程中创建的架构。 1. 在树视图面板中，选择该架构。 1. 请选择一个表来查看表定义。此时系统将显示表列和数据类型。 1. 要查询表，请选择该表并使用上下文菜单（右键单击），选择**选择表**以生成查询。 1. 在**编辑器**中运行查询。 以下示例 SQL 由查询编辑器 v2 生成，用于查询名为 `flightscsv` 的 AWS Glue 表中的所有行。为简化起见，只显示了输出中的部分列和行。 ``` SELECT * FROM "dev"."mydatalake_schema"."flightscsv"; year quarter month dom day_of_week fl_date unique_carrier airline_id carrier tail_num fl_num 2016 4 10 19 3 10/19/16 OO 20304 OO N753SK 3086 2016 4 10 19 3 10/19/16 OO 20304 OO N753SK 3086 2016 4 10 19 3 10/19/16 OO 20304 OO N778SK 3087 2016 4 10 19 3 10/19/16 OO 20304 OO N778SK 3087 ... ``` # 数据共享 您可以创建数据共享，以便其他集群上的用户可以查询数据。包含您要共享的数据的集群称为*创建者*集群。您可以在创建者集群上为要共享的数据库对象创建数据共享。您可以共享 Schema、表、视图和 SQL 用户定义的函数 (UDF)。您要与其共享数据的集群称为*使用者*集群。在使用者集群上，您可以利用数据共享创建数据库。然后，使用者集群上的用户可以查询数据。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据共享入门](https://docs.aws.amazon.com/redshift/latest/dg/getting-started-datasharing.html)。 # 创建数据共享 您可以在要用作创建者集群的集群上创建数据共享。要详细了解数据共享的注意事项，请参阅中的《Amazon Redshift 数据库开发人员指南》**中的 [Amazon Redshift 中的数据共享注意事项](https://docs.aws.amazon.com/redshift/latest/dg/datashare-considerations.html)。 1. 选择要使用的创建者集群上的数据库。 1. 创建数据共享。例如： ``` create datashare mysource; ``` 1. 设置数据共享的权限。例如： ``` grant alter, share on datashare mysource to admin; ``` 1. 设置要共享的数据库对象的权限。例如： ``` alter datashare mysource add schema public; ``` ``` alter datashare mysource add table public.event; ``` 1. 设置使用者集群命名空间的权限以访问数据共享。例如： ``` grant usage on datashare mysource to namespace '2b12345-1234-5678-9012-bb1234567890'; ``` # 显示数据共享 您可以显示您在创建者集群上创建的数据共享。 1. 选择创建者集群。 1. 显示数据共享。例如： ``` show datashares; ``` ``` share_name share_owner source_database consumer_database share_type createdate is_publicaccessible share_acl producer_account producer_namespace test_datashare 100 db_producer NULL OUTBOUND 2/15/2022 FALSE admin 123456789012 p1234567-8765-4321-p10987654321 ``` # 创建使用者数据库 在使用者集群上，您可以利用数据共享创建数据库。这些步骤描述了如何在同一个账户中的两个集群之间共享数据。有关跨 AWS 账户共享数据的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[跨 AWS 账户共享数据](https://docs.aws.amazon.com/redshift/latest/dg/across-account.html)。 您可以使用 SQL 命令或查询编辑器 v2 树状视图面板来创建数据库。 **使用 SQL** 1. 利用数据共享为您的账户和创建者集群的命名空间创建一个数据库。例如： ``` create database share_db from datashare mysource of account '123456789012' namespace 'p1234567-8765-4321-p10987654321'; ``` 1. 设置权限，以便用户可以访问数据库和 Schema。例如： ``` grant usage on database share_db to usernames; ``` ``` grant usage on schema public to usernames; ``` **使用查询编辑器 v2 树状视图面板** 1. 选择![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-add.png)**创建**，然后选择**数据库**。 1. 输入**数据库名称**。 1. （可选）选择**用户和组**，然后选择**数据库用户**。 1. 选择**使用数据共享创建**。 1. 选择数据共享。 1. 选择**创建数据库**。 新的 ![\[datashare\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-datashare.png)**数据共享**数据库将在查询编辑器 v2 树状视图面板中显示。 1. 设置权限，以便用户可以访问数据库和 Schema。例如： ``` grant usage on database share_db to usernames; ``` ``` grant usage on schema public to usernames; ``` # 查询数据共享对象 在使用者集群上，您可以使用以三部分表示法表示的完全限定对象名来查询数据共享对象：数据库、架构和对象的名称。 1. 在查询编辑器 v2 树状视图面板中，选择该 Schema。 1. 请选择一个表来查看表定义。 此时系统将显示表列和数据类型。 1. 要查询表，请选择表并使用上下文菜单（右键单击）选择**选择表**。 1. 使用 SELECT 命令查询表。例如： ``` select top 10 * from test_db.public.event; ``` # 使用查询编辑器 v2 的计划查询 使用 Amazon Redshift 查询编辑器 v2，您可以自动执行 SQL 查询，使其按计划运行。计划查询是按指定时间或间隔自动运行的 SQL 语句，可让您高效管理重复性数据操作和分析任务。如果您想在 Amazon Redshift 环境中简化批处理、生成定期报告或维护数据管道，则可能需要计划查询。 计划查询有助于自动执行提取、转换和加载（ETL）工作流，用最新见解刷新控制面板，以及操作各种数据管理例程。以下页面详细介绍了创建、配置和管理计划查询以优化 Amazon Redshift 工作负载的过程。 # 使用查询编辑器 v2 创建查询计划 您可以使用 Amazon Redshift 查询编辑器 v2 创建运行 SQL 语句的计划。您创建一个计划，以便按照与您的业务需求相匹配的时间间隔运行 SQL 语句。当到了运行计划查询的时间时，查询由 Amazon EventBridge 启动并使用 Amazon Redshift Data API。 **创建计划以运行 SQL 语句** 1. 在**编辑器** ![\[Editor\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-align-left.png) 视图中，选择 ![\[Schedule\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-calendar.png) **计划**以创建运行 SQL 语句的计划。 1. 在定义计划时，您需要提供以下信息。 + 代入运行查询所需权限的 IAM 角色。此 IAM 角色还附加到您的集群或工作组。 + AWS Secrets Manager 或用于授权访问您的集群或工作组的临时凭证的身份验证值。数据 API 支持这些身份验证方法。有关更多信息，请参阅 [对计划查询进行身份验证](query-editor-v2-schedule-query-authentication.md)。 + 您的数据库所在的集群或工作组。 + 包含要查询的数据的数据库名称。 + 计划查询的名称及其描述。查询编辑器 v2 将在您提供的计划查询名称前加上“QS2-”前缀。查询编辑器 v1 将在其计划查询名称前加上“QS-”前缀。 + 要按计划运行的 SQL 语句。 + 计划频率和重复选项，或定义计划的 cron 格式的值。有关更多信息，请参阅《Amazon CloudWatch Events User Guide》**中的 [Cron Expressions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#CronExpressions)。 + （可选）您可以启用标准 Amazon SNS 通知来监控计划查询。您可能需要确认您向 Amazon SNS 通知提供的电子邮件地址。在您收到的电子邮件中查找用于确认接收 Amazon SNS 通知的电子邮件地址的链接。有关更多信息，请参阅《Amazon Simple Notification Service 开发人员指南》**中的[电子邮件通知](https://docs.aws.amazon.com/sns/latest/dg/sns-email-notifications.html)。如果您的查询正在运行，但您没有看到 SNS 主题中发布的消息，请参阅《Amazon EventBridge 用户指南》**中的[我的规则正在运行，但我没有看到任何消息发布到我的 Amazon SNS 主题](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-troubleshooting.html#eb-no-messages-published-sns)。 1. 选择**计划查询**以保存和激活计划，并将计划添加到**计划查询**视图中的查询列表。 **计划查询** ![\[Scheduled queries\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/qev2-calendar.png) 视图列出了您的集群和工作组的所有计划查询。使用此视图，您可以显示计划查询的详细信息、激活或停用计划、编辑计划以及删除计划查询。查看查询详细信息时，还可以查看使用计划运行查询的历史记录。 **注意** 计划查询的运行仅在**计划历史记录**列表中列出 24 小时。按计划运行的查询不会出现在查询编辑器 v2 的**查询历史记录**视图中。 ## 安排查询的演示 有关安排查询的演示，请观看以下视频。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/gTw0XUpO8sw/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/gTw0XUpO8sw) # 设置计划查询的权限 要计划查询，定义计划的 AWS Identity and Access Management（IAM）用户以及与计划关联的 IAM 角色必须配置了使用 Amazon EventBridge 和 Amazon Redshift Data API 的 IAM 权限。要接收来自计划查询的电子邮件，还必须配置可选指定的 Amazon SNS 通知。 以下内容描述了使用 AWS 托管式策略提供权限的任务，但根据您的环境，您可能需要缩小允许的权限范围。 对于登录到查询编辑器 v2 的 IAM 用户，请使用 IAM 控制台（[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)）编辑 IAM 用户。 + 除了运行 Amazon Redshift 和查询编辑器 v2 操作的权限外，还要将 `AmazonEventBridgeFullAccess` 和 `AmazonRedshiftDataFullAccess` AWS 托管式策略附加到 IAM 用户。 + 或者，为角色分配权限并将该角色分配给用户。 附加一个策略，对于您在定义计划查询时指定的 IAM 角色的资源 ARN，该策略将允许 `sts:AssumeRole` 权限。有关代入角色的更多信息，请参阅《IAM 用户指南》**中的[向用户授予切换角色的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html)。 以下示例显示了代入账户 `123456789012` 中的 IAM 角色 `myRedshiftRole` 的权限策略。IAM 角色 `myRedshiftRole` 也是附加到运行计划查询的集群或工作组的 IAM 角色。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AssumeIAMRole", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": [ "arn:aws:iam::123456789012:role/myRedshiftRole" ] } ] } ``` ------ 更新用于计划查询的 IAM 角色的信任策略，以允许 IAM 用户代入此角色。 ``` { "Sid": "AssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/myIAMusername" }, "Action": "sts:AssumeRole" } ] } ``` 对于您指定为允许运行计划查询的 IAM 角色，请使用 IAM 控制台（[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)）编辑 IAM 角色。 + 将 `AmazonRedshiftDataFullAccess` 和 `AmazonEventBridgeFullAccess` AWS 托管式策略附加到 IAM 角色。`AmazonRedshiftDataFullAccess` 托管式策略只允许使用键 `RedshiftDataFullAccess` 标记的 Redshift Serverless 工作组具有 `redshift-serverless:GetCredentials` 权限。 # 对计划查询进行身份验证 当您计划查询时，在 SQL 运行时使用下列身份验证方法之一。每种方法都需要查询编辑器 v2 上的不同输入组合。用于运行 SQL 语句的数据 API 支持这些身份验证方法。 用于运行查询的数据库用户或角色必须具有必要的数据库权限。例如，要授予对于表 `mytable` 的 `IAMR:MyRedshiftQEv2Scheduler` 权限，请运行以下 SQL 命令。 ``` GRANT all ON TABLE mytable TO "IAMR:MyRedshiftQEv2Scheduler"; ``` 要查看集群或工作组中的数据库用户列表，请查询系统视图 `PG_USER_INFO`。 **注意** 您为其计划查询的任何 Redshift Serverless 工作组都必须使用键 `RedshiftDataFullAccess` 进行标记。有关更多信息，请参阅 [授予对 Amazon Redshift 数据 API 的访问权限](data-api-access.md)。 作为标记工作组的替代方法，您可以向 IAM 角色（随计划指定）添加允许 `redshift-serverless:GetCredentials` 的内联策略。例如： **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "UseTemporaryCredentialsForAllServerlessWorkgroups", "Effect": "Allow", "Action": "redshift-serverless:GetCredentials", "Resource": [ "arn:aws:redshift-serverless:*:*:workgroup/*" ] } ] } ``` **AWS Secrets Manager** 使用此方法，为存储在 AWS Secrets Manager 中的 **secret-arn** 提供一个密钥值。此密钥包含用于连接到数据库的凭证。在创建集群或工作组时，您可能已经使用适当的凭证创建了密钥。密钥必须使用键 `RedshiftDataFullAccess` 进行标记。如果标签键尚不存在，请使用 AWS Secrets Manager 控制台进行添加。有关创建密钥的信息，请参阅[为数据库连接凭证创建密钥](redshift-secrets-manager-integration-create.md)。 有关最低权限的更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[使用 AWS Secrets Manager 创建和管理密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)。 **临时凭证** 使用此方法，在连接到集群中的数据库时，需提供您的**数据库名称**和**数据库用户**值。在连接到工作组中的数据库时，只需提供您的**数据库名称**。 连接到集群时，`AmazonRedshiftDataFullAccess` 策略允许名为 `redshift_data_api_user` 的数据库用户拥有对 `redshift:GetClusterCredentials` 的权限。如果要使用其他数据库用户运行 SQL 语句，请向附加到您集群的 IAM 角色添加策略以允许 `redshift:GetClusterCredentials`。以下示例策略允许数据库用户 `awsuser` 和 `myuser`。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "UseTemporaryCredentialsForAllDbUsers", "Effect": "Allow", "Action": "redshift:GetClusterCredentials", "Resource": [ "arn:aws:redshift:*:*:dbuser:*/awsuser", "arn:aws:redshift:*:*:dbuser:*/myuser" ] } ] } ``` # 设置查看计划查询历史记录的权限 要允许用户查看计划查询历史记录，请编辑 IAM 角色（随计划指定）**信任关系**以添加权限。 以下是 IAM 角色中的信任策略示例，该策略允许 IAM 用户 *myIAMusername* 查看计划查询历史记录。您可以选择允许 IAM 角色拥有 `sts:AssumeRole` 权限，而不是允许 IAM 用户拥有此权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "redshift.amazonaws.com", "redshift-serverless.amazonaws.com" ] }, "Action": "sts:AssumeRole" }, { "Effect": "Allow", "Principal": { "Service": "events.amazonaws.com" }, "Action": "sts:AssumeRole" }, { "Sid": "AssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/myIAMusername" }, "Action": "sts:AssumeRole" } ] } ``` ------ # 监控计划查询 对于您指定用于发送电子邮件通知的 Amazon SNS 主题，请使用查询编辑器 v2 创建 Amazon SNS 主题，方法是导航到 **SNS 通知**部分，**开启**监控，然后使用**创建 SNS 主题**来创建主题。查询编辑器 v2 创建 Amazon SNS 主题，并将服务主体添加到 Amazon EventBridge 的访问策略中。以下是在 Amazon SNS 主题中创建的示例**访问策略**。在示例中，使用了 AWS 区域 *us-west-2*、AWS 账户 *123456789012* 以及 Amazon SNS 主题 *select-version-pdx-testunload*。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "__default_policy_ID", "Statement": [ { "Sid": "Allow_Publish_Events", "Effect": "Allow", "Principal": { "Service": "events.amazonaws.com" }, "Action": "sns:Publish", "Resource": "arn:aws:sns:us-west-2:123456789012:select-version-pdx-testunload" } ] } ``` ------ 计划查询运行时，Amazon SNS 会发送 AWS 通知电子邮件。以下示例显示了使用 Amazon SNS 通知主题 *may25a-SNS*，为 AWS 账户 *123456789012* 中在 AWS 区域 *eu-north-1* 上运行的计划查询 *QS2-may25a* 发送到 *myemail@example.com* 的电子邮件。 ``` {"version":"0","id":"8e4323ec-5258-7138-181b-91290e30ff9b","detail-type":"Scheduled Event","source":"aws.events","account":"123456789012","time":"2023-05-25T15:22:00Z", "region":"eu-north-1","resources":["arn:aws:events:eu-north-1:123456789012:rule/QS2-may25a"],"detail":{}} -- If you wish to stop receiving notifications from this topic, please click or visit the link below to unsubscribe: https://sns.eu-north-1.amazonaws.com/unsubscribe.html?SubscriptionArn=arn:aws:sns:eu-north-1:123456789012:may25a-SNS:0c1a3d05-39c2-4507-bc3d-47250513d7b0&Endpoint=myemail@example.com Please do not reply directly to this email. If you have any questions or comments regarding this email, please contact us at https://aws.amazon.com/support ``` # 计划查询设置故障排除 如果您在计划查询时遇到问题，请考虑以下几点。 **查询未运行** 检查计划中使用的 IAM 角色是否有权获取临时集群凭证。预置集群的权限为 `redshift:GetClusterCredentialsWithIAM`。Redshift Serverless 工作组的权限为 `redshift-serverless:GetCredentials`。 **计划历史记录未显示** 用于登录 AWS 控制台的 IAM 用户或 IAM 角色未添加到用于计划查询的 IAM 角色的信任策略中。 当使用 AWS Secrets Manager 供计划的查询进行连接时，请确认已使用键 `RedshiftDataFullAccess` 标记密钥。 如果计划查询使用的是 AWS Secrets Manager 连接，则用于计划查询的 IAM 角色必须具有附加到该角色的等效托管策略 `SecretsManagerReadWrite`。 **查询历史记录状态为 `Failed`** 查看 SYS\$1QUERY\$1HISTORY 系统视图，了解有关查询失败原因的详细信息。一个常见问题是，用于运行查询的数据库用户或角色可能没有运行 SQL 所需的权限。有关更多信息，请参阅 [对计划查询进行身份验证](query-editor-v2-schedule-query-authentication.md)。 以下 SQL 查询 SYS\$1QUERY\$1HISTORY 视图以返回失败的查询。 ``` SELECT user_id, query_id, transaction_id, session_id, database_name, query_type, status, error_message, query_text FROM sys_query_history WHERE status = 'failed'; ``` 要了解失败的特定计划查询的详细信息，请参阅[使用 AWS CloudShell 查看计划查询的结果](query-editor-v2-schedule-query-troubleshooting-cloudshell.md)。 # 使用 AWS CloudShell 查看计划查询的结果 您可以使用 AWS CloudShell 查找有关计划查询的详细信息。您必须具有适当的权限才能运行 AWS CLI 命令，如以下过程所示。 **查看计划查询的结果** 1. 在 AWS 控制台上，打开 AWS CloudShell 命令提示符。有关 AWS CloudShell 的更多信息，请参阅《AWS CloudShell User Guide》**中的[What is AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html)。 1. 代入计划查询的 IAM 角色。要代入该角色，请在查询编辑器 v2 中找到与计划查询关联的 IAM 角色，然后在 AWS CloudShell 中通过 AWS CLI 命令使用它。例如，对于角色 `scheduler`，输入 AWS STS 命令以代入计划查询所用的角色。 ``` aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/scheduler" --role-session-name "scheduler-test" ``` 返回的凭证与以下内容类似。 ``` "Credentials": { "AccessKeyId": "AKIAIOSFODNN7EXAMPLE", "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "SessionToken": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY...", "Expiration": "2023-08-18T18:19:44+00:00" }, "AssumedRoleUser": { "AssumedRoleId": "AROA35B2NH6WBTP7ONL4E:scheduler-test", "Arn": "arn:aws:sts::123456789012:assumed-role/scheduler/scheduler-test" } } ``` 1. 使用代入 IAM 角色时显示的凭证在 AWS CLI 中创建环境变量。您必须在这些令牌到期之前使用它们。例如，您可以在 AWS CloudShell 中输入以下内容。 ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_SESSION_TOKEN=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY... ``` 1. 要查看失败查询的错误，请运行 AWS CLI 命令以描述语句。SQL 语句的 ID 来自查询编辑器 v2 中计划查询的**计划历史记录**部分显示的 **ID**。 ``` aws redshift-data describe-statement --id 130d2620-05d2-439c-b7cf-815d9767f513 ``` 在本例中，计划的 SQL `select * from users limit 100` 会导致一个 SQL 错误，即 `users` 表不存在。 ``` { "CreatedAt": "2023-08-18T17:39:15.563000+00:00", "Duration": -1, "Error": "ERROR: relation \"users\" does not exist", "HasResultSet": false, "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "QueryString": "select * from users limit 100\n—RequestID=a1b2c3d4-5678-90ab-cdef-EXAMPLE22222; TraceID=1-633c5642-4039308d03f3a0ba53dbdf6f", "RedshiftPid": 1073766651, "RedshiftQueryId": 0, "ResultRows": -1, "ResultSize": -1, "Status": "FAILED", "UpdatedAt": "2023-08-18T17:39:16.116000+00:00", "WorkgroupName": "default" } ``` # 可视化查询结果 运行查询并显示结果后，可以打开**图表**以显示当前结果页的图形可视化。您可以使用以下控件来定义图表的内容、结构和外观： ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png) 跟踪 表示图表中的一组相关图形标记。可以在图表中定义多个跟踪。 类型 您可以将跟踪类型定义为以下类型之一来表示数据： + 适用于散点的散点图或气泡图。 + 用垂直条或水平条表示数据类别的条形图。 + 用于定义填充区域的区域图。 + 使用条形表示频率分布的直方图。 + 使用圆形表示数据的饼图，其中每个切片代表所占整体的百分比。 + 用于表示流程不同阶段的数据的漏斗或漏斗区域图。 + OHLC（开盘、高、低、收盘）图通常用于财务数据，表示沿 x 轴的开盘、高、低和收盘值，这通常表示时间间隔。 + K 线图表示时间线上类别的一系列值。 + 瀑布图，表示初始值如何通过一系列中间值而增加或减少。值可以表示时间间隔或类别。 + 折线图表示值随着时间的推移而变化。 X 轴 您可以指定一个表列，其中包含要沿 X 轴绘制的值。包含描述性值的列通常表示维度数据。包含量化值的列通常表示实际数据。 Y 轴 您可以指定一个表列，其中包含要沿 Y 轴绘制的值。包含描述性值的列通常表示维度数据。包含量化值的列通常表示实际数据。 子图 您可以定义图表数据的其它表示形式。 转换 您可以定义转换以筛选跟踪数据。您可以使用拆分转换以显示来自单个源跟踪的多个跟踪。您可以使用聚合转换以将跟踪显示为平均值或最小值。您可以使用排序转换以对跟踪进行排序。 一般外观 您可以设置背景颜色、边距颜色、设计调色板的色阶、文本样式和大小、标题样式和大小以及模式栏的默认值。您可以定义拖动、单击和悬停的交互。您可以定义元文本。您可以定义跟踪、轴、图例和注释的默认外观。 **创建图表** 1. 运行查询并获取结果。 1. 启用**图表**。 1. 选择**跟踪**，然后开启可视化您的数据。 1. 从以下值中选择一种图表样式： + 散点图 + 条形图 + 区域图 + 直方图 + 饼图 + 漏斗图 + 漏斗区域图 + OHLC（开盘、高、低、收盘） + K 线图 + 瀑布图 + 折线图 1. 选择**样式**以自定义外观，包括颜色、轴、图例和注释。您可以添加文本、形状和图像。 1. 选择**注释**添加文本、形状和图像。 1. 要更新显示，请选择**更新**。选择**全屏**以扩大图表显示范围。 ## 示例：创建饼图以可视化查询结果 以下示例使用示例数据库中的*销售*表。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[示例数据库](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 以下是为饼图提供数据而运行的查询。 ``` select top 5 eventname, count(salesid) totalorders, sum(pricepaid) totalsales from sales, event where sales.eventid=event.eventid group by eventname order by 3; ``` **按总销售额作为顶事件创建饼图** 1. 运行查询。 1. 在查询结果区域中，打开**图表**。 1. 选择**跟踪**。 1. 对于**类型**，选择**饼图**。 1. 对于**值**，选择 *totalsales*。 1. 对于**标签**，选择 *eventname*。 1. 选择**样式**，然后选择**普通**。 1. 在**颜色刻度**下，选择**分类**，然后选择 **Pastel2**。 ![\[饼图\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/pie-chart.png) ## 示例：创建用于比较收入和销售额的组合图 执行此示例中的步骤创建一个图表，该图表将收入数据的条形图和销售额数据的折线图组合在一起。以下示例使用 tickit 示例数据库中的 *Sales* 表。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[示例数据库](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 以下是为图表提供数据而运行的查询。 ``` select eventname, total_price, total_qty_sold from (select eventid, total_price, total_qty_sold, ntile(1000) over(order by total_price desc) as percentile from (select eventid, sum(pricepaid) total_price, sum(qtysold) total_qty_sold from tickit.sales group by eventid)) Q, tickit.event E where Q.eventid = E.eventid and percentile = 1 order by total_price desc; ``` **创建用于比较收入和销售额的组合图** 1. 运行查询。 1. 在查询结果区域中，打开**图表**。 1. 在 *trace o* 下，对于**类型**，选择**条形图**。 1. 对于 **X**，选择 *eventname*。 1. 对于 **Y**，选择 *total\$1price*。 条形图将沿 X 轴显示事件名称。 1. 在**样式**下，选择**跟踪**。 1. 对于**名称**，输入*收入*。 1. 在**样式**下，选择**轴**。 1. 对于**标题**，选择 **Y** 然后输入*收入*。 *收入*标签将显示在左侧 Y 轴上。 1. 在**结构**下，选择**跟踪**。 1. 选择 ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png) **跟踪**。 系统将显示跟踪 1 选项。 1. 对于**类型**，选择 **线形图**。 1. 对于 **X**，选择 *eventname*。 1. 对于 **Y**，选择 *total\$1qty\$1sold*。 1. 在**要使用的轴**下，为**Y 轴**选择 ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/add-plus.png)。 **Y 轴**将显示 *Y2*。 1. 在**样式**下，选择**轴**。 1. 在**标题**下，选择 **Y2**。 1. 对于**名称**，输入 *Sales*。 1. 在**线形图**下，选择 *Y:Sales*。 1. 在**轴线**下，选择**显示**，对于**位置**，选择**右侧**。 ![\[收入和销售额表\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/chart-revenue-sales.png) ## 演示：使用 Amazon Redshift 查询编辑器 v2 构建可视化 要了解如何构建可视化项的演示，请观看以下视频。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/-FYqTIER-6U/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/-FYqTIER-6U) # 以团队形式协作和共享 您可以与您的团队共享查询。 团队是针对一组协作并共享查询编辑器 v2 资源的用户定义的。管理员可以通过向 IAM 角色添加标签来创建团队。有关更多信息，请参阅 [使用查询编辑器 v2 所需的权限](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 # 保存和浏览查询 在与团队共享查询之前，请保存查询。您可以查看和删除已保存的查询。 **保存查询** 1. 准备查询然后选择**保存**。 1. 输入查询的标题。 1. 选择**保存**。 **浏览保存的查询** 1. 从导航窗格中，选择**查询**。 1. 您可以查看以下查询：**我的查询**、**由我分享的查询**，或者**分享给我的团队的查询**。这些查询可以显示为单个查询或存在您创建的文件夹中。 # 共享查询 您可以与您的团队共享您的查询。您还可以查看已保存查询的历史记录和管理查询版本。 如要与团队共享查询，请确保您将主要标签 `sqlworkbench-team` 设置为与账户中其它团队成员相同的值。例如，管理员可以为会计部门的每个人将该值设置为 `accounting-team`。有关示例，请参阅[使用查询编辑器 v2 所需的权限](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 **与团队共享查询** 1. 从导航窗格中，选择**查询**。 1. 打开要共享的查询的上下文（右键单击）菜单，然后选择**与我的团队分享**。 1. 选择要与之共享查询的一个或多个团队，然后选择**保存共享选项**。 # 管理查询版本 每次保存 SQL 查询时，查询编辑器 v2 都会将其保存为新版本。您可以浏览早期的查询版本、保存查询副本或恢复查询。 **管理查询版本** 1. 从导航窗格中，选择**查询**。 1. 打开要处理查询的上下文（右键单击）菜单。 1. 选择**版本历史记录**以打开查询的版本列表。 1. 在**版本历史记录**页面上，您可以执行以下操作： + **恢复为选定** – 恢复到选定的版本并继续使用此版本。 + **将选定选项另存为** – 在编辑器中创建新的查询。 # 使用 Amazon Redshift 查询编辑器 v1 查询数据库 使用查询编辑器是在由 Amazon Redshift 集群托管的数据库上运行查询的简单方法。创建集群后，可以使用 Amazon Redshift 控制台上的查询编辑器立即运行查询。 **注意** 您无法使用此原始查询编辑器在 Amazon Redshift Serverless 中查询数据。而应使用 Amazon Redshift 查询编辑器 v2。 2021 年 2 月，部署了更新的查询编辑器，并更改了使用查询编辑器的授权权限。新的查询编辑器使用 Amazon Redshift 数据 API 来运行查询。作为 AWS 托管式 AWS Identity and Access Management (IAM) 策略的 `AmazonRedshiftQueryEditor` 策略已更新为包含必要的权限。如果您有自定义 IAM 策略，请务必更新它。将 `AmazonRedshiftQueryEditor` 用作指南。对 `AmazonRedshiftQueryEditor` 的更改包括以下内容： + 管理查询编辑器语句结果的权限需要语句拥有者用户。 + 已添加使用 Secrets Manager 连接到数据库的权限。 有关更多信息，请参阅 [使用 Amazon Redshift 控制台查询编辑器所需的权限](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor)。 从新的查询编辑器连接到集群时，可以使用两种身份验证方法之一。 使用查询编辑器可以执行以下操作： + 运行单个 SQL 语句查询。 + 将大小为 100 MB 的结果集下载到一个逗号分隔值 (CSV) 文件。 + 保存查询以供重用。您无法在欧洲（巴黎）区域、亚太地区（大阪）区域、亚太地区（香港）区域或中东（巴林）区域中保存查询。 + 查看用户定义表的查询运行时详细信息。 + 安排查询在未来运行。 + 查看您在查询编辑器中创建的查询的历史记录。 + 使用增强型 VPC 路由对集群运行查询。 ## 查询编辑器注意事项 请考虑下列有关使用查询编辑器时处理查询的事项： + 查询的最长持续时间为 24 小时。 + 查询结果的最大大小为 100 MB。如果调用返回的响应数据超过 100 MB，则调用将终止。 + 查询结果的最长保留时间为 24 小时。 + 最大查询语句大小为 100 KB。 + 集群必须在基于 Amazon VPC 服务的 Virtual Private Cloud (VPC) 中。 + 不能在查询编辑器中使用事务处理。有关事务的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [BEGIN](https://docs.aws.amazon.com/redshift/latest/dg/r_BEGIN.html)。 + 您可以保存最长为 3000 个字符的查询。 # 使用 SQL 客户端工具连接到 Amazon Redshift 数据仓库 您可以通过 Java 数据库连接（JDBC）、Python 和开放式数据库连接（ODBC）这几种连接将 SQL 客户端工具连接到 Amazon Redshift 数据仓库。Amazon Redshift 不提供或安装任何 SQL 客户端工具或库。要使用这些工具或库处理数据仓库中的数据，请将它们安装在客户端计算机或 Amazon EC2 实例上。您可以使用支持 JDBC、Python 或 ODBC 驱动程序的大多数 SQL 客户端工具。 使用本主题末尾的章节列表来帮助您完成将客户端计算机或 Amazon EC2 实例配置为使用 JDBC、Python 或 ODBC 连接的过程。这些主题还讨论了与服务器的客户端连接的相关安全选项。此外，还可以查找有关从 SQL 客户端工具（如 [Amazon Redshift RSQL](https://docs.aws.amazon.com/redshift/latest/mgmt/rsql-query-tool.html)）中进行设置和连接的信息。如果您还没有可以使用的商业智能工具，则可以尝试使用这些工具。还可以通过本节了解如何连接到您的数据。最后，如果您在尝试连接到数据仓库时遇到问题，可以查看故障排除信息以确定解决方案。 ## 关于连接客户端工具的建议 如果您使用 IP 地址连接到 Redshift 集群，则当发生中断或连接丢失时，集群会在新的可用区（AZ）中联机，这可能会延长停机时间。但是，如果您仍希望您的应用程序使用 IP 地址连接到 Redshift，请使用附加到集群虚拟私有云（VPC）端点的私有 IP 地址。您可以在**属性**选项卡下的**网络和安全性**中的集群详细信息中找到此信息。 **注意** 如果您的应用程序使用领导节点的 IP 地址来访问 Redshift 集群，则建议的最佳实践是将其更改为使用集群端点 URL。有关更多信息，请参阅[在 Amazon Redshift 中配置连接](https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html)。 **Topics** + [关于连接客户端工具的建议](#connecting-to-cluster-recommendations) + [在 Amazon Redshift 中配置连接](configuring-connections.md) + [配置连接的安全选项](connecting-ssl-support.md) + [通过客户端工具和代码连接](connecting-via-client-tools.md) + [使用身份验证配置文件连接到 Amazon Redshift](connecting-with-authentication-profiles.md) + [解决 Amazon Redshift 中的连接问题](troubleshooting-connections.md) # 在 Amazon Redshift 中配置连接 在以下章节中，了解如何配置 JDBC、Python 和 ODBC 连接以从 SQL 客户端工具连接到集群。此部分介绍如何设置 JDBC、Python 和 ODBC 连接。它还介绍了如何使用安全套接字层 (SSL) 和服务器证书来加密客户端和服务器之间的通信。 ## 适用于 Amazon Redshift 的 JDBC、Python 和 ODBC 驱动程序 要处理集群中的数据，您必须具有 JDBC、Python 或 ODBC 驱动程序，以便从客户端计算机或实例进行连接。对应用程序进行编码以使用 JDBC、Python 或 ODBC 数据访问 API 操作，并使用支持 JDBC 或 ODBC 的 SQL 客户端工具。 Amazon Redshift 提供 JDBC、Python 和 ODBC 驱动程序以供下载。这些驱动程序受 支持 支持。PostgreSQL 驱动程序未经过测试，也不受 Amazon Redshift 团队的支持。连接到 Amazon Redshift 集群时，请使用 Amazon Redshift 特定的驱动程序。Amazon Redshift 驱动程序具有以下优势： + 支持 IAM、SSO 和联合身份验证。 + 支持新的 Amazon Redshift 数据类型。 + 支持身份验证配置文件。 + 结合 Amazon Redshift 增强功能提升性能。 有关如何下载 JDBC 和 ODBC 驱动程序和配置到集群的连接的更多信息，请参阅 [为 Amazon Redshift 配置 JDBC 驱动程序版本 2.x 连接](jdbc20-install.md)、[Amazon Redshift Python 连接器](python-redshift-driver.md) 和 [为 Amazon Redshift 配置 ODBC 驱动程序版本 2.x 连接](odbc20-install.md)。 有关管理 IAM 身份的更多信息，包括 IAM 角色的最佳实践，请参阅 [Amazon Redshift 中的 Identity and Access Management](redshift-iam-authentication-access-control.md)。 # 查找集群连接字符串 要使用 SQL 客户端工具连接到您的集群，您必须具有集群连接字符串。您可以在 Amazon Redshift 控制台中的集群详细信息页面上查找集群连接字符串。 **查找集群的连接字符串** 1. 登录到 AWS 管理控制台并打开 Amazon Redshift 控制台，网址：[https://console.aws.amazon.com/redshiftv2/](https://console.aws.amazon.com/redshiftv2/)。 1. 在导航菜单上，选择**集群**，然后从列表中选择集群名称以打开其详细信息。 1. **一般信息**部分中提供有 **JDBC URL** 和 **ODBC URL** 连接字符串以及其他详细信息。每个字符串均基于运行集群的 AWS 区域。点击相应连接字符串旁边的图标复制该字符串。 要连接到集群端点，可以使用 [DescribeClusters API 请求](https://docs.aws.amazon.com/redshift/latest/APIReference/API_DescribeClusters.html)中的集群端点 URL。以下是集群端点 URL 的示例。 ``` mycluster.cmeaswqeuae.us-east-2.redshift.amazonaws.com ``` 如果您为集群设置了自定义域名，还可以使用该域名连接到您的集群。有关创建自定义域名的更多信息，请参阅[设置自定义域名](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-connection-CNAME-connect.html)。 **注意** 连接时，请勿使用集群节点的 IP 地址或 VPC 端点的 IP 地址。请务必使用 Redshift 端点以避免不必要的中断。使用端点 URL 的唯一例外是使用自定义域名时。有关更多信息，请参阅[使用自定义域名进行客户端连接](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-connection-CNAME.html)。 # 为 Amazon Redshift 配置 JDBC 驱动程序版本 2.x 连接 可以使用 JDBC 驱动程序版本 2.x 连接从多种第三方 SQL 客户端工具连接到 Amazon Redshift 集群。Amazon Redshift JDBC 连接器提供了一个开源解决方案。您可以浏览源代码、请求增强功能、报告问题和提供文章。 有关 JDBC 驱动程序更改的最新信息，请参阅 [change log](https://github.com/aws/amazon-redshift-jdbc-driver/blob/master/CHANGELOG.md)。 预设情况下，Amazon Redshift JDBC 驱动程序将配置为使用 TCP Keepalive 来防止连接超时。可以指定驱动程序开始发送 Keepalive 包的时间或通过在连接 URL 中设置相关属性来关闭该功能。有关连接 URL 的语法的更多信息，请参阅 [构建连接 URL](jdbc20-build-connection-url.md)。 | 属性 | 说明 | | --- | --- | | `TCPKeepAlive` | 要关闭 TCP Keepalive，请将此属性设置为 `FALSE`。 | **Topics** + [下载 Amazon Redshift JDBC 驱动程序版本 2.1](jdbc20-download-driver.md) + [安装 Amazon Redshift JDBC 驱动程序版本 2.2](jdbc20-install-driver.md) + [获取 JDBC URL](jdbc20-obtain-url.md) + [构建连接 URL](jdbc20-build-connection-url.md) + [使用 Apache Maven 配置 JDBC 连接](configure-jdbc20-connection-with-maven.md) + [配置身份验证和 SSL](jdbc20-configure-authentication-ssl.md) + [配置日志记录](jdbc20-configuring-logging.md) + [数据类型转换](jdbc20-data-type-mapping.md) + [使用预编译的语句支持](jdbc20-prepared-statement-support.md) + [JDBC 驱动程序 2.2 版本与 1.x 版本之间的差异](jdbc20-jdbc10-driver-differences.md) + [为 JDBC 驱动程序版本 2.x 创建初始化 (.ini) 文件](jdbc20-ini-file.md) + [JDBC 驱动程序版本 2.x 配置的选项](jdbc20-configuration-options.md) + [JDBC 驱动程序版本 2.x 的以前版本](jdbc20-previous-driver-version-20.md) # 下载 Amazon Redshift JDBC 驱动程序版本 2.1 **注意** Amazon Redshift JDBC 2.x 驱动程序并不是为线程安全而设计的。两个或更多线程并发尝试使用同一个连接可能会导致死锁、错误、不正确的结果或其它意外行为。 如果您有多线程应用程序，我们建议您同步对驱动程序的访问，以避免并发访问。 Amazon Redshift 向与 JDBC 4.2 API 兼容的工具提供驱动程序。此驱动程序的类名是 `com.amazon.redshift.Driver`。 有关如何安装 JDBC 驱动程序、引用 JDBC 驱动程序库和注册驱动程序类的详细信息，请参阅以下主题。 对于您在其上使用 Amazon Redshift JDBC 驱动程序版本 2.x 的每台计算机，请确保已安装 Java 运行时环境（JRE）8.0。 如果将 Amazon Redshift JDBC 驱动程序用于数据库身份验证，请确保您的 Java 类路径中包含 适用于 Java 的 AWS SDK 1.11.118 或更高版本。如果您没有安装 适用于 Java 的 AWS SDK，请下载带有与 JDBC 4.2 兼容的驱动程序和 AWS SDK 驱动程序相关库的 ZIP 文件： + [与 JDBC 4.2 兼容的驱动程序版本 2.x 和 AWS SDK 驱动程序依赖库](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.5/redshift-jdbc42-2.2.5.zip) 此 ZIP 文件包含与 JDBC 4.2 兼容的驱动程序版本 2.x 和适用于 Java 的 AWS SDK 1.x 驱动程序相关库文件。将相关 jar 文件解压缩到与 JDBC 驱动程序相同的位置。只有 JDBC 驱动程序需要位于 CLASSPATH 中。 此 ZIP 文件不包含完整的 AWS SDK for Java 1.x。但是，它包含适用于 AWS Identity and Access Management (IAM) 数据库身份验证所需的 Java 1.x 驱动程序相关库的 AWS 开发工具包。 将此 Amazon Redshift JDBC 驱动程序与 IAM 数据库身份验证所需的 AWS SDK 一起使用。 要安装完整的 AWS SDK for Java 1.x，请参阅《适用于 Java 的 AWS SDK 开发人员指南》**中的 [AWS SDK for Java 1.x](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/welcome.html)。 + [与 JDBC 4.2 兼容的驱动程序版本 2.x（不含 AWS SDK）](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.5/redshift-jdbc42-2.2.5.jar) 查看 JDBC 驱动程序版本 2.x 软件许可证并更改日志文件： + [JDBC 驱动程序版本 2.x 许可证](https://github.com/aws/amazon-redshift-jdbc-driver/blob/master/LICENSE) + [JDBC 驱动程序版本 2.x 更改日志](https://github.com/aws/amazon-redshift-jdbc-driver/blob/master/CHANGELOG.md) JDBC 驱动程序版本 1.2.27.1051 及更高版本支持 Amazon Redshift 存储过程。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[在 Amazon Redshift 中创建存储过程](https://docs.aws.amazon.com/redshift/latest/dg/stored-procedure-overview.html)。 # 安装 Amazon Redshift JDBC 驱动程序版本 2.2 要安装与 Amazon Redshift JDBC 4.2 兼容的驱动程序版本 2.x 和 AWS SDK 的驱动程序相关库，请将文件从 ZIP 归档提取到您选择的目录。 要安装与 Amazon Redshift JDBC 4.2 兼容的驱动程序版本 2.x（不含 AWS SDK），请将 JAR 文件复制到您选择的目录。 要使用 Amazon Redshift JDBC 驱动程序访问 Amazon Redshift 数据存储，您需要执行如下配置。 **Topics** + [引用 JDBC 驱动程序库](jdbc20-driver-libraries.md) + [注册驱动程序类](jdbc20-register-driver-class.md) # 引用 JDBC 驱动程序库 用于连接到数据的 JDBC 应用程序或 Java 代码必须访问驱动程序 JAR 文件。在应用程序或代码中，指定从 ZIP 归档中提取的所有 JAR 文件。 ## 在 JDBC 应用程序中使用驱动程序 JDBC 应用程序通常提供一组用于添加驱动程序库文件列表的配置选项。使用提供的选项将 ZIP 归档中的所有 JAR 文件作为应用程序中的驱动程序配置的一部分。有关更多信息，请参阅您 JDBC 应用程序的文档。 ## 在 Java 代码中使用驱动程序 您必须在类路径中包含所有驱动程序库文件。这是 Java 运行时环境搜索类和其他资源文件的路径。有关更多信息，请参阅相应的 Java SE 文档，以便为操作系统设置类路径。 + Windows：[https://docs.oracle.com/javase/7/docs/technotes/tools/windows/classpath.html](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/classpath.html) + Linux 和 Solaris：[https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/classpath.html](https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/classpath.html) + macOS：默认 macOS 类路径是安装 JDBC 驱动程序的目录。 # 注册驱动程序类 请确保您为您的应用程序注册了适当的类。您可以使用以下类将 Amazon Redshift JDBC 驱动程序连接到 Amazon Redshift 数据存储： + `Driver` 类扩展 `java.sql.Driver`。 + `DataSource` 类扩展 `javax.sql.DataSource` 和 `javax.sql.ConnectionPoolDataSource`。 驱动程序支持以下独立于 JDBC 版本的完全限定类名： + `com.amazon.redshift.jdbc.Driver` + `com.amazon.redshift.jdbc.DataSource` 以下示例说明了如何使用 DriverManager 类建立 JDBC 4.2 的连接。 ``` private static Connection connectViaDM() throws Exception { Connection connection = null; connection = DriverManager.getConnection(CONNECTION_URL); return connection; } ``` 下面的示例展示了如何使用 `DataSource` 类建立连接。 ``` private static Connection connectViaDS() throws Exception { Connection connection = null; 11 Amazon Redshift JDBC Driver Installation and Configuration Guide DataSource ds = new com.amazon.redshift.jdbc.DataSource (); ds.setURL(CONNECTION_URL); connection = ds.getConnection(); return connection; } ``` # 获取 JDBC URL 您需要获知您的 Amazon Redshift 集群的 JDBC URL，才能将 SQL 客户端工具连接到该集群。JDBC URL 采用以下格式：`jdbc:redshift://endpoint:port/database`。 上述格式的字段具有以下值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/jdbc20-obtain-url.html) 以下是一个示例 JDBC URL：`jdbc:redshift://examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com:5439/dev` 如果您的 URL 值包含以下任何 URI 预留字符，则这些值必须经过 URL 编码： + ; + \$1 + \$1 + \$1 + [ + ] + & + = + ? + 一个空格 例如，如果 `PWD` 的值为 `password:password`，则使用该值的连接 URL 将如下所示： `jdbc:redshift://redshift.company.us-west-1.redshift.amazonaws.com:9000/dev;UID=amazon;PWD=password%3Apassword` 有关如何获取 JDBC 连接的信息，请参阅[查找集群连接字符串](connecting-connection-string.md)。 如果客户端计算机无法连接到数据库，您可以进行故障排除，解决可能存在的问题。有关更多信息，请参阅 [解决 Amazon Redshift 中的连接问题](troubleshooting-connections.md)。 # 构建连接 URL 使用连接 URL 向您正在访问的数据存储提供连接信息。以下是 Amazon Redshift JDBC 驱动程序版本 2.x 的连接 URL 的格式。此处，[主机] 是 Amazon Redshift 服务器的端点，[端口] 是服务器用于侦听客户端请求的传输控制协议 (TCP) 端口的编号。 ``` jdbc:redshift://[Host]:[Port] ``` 以下是指定某些可选设置的连接 URL 的格式。 ``` jdbc:redshift://[Host]:[Port]/[database];[Property1]=[Value]; [Property2]=[Value]; ``` 如果您的 URL 值包含以下任何 URI 预留字符，则这些值必须经过 URL 编码： + ; + \$1 + \$1 + \$1 + [ + ] + & + = + ? + 一个空格 例如，如果 `PWD` 的值为 `password:password`，则使用该值的连接 URL 将如下所示： `jdbc:redshift://redshift.company.us-west-1.redshift.amazonaws.com:9000/dev;UID=amazon;PWD=password%3Apassword` 例如，假设您希望在 AWS 上连接到位于美国西部（加利福尼亚北部）区域的 Amazon Redshift 集群上的端口 9000。您还希望访问名为 `dev` 的数据库，并使用数据库用户名和密码对连接进行身份验证。在此情况下，您使用以下连接 URL。 ``` jdbc:redshift://redshift.company.us-west-1.redshift.amazonaws.com:9000/dev;UID=amazon;PWD=amazon ``` 您可以使用以下字符将配置选项与 URL 字符串的其余部分分隔开： + ; + ? 例如，以下 URL 字符串等效： ``` jdbc:redshift://my_host:5439/dev;ssl=true;defaultRowFetchSize=100 ``` ``` jdbc:redshift://my_host:5439/dev?ssl=true;defaultRowFetchSize=100 ``` 您可以使用以下字符将 URL 字符串中的配置选项彼此分隔开： + ; + & 例如，以下 URL 字符串等效： ``` jdbc:redshift://my_host:5439/dev;ssl=true;defaultRowFetchSize=100 ``` ``` jdbc:redshift://my_host:5439/dev;ssl=true&defaultRowFetchSize=100 ``` 以下 URL 示例指定日志级别 6 和日志的路径。 ``` jdbc:redshift://redshift.amazonaws.com:5439/dev;DSILogLevel=6;LogPath=/home/user/logs; ``` 不要复制连接 URL 中的属性。 有关可指定的配置选项的完整列表，请参阅 [JDBC 驱动程序版本 2.x 配置的选项](jdbc20-configuration-options.md)。 **注意** 连接时，请勿使用集群节点的 IP 地址或 VPC 端点的 IP 地址。请务必使用 Redshift 端点以避免不必要的中断。使用端点 URL 的唯一例外是使用自定义域名时。有关更多信息，请参阅[使用自定义域名进行客户端连接](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-connection-CNAME.html)。 # 使用 Apache Maven 配置 JDBC 连接 Apache Maven 是一款软件项目管理及理解工具。适用于 Java 的 AWS SDK 支持 Apache Maven 项目。有关更多信息，请参阅《适用于 Java 的 AWS SDK 开发人员指南》**中的[将开发工具包与 Apache Maven 一起使用](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html)。 如果您使用 Apache Maven，可以配置并构建您的项目，以使用 Amazon Redshift JDBC 驱动程序与 Amazon Redshift 集群连接。为此，在项目的 `pom.xml` 文件中将 JDBC 驱动程序添加为依赖项。如果您使用 Maven 生成项目并希望使用 JDBC 连接，请执行以下部分中的步骤。 **将 JDBC 驱动程序配置为 Maven 依赖项** 1. 将 Amazon 存储库或 Maven Central 存储库添加到您的 `pom.xml` 文件的存储库部分。 **注意** 以下代码示例中的 URL 如果用在浏览器中，将返回错误。仅在 Maven 项目的上下文中使用此 URL。 要使用安全套接字层 (SSL) 进行连接，请将以下存储库添加到您的 `pom.xml` 文件。 ``` redshift https://s3.amazonaws.com/redshift-maven-repository/release ``` 对于 Maven Central 存储库，请将以下内容添加到您的 `pom.xml` 文件。 ``` redshift https://repo1.maven.org/maven2 ``` 1. 在 `pom.xml` 文件的依赖项部分中，声明您要使用的驱动程序版本。 Amazon Redshift 向与 JDBC 4.2 API 兼容的工具提供驱动程序。有关这些驱动程序支持的功能的信息，请参阅 [下载 Amazon Redshift JDBC 驱动程序版本 2.1](jdbc20-download-driver.md)。 将以下示例中的 `driver-version` 替换为您的驱动程序版本，例如 `2.1.0.1`。对于兼容 JDBC 4.2 的驱动程序，请使用以下内容。 ``` com.amazon.redshift redshift-jdbc42 driver-version ``` 此驱动程序的类名是 `com.amazon.redshift.Driver`。 当您使用 IAM 数据库身份验证时，Amazon Redshift Maven 驱动程序需要以下可选依赖项。 ``` com.amazonaws aws-java-sdk-core 1.12.23 runtime true com.amazonaws aws-java-sdk-redshift 1.12.23 runtime true com.amazonaws aws-java-sdk-sts 1.12.23 runtime true ``` 要将 Amazon Redshift JDBC 驱动程序升级或更改到最新版本，请先将依赖项的版本部分修改为驱动程序的最新版本。然后用 Maven Clean Plugin 清除您的项目，如下所示。 ``` mvn clean ``` # 配置身份验证和 SSL 为了防止数据遭到未经授权的访问，Amazon Redshift 数据存储要求所有连接都使用用户凭据进行身份验证。某些数据存储还要求通过安全套接字层 (SSL) 协议建立连接，无论是否使用单向身份验证。 Amazon Redshift JDBC 驱动程序版本 2.x 提供了对这些身份验证协议的完全支持。 驱动程序支持的 SSL 版本取决于您使用的 JVM 版本。有关每个 Java 版本支持的 SSL 版本的信息，请参阅 Java 平台组产品管理博客上的[诊断 TLS、SSL 和 HTTPS](https://blogs.oracle.com/java-platform-group/diagnosing-tls,-ssl,-and-https)。 用于连接的 SSL 版本是驱动程序和服务器都支持的最高版本，该版本在连接时确定。 配置 Amazon Redshift JDBC 驱动程序版本 2.x，以根据要连接到的 Redshift 服务器的安全要求对连接进行身份验证。 要对连接进行身份验证，您必须始终提供您的 Redshift 用户名和密码。根据服务器上是否启用或需要 SSL，您可能还需要将驱动程序配置为通过 SSL 进行连接。或者，您可能要使用单向 SSL 身份验证，以便客户端（驱动程序本身）验证服务器的身份。 在连接 URL 中将配置信息提供给驱动程序。有关连接 URL 的语法的更多信息，请参阅 [构建连接 URL](jdbc20-build-connection-url.md)。 *SSL* 表示 TLS/SSL，包括传输层安全性和安全套接字层。驱动程序支持 TLS/SSL 的行业标准版本。 ## 配置 IAM 身份验证 如果您使用 IAM 身份验证连接到 Amazon Redshift 服务器，请将以下属性设置为数据来源连接字符串的一部分。 有关 IAM 身份验证的更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](redshift-iam-authentication-access-control.md)。 要使用 IAM 身份验证，请使用以下连接字符串格式之一： | 连接字符串 | 描述 | | --- | --- | | `jdbc:redshift:iam:// [host]:[port]/[db]` | 常规连接字符串。驱动程序从主机推断 ClusterID 和区域。 | | `jdbc:redshift:iam:// [cluster-id]: [region]/[db]` | 在已知 ClusterID 和区域的情况下，驱动程序将检索主机信息。 | | `jdbc:redshift:iam:// [host]/[db]` | 驱动程序默认为端口 5439，并从主机推断 ClusterID 和区域。根据您在创建、修改或迁移集群时选择的端口，允许访问所选端口。 | ## 指定配置文件 如果您使用 IAM 身份验证，则可以在配置文件名称下指定任何其他必需或可选的连接属性。通过这样做，您可以避免将某些信息直接放入连接字符串中。您可以使用 Profile 属性在连接字符串中指定配置文件名称。 配置文件可以添加到 AWS 凭证文件。此文件的默认位置为：`~/.aws/credentials` 您可以通过在以下环境变量中设置路径更改默认值：`AWS_CREDENTIAL_PROFILES_FILE` 有关配置文件的更多信息，请参阅 *适用于 Java 的 AWS SDK* 中的[使用 AWS 凭证](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)。 ## 使用实例配置文件凭证 如果您在与 IAM 角色关联的 Amazon EC2 实例上运行应用程序，则可以使用实例配置文件凭证进行连接。 为此，请使用上表中的 IAM 连接字符串格式之一，并将 dbuser 连接属性设置为您正要以其身份连接的 Amazon Redshift 用户名。 有关实例配置文件的更多信息，请参阅《IAM 用户指南》**中的[访问控制](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html)。 ## 使用凭证提供程序 驱动程序还支持来自以下服务的凭证提供程序插件： + AWS IAM Identity Center + Active Directory 联合身份验证服务 (ADFS) + JSON Web Token (JWT) 服务 + Microsoft Azure Active Directory (AD) 服务和浏览器 Microsoft Azure Active Directory (AD) 服务 + Okta 服务 + PingFederate 服务 + 适用于 SAML 服务（如 Okta、Ping 或 ADFS）的浏览器 SAML 如果您使用上述服务之一，则连接 URL 需要指定以下属性： + **Plugin\$1Name** – 凭证提供程序插件类的完全限定类路径。 + **IdP\$1Host：**– 您用于对 Amazon Redshift 进行身份验证的服务的主机。 + **IdP\$1Port** – 身份验证服务的主机侦听的端口。Okta 不需要。 + **User** – idp\$1host 服务器的用户名。 + **Password** – 与 idp\$1host 用户名关联的密码。 + **DbUser** – 您连接时使用的 Amazon Redshift 用户名。 + **SSL\$1Insecure** – 指示是否应验证 IDP 服务器证书。 + **Client\$1ID** – 与 Azure AD 门户中的用户名关联的客户端 ID。仅用于 Azure AD。 + **Client\$1Secret** – 与 Azure AD 门户中的客户端 ID 关联的客户端密钥。仅用于 Azure AD。 + **IdP\$1Tenant** – 适用于您的 Amazon Redshift 应用程序的 Azure AD 租户 ID。仅用于 Azure AD。 + **App\$1ID** – 您的 Amazon Redshift 应用程序的 Okta 应用程序 ID。仅适用于 Okta。 + **应用程序名称** – 您的 Amazon Redshift 应用程序的可选 Okta 应用程序名称。仅适用于 Okta。 + **Partner\$1SPID** – 可选的合作伙伴 SPID（服务提供商 ID）值。仅用于 PingFederate。 + **Idc\$1Region** – AWS IAM Identity Center 实例所在的 AWS 区域。仅用于 AWS IAM Identity Center。 + **Issuer\$1Url** – AWS IAM Identity Center 服务器的实例端点。仅用于 AWS IAM Identity Center。 如果您将浏览器插件用于这些服务之一，则连接 URL 还可以包括： + **Login\$1URL** – 通过浏览器插件使用安全断言标记语言 (SAML) 或 Azure AD 服务时，身份提供者网站上的资源的 URL。如果使用浏览器插件，则此参数是必需的。 + **Listen\$1Port** – 通过浏览器插件使用 SAML、Azure AD 或 AWS IAM Identity Center 服务时，驱动程序用于从身份提供者获取 SAML 响应的端口。 + **IdP\$1Response\$1Timeout** – 通过浏览器插件使用 SAML、Azure AD 或 AWS IAM Identity Center 服务时，驱动程序等待身份提供者的 SAML 响应的时间（以秒为单位）。 有关其他连接字符串属性的信息，请参阅[JDBC 驱动程序版本 2.x 配置的选项](jdbc20-configuration-options.md)。 # 仅使用用户名和密码 如果要连接的服务器不使用 SSL，则只需提供 Redshift 用户名和密码即可对连接进行身份验证。 **仅使用您的 Redshift 用户名和密码配置身份验证** 1. 将 `UID` 属性设置为您的 Redshift 用户名，以便访问 Amazon Redshift 服务器。 1. 将 PWD 属性设置为与您的 Redshift 用户名相对应的密码。 # 在不验证身份的情况下使用 SSL 如果要连接的服务器使用 SSL 但不需要身份验证，则可以将驱动程序配置为使用非验证 SSL 出厂设置。 **要在不进行身份验证的情况下配置 SSL 连接** 1. 将 `UID` 属性设置为您的 Redshift 用户名，以便访问 Amazon Redshift 服务器。 1. 将 `PWD` 属性设置为与您的 Redshift 用户名相对应的密码。 1. 将 `SSLFactory` 属性设置为 `com.amazon.redshift.ssl.NonValidatingFactory`。 # 使用单向 SSL 身份验证 如果要连接的服务器使用 SSL 并且具有证书，则您可以将驱动程序配置为使用单向身份验证来验证服务器的身份。 单向身份验证需要签名、受信任的 SSL 证书来验证服务器的身份。您可以将驱动程序配置为使用特定证书或访问包含相应证书的 TrustStore。如果您未指定证书或 TrustStore，则驱动程序将使用默认的 Java TrustStore（通常为 `jssecacerts` 或 `cacerts`）。 **要配置单向 SSL 身份验证** 1. 将 UID 属性设置为您的 Redshift 用户名，以便访问 Amazon Redshift 服务器。 1. 将 PWD 属性设置为与您的 Redshift 用户名相对应的密码。 1. 将 SSL 属性设置为 true。 1. 将 SSLRootCert 属性设置为根 CA 证书的位置。 1. 如果您未使用默认的 Java TrustStore 之一，请执行以下操作之一： + 要指定服务器证书，请将 SSLRootCert 属性设置为证书的完整路径。 + 要指定 TrustStore，请执行以下操作： 1. 使用 keytool 程序将服务器证书添加到要使用的 TrustStore 中。 1. 指定使用驱动程序启动 Java 应用程序时要使用的 TrustStore 和密码。例如： ``` -Djavax.net.ssl.trustStore=[TrustStoreName] -Djavax.net.ssl.trustStorePassword=[TrustStorePassword] -Djavax.net.ssl.trustStoreType=[TrustStoreType] ``` 1. 请选择一种： + 要验证证书，请将 SSLMode 属性设置为 verify-ca。 + 要验证证书并确认证书中的主机名，请将 SSLMode 属性设置为 verify-full。 # 配置日志记录 您可以在驱动程序中打开日志记录以帮助诊断问题。 您可以使用以下方法记录驱动程序信息： + 要将记录的信息保存在 .log 文件中，请参阅 [使用日志文件](jdbc20-using-log-files.md)。 + 要将记录的信息发送到 DriverManager 中指定的 LogStream 或 LogWriter，请参阅 [使用 LogStream 或 LogWriter](jdbc20-logstream-option.md)。 在连接 URL 中将配置信息提供给驱动程序。有关连接 URL 的语法的更多信息，请参阅 [构建连接 URL](jdbc20-build-connection-url.md)。 # 使用日志文件 只有打开足够长的日志记录才能捕获问题。日志记录会降低性能，并会占用大量磁盘空间。 在连接 URL 中设置 LogLevel 键以打开日志记录并指定包含在日志文件中的详细信息量。下表列出了 Amazon Redshift JDBC 驱动程序版本 2.x 提供的日志记录级别，按从最不详细到最详细的顺序排列。 | LogLevel 值 | 描述 | | --- | --- | | 1 | 记录将导致驱动程序中止的严重错误事件。 | | 2 | 记录也许不会导致驱动程序中止运行的错误事件。 | | 3 | 记录在未执行操作时可能导致错误的事件。此日志记录级别和高于此级别的日志记录级别也会记录用户的查询。 | | 4 | 记录描述驱动程序进程的一般信息。 | | 5 | 记录用于调试驱动程序的详细信息。 | | 6 | 记录所有驱动程序活动。 | **要设置使用日志文件的日志记录** 1. 将 LogLevel 属性设置为要包含在日志文件中的所需信息级别。 1. 将 LogPath 属性设置为您要保存日志文件的目标文件夹的完整路径。 例如，以下连接 URL 启用日志记录级别 3 并将日志文件保存在 C:\$1temp 文件夹中：`jdbc:redshift://redshift.company.us-west- 1.redshift.amazonaws.com:9000/Default;DSILogLevel=3;LogPath=C:\temp` 1. 要确保新设置生效，请重新启动 JDBC 应用程序并重新连接到服务器。 Amazon Redshift JDBC 驱动程序在 LogPath 属性中指定的位置生成以下日志文件： + redshift\$1jdbc.log 文件，该文件记录不特定于连接的驱动程序活动。 + 与数据库建立的每个连接的 redshift\$1jdbc\$1connection\$1[Number].log 文件，其中 [Number] 是标识每个日志文件的编号。此文件记录特定于连接的驱动程序活动。 如果 LogPath 值无效，则驱动程序将记录的信息发送到标准输出流（`System.out`） # 使用 LogStream 或 LogWriter 只有打开足够长的日志记录才能捕获问题。日志记录会降低性能，并会占用大量磁盘空间。 在连接 URL 中设置 LogLevel 键以打开日志记录，并指定发送到 DriverManager 中指定的 LogStream 或 LogWriter 的详细信息量。 **要打开使用 LogStream 或 LogWriter 的日志记录：** 1. 要将驱动程序配置为记录描述驱动程序进度的一般信息，请将 LogLevel 属性设置为 1 或 INFO。 1. 要确保新设置生效，请重新启动 JDBC 应用程序并重新连接到服务器。 # 数据类型转换 Amazon Redshift JDBC 驱动程序版本 2.x 支持许多常见的数据格式，从而可在 Amazon Redshift、SQL 和 Java 数据类型之间进行转换。 下表列出了支持的数据类型映射。 | Amazon Redshift 类型 | SQL 类型 | Java 类型 | | --- | --- | --- | | BIGINT | SQL\$1BIGINT | 长整型 | | BOOLEAN | SQL\$1BIT | Boolean | | CHAR | SQL\$1CHAR | 字符串 | | DATE | SQL\$1TYPE\$1DATE | java.sql.Date | | DECIMAL | SQL\$1NUMERIC | BigDecimal | | DOUBLE PRECISION | SQL\$1DOUBLE | Double | | GEOMETRY | SQL\$1 LONGVARBINARY | byte[] | | INTEGER | SQL\$1INTEGER | 整数 | | OID | SQL\$1BIGINT | 长整型 | | SUPER | SQL\$1LONGVARCHAR | 字符串 | | REAL | SQL\$1REAL | Float | | SMALLINT | SQL\$1SMALLINT | 短型 | | TEXT | SQL\$1VARCHAR | 字符串 | | TIME | SQL\$1TYPE\$1TIME | java.sql.Time | | TIMETZ | SQL\$1TYPE\$1TIME | java.sql.Time | | TIMESTAMP | SQL\$1TYPE\$1 TIMESTAMP | java.sql.Timestamp | | TIMESTAMPTZ | SQL\$1TYPE\$1 TIMESTAMP | java.sql.Timestamp | | VARCHAR | SQL\$1VARCHAR | 字符串 | # 使用预编译的语句支持 Amazon Redshift JDBC 驱动程序支持预编译的语句。您可以使用预编译的语句来提高需要在同一连接过程中多次运行的参数化查询的性能。 *预编译的语句*是在服务器端编译但不立即运行的 SQL 语句。在关闭对象或连接之前，已编译的语句作为 PreparedStatement 对象存储在服务器上。当该对象存在时，您可以根据需要使用不同的参数值多次运行预编译的语句，而无需再次编译该语句。此操作降低了开销，可以更快地运行一组查询。 有关预编译语句的更多信息，请参阅[来自 Oracle 的 JDBC 基础知识教程](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html)中的“使用预编译语句”。 您可以预编译包含多个查询的语句。例如，以下预编译语句包含两个 INSERT 查询： ``` PreparedStatement pstmt = conn.prepareStatement("INSERT INTO MyTable VALUES (1, 'abc'); INSERT INTO CompanyTable VALUES (1, 'abc');"); ``` 请注意，这些查询不依赖于在同一预编译语句内指定的其他查询的结果。由于查询在预编译步骤期间未运行，因此尚未返回结果，并且不可用于同一预编译语句中的其他查询。 例如，不允许使用以下预编译语句，该语句将创建一个表，然后将值插入到该新创建的表中： ``` PreparedStatement pstmt = conn.prepareStatement("CREATE TABLE MyTable(col1 int, col2 varchar); INSERT INTO myTable VALUES (1, 'abc');"); ``` 如果您尝试预编译此语句，服务器将返回一个错误，指出目标表 (myTable) 尚不存在。必须先运行 CREATE 查询，然后才能预编译 INSERT 查询。 # JDBC 驱动程序 2.2 版本与 1.x 版本之间的差异 本节介绍 JDBC 驱动程序的 2.2 和 1.x 版本返回的信息的差异。JDBC 驱动程序 1.x 版本已停产。 下表列出了由 getDatabaseProductName() 和 getDatabaseProductVersion() 函数为每个版本的 JDBC 驱动程序返回的 DatabaseMetadata 信息。JDBC 驱动程序版本 2.2 在建立连接时获取值。JDBC 驱动程序版本 1.x 通过查询获取值。 | JDBC 驱动程序版本 | getDatabaseProductName() 结果 | getDatabaseProductVersion() 结果 | | --- | --- | --- | | 2.2 | Redshift | 8.0.2 | | 1.x | PostgreSQL | 08.00.0002 | 下表列出了由 getTypeInfo 函数为每个版本的 JDBC 驱动程序返回的 DatabaseMetadata 信息。 | JDBC 驱动程序版本 | getTypeInfo 结果 | | --- | --- | | 2.2 | 与 Redshift 数据类型一致 | | 1.x | 与 PostgreSQL 数据类型保持一致 | # 为 JDBC 驱动程序版本 2.x 创建初始化 (.ini) 文件 通过对 Amazon Redshift JDBC 驱动程序版本 2.x 使用初始化 (.ini) 文件，可以指定系统级别的配置参数。例如，联合 IdP 身份验证参数可能因每个应用程序而异。.ini 文件为 SQL 客户端提供了获取所需配置参数的常见位置。 可以创建包含 SQL 客户端配置选项的 JDBC 驱动程序版本 2.x 初始化 (.ini) 文件。文件的默认名称为 `rsjdbc.ini`。JDBC 驱动程序版本 2.x 在按优先级顺序列出的以下位置检查 .ini 文件： + `IniFile`连接 URL 或 SQL 客户端的连接属性对话框中的 参数。请确保 `IniFile` 参数包含 .ini 文件的完整路径，其中包括文件名。有关 `IniFile` 参数的信息，请参阅 [IniFile](jdbc20-configuration-options.md#jdbc20-inifile-option)。如果 `IniFile` 参数错误地指定了 .ini 文件的位置，将显示错误。 + 环境变量，例如具有完整路径 AMAZON\$1REDSHIFT\$1JDBC\$1INI\$1FILE，包括文件名。您可以使用 `rsjdbc.ini` 或指定文件名。如果 AMAZON\$1REDSHIFT\$1JDBC\$1INI\$1FILE 环境变量错误地指定了 .ini 文件的位置，将显示一个错误。 + 驱动程序 JAR 文件所在的目录。 + 用户主目录。 + 系统的临时目录。 您可以将 .ini 文件组织成各个部分，例如 [DRIVER]。每个部分都包含键-值对，这些键-值对将指定各种连接参数。您可以使用 `IniSection` 参数来指定 .ini 文件中的部分。有关 `IniSection` 参数的信息，请参阅 [IniSection](jdbc20-configuration-options.md#jdbc20-inisection-option)。 以下是 .ini 文件格式的示例，其中包含了 [DRIVER]、[DEV]、[QA] 和 [PROD] 的部分。[DRIVER] 部分可以应用于任何连接。 ``` [DRIVER] key1=val1 key2=val2 [DEV] key1=val1 key2=val2 [QA] key1=val1 key2=val2 [PROD] key1=val1 key2=val2 ``` JDBC 驱动程序版本 2.x 从按优先级顺序列出的以下位置加载配置参数： + 应用程序代码中的默认配置参数。 + .ini 文件中的 [DRIVER] 部分属性（如果包含）。 + 自定义部分配置参数，如果 `IniSection` 选项在连接 URL 或 SQL 客户端的连接属性对话框中提供。 + `getConnection` 调用中指定的连接属性对象的属性。 + 连接 URL 中指定的配置参数。 # JDBC 驱动程序版本 2.x 配置的选项 下面，您可以找到您可以为 Amazon Redshift JDBC 驱动程序 2.2 版本指定的选项的说明。配置选项不区分大小写。 您可以使用连接 URL 设置配置属性。有关更多信息，请参阅 [构建连接 URL](jdbc20-build-connection-url.md)。 **Topics** + [AccessKeyID](#jdbc20-accesskeyid-option) + [AllowDBUserOverride](#jdbc20-allowdbuseroverride-option) + [App\$1ID](#jdbc20-app-id-option) + [App\$1Name](#jdbc20-app-name-option) + [ApplicationName](#jdbc20-applicationname-option) + [AuthProfile](#jdbc20-authprofile-option) + [AutoCreate](#jdbc20-autocreate-option) + [Client\$1ID](#jdbc20-client_id-option) + [Client\$1Secret](#jdbc20-client_secret-option) + [ClusterID](#jdbc20-clusterid-option) + [压缩](#jdbc20-compression-option) + [connectTimeout](#jdbc20-connecttimeout-option) + [connectionTimezone](#jdbc20-connecttimezone-option) + [databaseMetadataCurrentDbOnly](#jdbc20-databasemetadatacurrentdbonly-option) + [DbUser](#jdbc20-dbuser-option) + [DbGroups](#jdbc20-dbgroups-option) + [DBNAME](#jdbc20-dbname-option) + [defaultRowFetchSize](#jdbc20-defaultrowfetchsize-option) + [DisableIsValidQuery](#jdbc20-disableisvalidquery-option) + [enableFetchRingBuffer](#jdbc20-enablefetchringbuffer-option) + [enableMultiSqlSupport](#jdbc20-enablemultisqlsupport-option) + [fetchRingBufferSize](#jdbc20-fetchringbuffersize-option) + [ForceLlowcase](#jdbc20-forcelowercase-option) + [groupFederation](#jdbc20-groupFederation-option) + [HOST](#jdbc20-host-option) + [IAMDisableCache](#jdbc20-iamdisablecache-option) + [IAMDuration](#jdbc20-iamduration-option) + [Idc\$1Client\$1Display\$1Name](#jdbc20-idc_client_display_name) + [Idc\$1Region](#jdbc20-idc_region) + [IdP\$1Host](#jdbc20-idp_host-option) + [IdP\$1Partition](#jdbc20-idp_partition-option) + [IdP\$1Port](#jdbc20-idp_port-option) + [IdP\$1Tenant](#jdbc20-idp_tenant-option) + [IdP\$1Response\$1Timeout](#jdbc20-idp_response_timeout-option) + [IniFile](#jdbc20-inifile-option) + [IniSection](#jdbc20-inisection-option) + [isServerless](#jdbc20-isserverless-option) + [Issuer\$1Url](#jdbc20-issuer-url) + [Listen\$1Port](#jdbc20-listen-port) + [Login\$1URL](#jdbc20-login_url-option) + [loginTimeout](#jdbc20-logintimeout-option) + [loginToRp](#jdbc20-logintorp-option) + [LogLevel](#jdbc20-loglevel-option) + [LogPath](#jdbc20-logpath-option) + [OverrideSchemaPatternType](#jdbc20-override-schema-pattern-type) + [Partner\$1SPID](#jdbc20-partner_spid-option) + [密码](#jdbc20-password-option) + [Plugin\$1Name](#jdbc20-plugin_name-option) + [PORT](#jdbc20-port-option) + [Preferred\$1Role](#jdbc20-preferred_role-option) + [配置文件](#jdbc20-profile-option) + [PWD](#jdbc20-pwd-option) + [queryGroup](#jdbc20-querygroup-option) + [readOnly](#jdbc20-readonly-option) + [Region](#jdbc20-region-option) + [reWriteBatchedInserts](#jdbc20-rewritebatchedinserts-option) + [reWriteBatchedInsertsSize](#jdbc20-rewritebatchedinsertssize-option) + [roleArn](#jdbc20-rolearn-option) + [roleSessionName](#jdbc20-roleaessionname-option) + [范围](#jdbc20-scope-option) + [SecretAccessKey](#jdbc20-secretaccesskey-option) + [SessionToken](#jdbc20-sessiontoken-option) + [serverlessAcctId](#jdbc20-serverlessacctid-option) + [serverlessWorkGroup](#jdbc20-serverlessworkgroup-option) + [socketFactory](#jdbc20-socketfactory-option) + [socketTimeout](#jdbc20-sockettimeout-option) + [SSL](#jdbc20-ssl-option) + [SSL\$1Insecure](#jdbc20-ssl_insecure-option) + [SSLCert](#jdbc20-sslcert-option) + [SSLFactory](#jdbc20-sslfactory-option) + [SSLKey](#jdbc20-sslkey-option) + [SSLMode](#jdbc20-sslmode-option) + [SSLPassword](#jdbc20-sslpassword-option) + [SSLRootCert](#jdbc20-sslrootcert-option) + [StsEndpointUrl](#jdbc20-stsendpointurl-option) + [tcpKeepAlive](#jdbc20-tcpkeepalive-option) + [令牌](#jdbc20-token-option) + [token\$1type](#jdbc20-token-type-option) + [UID](#jdbc20-uid-option) + [用户](#jdbc20-user-option) + [webIdentityToken](#jdbc20-webidentitytoken-option) ## AccessKeyID + **默认值** – 无 + **数据类型** – 字符串 您可以指定此参数以输入用户或角色的 IAM 访问密钥。您通常可以通过查看现有的字符串或用户配置文件来查找密钥。如果您指定此参数，还必须指定 `SecretAccessKey` 参数。如果在 JDBC URL 中传递，则 AccessKeyID 必须采用 URL 编码。 此参数为可选的。 ## AllowDBUserOverride + **默认值** - 0 + **数据类型** – 字符串 此选项指定驱动程序是使用 SAML 断言中的 `DbUser` 值，还是连接 URL 的 `DbUser` 连接属性中指定的值。 此参数为可选的。 **1** 驱动程序使用 SAML 断言中的 `DbUser` 值。 如果 SAML 断言没有为 `DBUser` 指定值，则驱动程序将使用 `DBUser` 连接属性中指定的值。如果连接属性也没有指定值，则驱动程序将使用连接配置文件中指定的值。 **0** 驱动程序使用 `DBUser` 连接属性中指定的 `DBUser` 值。 如果 `DBUser` 连接属性没有指定值，则驱动程序将使用连接配置文件中指定的值。如果连接配置文件也没有指定值，则驱动程序将使用 SAML 断言中的值。 ## App\$1ID + **默认值** – 无 + **数据类型** – 字符串 Okta 提供的与您的 Amazon Redshift 应用程序关联的唯一 ID。 如果通过 Okta 服务进行身份验证，则此参数是必需的。 ## App\$1Name + **默认值** – 无 + **数据类型** – 字符串 您用于验证与 Amazon Redshift 的连接的 Okta 应用程序的名称。 此参数为可选的。 ## ApplicationName + **默认值** – null + **数据类型** – 字符串 传递给 Amazon Redshift 以供审计的应用程序的名称。 此参数为可选的。 ## AuthProfile + **默认值** – 无 + **数据类型** – 字符串 用于连接到 Amazon Redshift 的身份验证配置文件的名称。 此参数为可选的。 ## AutoCreate + **默认值** – false + **数据类型** – Boolean 此选项指定在指定用户不存在时驱动程序是否导致新用户被创建。 此参数为可选的。 **true** 如果通过 `DBUser` 或唯一 ID (UID) 指定的用户不存在，则会创建具有该名称的新用户。 **false** 驱动程序不会导致新用户被创建。如果指定的用户不存在，则身份验证将失败。 ## Client\$1ID + **默认值** – 无 + **数据类型** – 字符串 使用 Azure AD 服务对连接进行身份验证时使用的客户端 ID。 如果通过 Azure AD 服务进行身份验证，则此参数是必需的。 ## Client\$1Secret + **默认值** – 无 + **数据类型** – 字符串 使用 Azure AD 服务对连接进行身份验证时使用的客户端密钥。 如果通过 Azure AD 服务进行身份验证，则此参数是必需的。 ## ClusterID + **默认值** – 无 + **数据类型** – 字符串 要连接到的 Amazon Redshift 集群的名称。驱动程序将尝试从给定主机中检测此参数。如果您使用的是网络负载均衡器 (NLB) 并通过 IAM 进行连接，驱动程序将无法检测到它，因此您可以使用此连接选项进行设置。 此参数为可选的。 ## 压缩 + **默认值** – 关闭 + **数据类型** – 字符串 用于 Amazon Redshift 服务器与客户端或驱动程序之间线路协议通信的压缩方法。 此参数为可选的。 可以指定以下值： + **lz4** 将用于与 Amazon Redshift 通信的线路协议通信的压缩方法设置为 lz4。 + **off** 与 Amazon Redshift 通信的线路协议通信不使用压缩。 ## connectTimeout + **默认值** – 10 + **数据类型** – 整数 用于套接字连接操作的超时值。如果建立 Amazon Redshift 连接所需的时间超过此值，则系统将该连接视为不可用。超时以秒为单位指定。值为 0 表示未指定超时。 此参数为可选的。 ## connectionTimezone + **默认值** – LOCAL + **数据类型** – 字符串 会话级别的时区。 此参数为可选的。 可以指定以下值： **LOCAL** 将会话级别的时区配置为 LOCAL JVM 时区。 **SERVER** 将会话级别的时区配置为在 Amazon Redshift 服务器上为用户设置的时区。您可以使用以下命令为用户配置会话级别的时区： ``` ALTER USER [...] SET TIMEZONE TO [...]; ``` ## databaseMetadataCurrentDbOnly + **默认值** – true + **数据类型** – Boolean 此选项指定元数据 API 是从所有可访问的数据库中检索数据，还是仅从连接的数据库检索数据。 此参数为可选的。 可以指定以下值： **true** 应用程序从单个数据库中检索元数据。 **false** 应用程序从所有可访问的数据库中检索元数据。 ## DbUser + **默认值** – 无 + **数据类型** – 字符串 用于您的 Amazon Redshift 账户的用户 ID。如果您启用了 AutoCreate 属性，则可以使用当前不存在的 ID。 此参数为可选的。 ## DbGroups + **默认值** – PUBLIC + **数据类型** – 字符串 `DBUser` 为当前会话加入的现有数据库组名称的逗号分隔列表。 此参数为可选的。 ## DBNAME + **默认值** – null + **数据类型** – 字符串 要连接的数据库的名称。您可以使用此选项在 JDBC 连接 URL 中指定数据库名称。 此参数为必需参数。您必须在连接 URL 或客户端应用程序的连接属性中指定数据库名称。 ## defaultRowFetchSize + **默认值** - 0 + **数据类型** – 整数 此选项可指定 getFetchSize 的默认值。 此参数为可选的。 可以指定以下值： **0** 在单一操作中取回所有行。 **正整数** 对于 ResultSet 的每次取回迭代，要从数据库中取回的行数。 ## DisableIsValidQuery + **默认值** – False + **数据类型** – Boolean 此选项指定驱动程序在使用 Connection.isValid() 方法来确定数据库连接是否处于活动状态时是否提交新的数据库查询。 此参数为可选的。 **true** 驱动程序在使用 Connection.isValid() 方法来确定数据库连接是否处于活动状态时不提交查询。如果数据库服务器意外关闭，这可能会导致驱动程序错误地将数据库连接标识为活动状态。 **false** 驱动程序在使用 Connection.isValid() 方法来确定数据库连接是否处于活动状态时提交查询。 ## enableFetchRingBuffer + **默认值** – true + **数据类型** – Boolean 此选项指定驱动程序使用单独线程上的环形缓冲区取回行。fetchRingBufferSize 参数指定环形缓冲区的大小。 环形缓冲区在 JDBC 中实施自动内存管理，以防止在数据检索操作期间出现内存不足（OOM）错误。环形缓冲区实时监控缓冲数据的实际大小，确保驱动程序占用的内存总量不超过定义的限制。当缓冲区达到容量上限时，驱动程序会暂停数据提取操作，无需人工干预即可防止内存溢出。这项内置保护措施可以自动消除 OOM 错误，用户无需进行任何配置。 如果事务检测到包含多个 SQL 命令（以分号分隔）的语句，则该事务的提取环形缓冲区将设置为 false。enableFetchRingBuffer 的值不变。 此参数为可选的。 **注意** 当禁用环形缓冲区且提取大小配置不当时，可能会出现内存不足（OOM）问题。有关配置提取大小的更多信息，请参阅[此处](https://docs.aws.amazon.com/redshift/latest/dg/set-the-JDBC-fetch-size-parameter.html)。 ## enableMultiSqlSupport + **默认值** – true + **数据类型** – Boolean 此选项指定是否处理语句中以分号分隔的多个 SQL 命令。 此参数为可选的。 可以指定以下值： **true** 驱动程序处理语句对象中多个用分号分隔的 SQL 命令。 **false** 驱动程序为单个语句中的多个 SQL 命令返回错误。 ## fetchRingBufferSize + **默认值** – 1G + **数据类型** – 字符串 此选项指定在取回结果集时使用的环形缓冲区的大小。您可以指定以字节为单位的大小，例如 1K 表示 1 KB，5000 代表 5000 字节，1M 表示 1 MB，1G 表示 1 GB，依此类推。您还可以指定堆内存的百分比。驱动程序在达到限制时停止取回行。当应用程序读取行并释放环形缓冲区中的空间时，取回将恢复。 此参数为可选的。 ## ForceLlowcase + **默认值** – false + **数据类型** – Boolean 此选项指定在使用单点登录身份验证时，驱动程序是否会将从身份提供者发送到 Amazon Redshift 的所有数据库组 (DbGroup) 设为小写。 此参数为可选的。 **true** 驱动程序会小写从身份提供者发送的所有数据库组。 **false** 驱动程序不会更改数据库组。 ## groupFederation + **默认值** – false + **数据类型** – Boolean 此选项指定是否使用 Amazon Redshift IDP 组。此选项由 GetClusterCredentialsV2 API 支持。 此参数为可选的。 **true** 使用 Amazon Redshift 身份提供者 (IDP) 组。 **false** 使用 STS API 和 GetClusterCredentials 进行用户联合身份验证，并明确指定用于连接的 DbGroups。 ## HOST + **默认值** – null + **数据类型** – 字符串 要连接到 Amazon Redshift 服务器的主机名。您可以使用此选项在 JDBC 连接 URL 中指定主机名。 此参数为必需参数。您必须在连接 URL 或客户端应用程序的连接属性中指定主机名。 ## IAMDisableCache + **默认值** – false + **数据类型** – Boolean 此选项指定是否缓存 IAM 凭证。 此参数为可选的。 **true** IAM 凭证不会被缓存。 **false** IAM 凭证将被缓存。例如，当对 API 网关的请求受到限制时，这会提高性能。 ## IAMDuration + **默认值** – 900 + **数据类型** – 整数 临时 IAM 凭证过期之前的时间长度（以秒为单位）。 + **最小值** – 900 + **最大值 **– 3,600 此参数为可选的。 ## Idc\$1Client\$1Display\$1Name + **默认值** – Amazon Redshift JDBC 驱动程序 + **数据类型** – 字符串 要用于使用 BrowserIdcAuthPlugin 的客户端的显示名称。 此参数为可选的。 ## Idc\$1Region + **默认值** – 无 + **数据类型** – 字符串 IAM Identity Center 实例所在的 AWS 区域。 只有在 plugin\$1name 配置选项中使用 `BrowserIdcAuthPlugin` 进行身份验证时，才需要此参数。 ## IdP\$1Host + **默认值** – 无 + **数据类型** – 字符串 您用于对 Amazon Redshift 进行身份验证的 IdP（身份提供者）主机。该选项可以在连接字符串或配置文件中指定。 此参数为可选的。 ## IdP\$1Partition + **默认值** – 无 + **数据类型** – 字符串 指定在其中配置身份提供者（IdP）的云分区。这决定了驱动程序连接到哪个 IdP 身份验证端点。 如果将此参数留空，则驱动程序默认为商业分区。可能的值有： + `us-gov`：如果在 Azure Government 中配置了 IdP，请使用此值。例如，Azure AD Government 使用端点 `login.microsoftonline.us`。 + `cn`：如果在中国云分区中配置了 IdP，请使用此值。例如，Azure AD China 使用 `login.chinacloudapi.cn` 端点。 此参数为可选的。 ## IdP\$1Port + **默认值** – 无 + **数据类型** – 字符串 IdP（身份提供者）使用的端口。您可以在连接字符串或配置文件中指定端口。默认端口为 5439。根据您在创建、修改或迁移集群时选择的端口，允许访问所选端口。 此参数为可选的。 ## IdP\$1Tenant + **默认值** – 无 + **数据类型** – 字符串 适用于您的 Amazon Redshift 应用程序的 Azure AD 租户 ID。 如果通过 Azure AD 服务进行身份验证，则此参数是必需的。 ## IdP\$1Response\$1Timeout + **默认值** – 120 + **数据类型** – 整数 当通过浏览器插件使用 SAML 或 Azure AD 服务时，驱动程序等待身份提供者发出 SAML 响应的时间（以秒为单位）。 此参数为可选的。 ## IniFile + **默认值** – 无 + **数据类型** – 字符串 .ini 文件的完整路径，包括文件名。例如： ``` IniFile="C:\tools\rsjdbc.ini" ``` 有关 .ini 文件的信息，请参阅[为 JDBC 驱动程序版本 2.x 创建初始化 (.ini) 文件](jdbc20-ini-file.md)。 此参数为可选的。 ## IniSection + **默认值** – 无 + **数据类型** – 字符串 .ini 文件中包含配置选项的部分的名称。有关 .ini 文件的信息，请参阅[为 JDBC 驱动程序版本 2.x 创建初始化 (.ini) 文件](jdbc20-ini-file.md)。 以下示例指定 .ini 文件的 [Prod] 部分： ``` IniSection="Prod" ``` 此参数为可选的。 ## isServerless + **默认值** – false + **数据类型** – Boolean 此选项指定 Amazon Redshift 端点主机是否为无服务器实例。驱动程序将尝试从给定主机中检测此参数。如果您使用的是网络负载均衡器 (NLB)，则驱动程序将无法检测到它，因此您可以在此处对其进行设置。 此参数为可选的。 **true** Amazon Redshift 端点主机是一个无服务器实例。 **false** Amazon Redshift 端点主机是一个预置集群。 ## Issuer\$1Url + **默认值** – 无 + **数据类型** – 字符串 指向 AWS IAM Identity Center 服务器的实例端点。 只有在 plugin\$1name 配置选项中使用 `BrowserIdcAuthPlugin` 进行身份验证时，才需要此参数。 ## Listen\$1Port + **默认值**：7890 + **数据类型** – 整数 通过浏览器插件使用 SAML、Azure AD 或 AWS Identity Center 服务时，驱动程序用于接收来自身份提供者的 SAML 响应或授权代吗的端口。 此参数为可选的。 ## Login\$1URL + **默认值** – 无 + **数据类型** – 字符串 通过浏览器插件使用 SAML 或 Azure AD 服务时，身份提供者网站上的资源 URL。 如果通过浏览器插件使用 SAML 或 Azure AD 服务进行身份验证，则此参数是必需的。 ## loginTimeout + **默认值** - 0 + **数据类型** – 整数 连接服务器并对服务器进行身份验证时发生超时前等待的秒数。如果建立连接的用时长于此阈值，则连接将被中止。 当此属性设置为 0 时，连接不会发生超时。 此参数为可选的。 ## loginToRp + **默认值** – `urn:amazon:webservices` + **数据类型** – 字符串 要用于 AD FS 身份验证类型的信赖方信任。 此参数为可选的。 ## LogLevel + **默认值** - 0 + **数据类型** – 整数 使用此属性可以打开或关闭驱动程序中的日志记录并指定包含在日志文件中的详细信息量。 只有启用足够长的日志记录才能捕获问题。日志记录会降低性能，并会占用大量磁盘空间。 此参数为可选的。 将参数设置为以下值之一： **0** 禁用所有日志记录。 **1** 启用 FATAL 级别的日志记录，该级别日志记录将记录导致驱动程序中止的非常严重错误事件。 **2** 启用 ERROR 级别的日志记录，该级别日志记录将记录可能仍然允许驱动程序继续运行的错误事件。 **3** 启用 WARNING 级别的日志记录，该级别日志记录将记录在未执行操作时可能导致错误的事件。 **4** 启用 INFO 级别的日志记录，该级别日志记录将记录描述驱动程序进程的一般信息。 **5** 启用 DEBUG 级别的日志记录，该级别日志记录将记录对调试驱动程序很有用的详细信息。 **6** 启用 TRACE 级别的日志记录，该级别日志记录将记录所有驱动程序活动。 启用日志记录后，驱动程序会在 `LogPath` 属性指定的位置生成以下日志文件： + **`redshift_jdbc.log`**：记录不特定于连接的驱动程序活动的文件。 + **`redshift_jdbc_connection_[Number].log`** – 与数据库建立的每个连接的文件，其中 `[Number]` 是区分每个日志文件和其他日志文件的数字。此文件记录特定于连接的驱动程序活动。 如果 LogPath 值无效，则驱动程序将记录的信息发送到标准输出流 `System.out`。 ## LogPath + **默认值** – 当前工作目录。 + **数据类型** – 字符串 启用 DSILogLevel 属性时驱动程序保存日志文件所在的文件夹的完整路径。 为了确保连接 URL 与所有 JDBC 应用程序兼容，我们建议您通过键入另一个反斜杠来转义文件路径中的反斜杠 (\$1)。 此参数为可选的。 ## OverrideSchemaPatternType + **默认值** – null + **数据类型** – 整数 此选项指定是否覆盖在 getTables 调用中使用的查询类型。 **0** 无模式通用查询 **1** 本地模式查询 **2** 外部模式查询 此参数为可选的。 ## Partner\$1SPID + **默认值** – 无 + **数据类型** – 字符串 在使用 PingFederate 服务验证连接时使用的合作伙伴 SPID（服务提供商 ID）值。 此参数为可选的。 ## 密码 + **默认值** – 无 + **数据类型** – 字符串 使用 IAM 身份验证通过 IDP 进行连接时，它是 IDP\$1Host 服务器的密码。使用标准身份验证时，它可用于 Amazon Redshift 数据库密码，而不是 PWD。 此参数为可选的。 ## Plugin\$1Name + **默认值** – 无 + **数据类型** – 字符串 实施特定凭证提供程序插件的完全限定类名称。 此参数为可选的。 以下提供程序选项受支持： + **`AdfsCredentialsProvider`** – Active Directory 联合身份验证服务。 + **`AzureCredentialsProvider`** – Microsoft Azure Active Directory（AD）服务。 + **`BasicJwtCredentialsProvider`** – JSON Web Token（JWT）服务。 + **`BasicSamlCredentialsProvider`** – 您可以与许多 SAML 服务提供商一起使用的安全断言标记语言（SAML）凭据。 + **`BrowserAzureCredentialsProvider`** – 浏览器 Microsoft Azure Active Directory（AD）服务。 + ** `BrowserAzureOAuth2CredentialsProvider` **–用于本机身份验证的浏览器 Microsoft Azure Active Directory（AD）服务。 + **`BrowserIdcAuthPlugin`** – 使用 AWS IAM Identity Center 的授权插件。 + **`BrowserSamlCredentialsProvider`** – 用于 SAML 服务（如 Okta、Ping 或 ADFS）的浏览器 SAML。 + **`IdpTokenAuthPlugin`** – 一种授权插件，可接受 AWS IAM Identity Center 令牌，或者基于 OpenID Connect（OIDC）JSON 的身份令牌（JWT），该令牌由与 AWS IAM Identity Center 关联的任意 Web 身份提供者提供。 + **`OktaCredentialsProvider`** – Okta 服务。 + **`PingCredentialsProvider`** – PingFederate 服务。 ## PORT + **默认值** – null + **数据类型** – 整数 要连接到 Amazon Redshift 服务器的端口。您可以使用此选项在 JDBC 连接 URL 中指定端口。 此参数为可选的。 ## Preferred\$1Role + **默认值** – 无 + **数据类型** – 字符串 您希望在 Amazon Redshift 连接期间代入的 IAM 角色。 此参数为可选的。 ## 配置文件 + **默认值** – 无 + **数据类型** – 字符串 用于 IAM 身份验证的配置文件的名称。此配置文件包含未在连接字符串中指定的任何其他连接属性。 此参数为可选的。 ## PWD + **默认值** – 无 + **数据类型** – 字符串 与您使用属性 UID 提供的 Amazon Redshift 用户名相对应的密码。 此参数为可选的。 ## queryGroup + **默认值** – null + **数据类型** – 字符串 此选项通过将查询分配到相应的查询组在运行时向队列分配查询。将为会话设置查询组。在连接上运行的所有查询都属于此查询组。 此参数为可选的。 ## readOnly + **默认值** – false + **数据类型** – Boolean 此属性指定驱动程序是否处于只读模式。 此参数为可选的。 **true** 连接处于只读模式，无法写入数据存储。 **false** 连接不处于只读模式，可以写入数据存储。 ## Region + **默认值** – null + **数据类型** – 字符串 此选项指定集群所在的 AWS 区域。如果指定 StsEndPoint 选项，则会忽略“区域”选项。Redshift `GetClusterCredentials` API 操作也使用“区域”选项。 此参数为可选的。 ## reWriteBatchedInserts + **默认值** – false + **数据类型** – Boolean 通过此选项，可以优化批处理的兼容 INSERT 语句的重写和合并。 此参数为可选的。 ## reWriteBatchedInsertsSize + **默认值** – 128 + **数据类型** – 整数 通过此选项，可以优化批处理的兼容 INSERT 语句的重写和合并。此值必须以 2 为幂呈指数增加。 此参数为可选的。 ## roleArn + **默认值** – 无 + **数据类型** – 字符串 角色的 Amazon 资源名称（ARN）。在为 Plugin\$1Name 选项指定 BasicJwtCredentialsProvider 时，请确保指定此参数。采用以下格式指定 ARN： `arn:partition:service:region:account-id:resource-id` 如果您为 Plugin\$1Name 选项指定 BasicJwtCredentialsProvider，则此参数为必需项。 ## roleSessionName + **默认值** – jwt\$1redshift\$1session + **数据类型** – 字符串 所代入角色会话的标识符。通常，您可以传递与应用程序用户关联的名称或标识符。您的应用程序使用的临时安全凭证与该用户相关联。在为 Plugin\$1Name 选项指定 BasicJwtCredentialsProvider 时，您可以指定此参数。 此参数为可选的。 ## 范围 + **默认值** – 无 + **数据类型** – 字符串 用户可以同意的范围列表，以空格分隔。您可以指定此参数，以便 Microsoft Azure 应用程序可以获得您想调用的 API 的同意。在为 Plugin\$1Name 选项指定 BrowserAzureOAuth2CredentialsProvider 时，您可以指定此参数。 此参数是 BrowserAzureOAuth2CredentialsProvider 插件必需的。 ## SecretAccessKey + **默认值** – 无 + **数据类型** – 字符串 用户或角色的 IAM 访问密钥。如果指定了此选项，则还必须指定 AccessKeyID。如果在 JDBC URL 中传递，则 SecretAccessKey 必须采用 URL 编码。 此参数为可选的。 ## SessionToken + **默认值** – 无 + **数据类型** – 字符串 与您用于身份验证的 IAM 角色关联的临时 IAM 会话令牌。如果在 JDBC URL 中传递，则临时 IAM 会话令牌必须采用 URL 编码。 此参数为可选的。 ## serverlessAcctId + **默认值** – null + **数据类型** – 字符串 Amazon Redshift Serverless 账户 ID。驱动程序将尝试从给定主机中检测此参数。如果您使用的是网络负载均衡器 (NLB)，则驱动程序将无法检测到它，因此您可以在此处对其进行设置。 此参数为可选的。 ## serverlessWorkGroup + **默认值** – null + **数据类型** – 字符串 Amazon Redshift Serverless 工作组名称。驱动程序将尝试从给定主机中检测此参数。如果您使用的是网络负载均衡器 (NLB)，则驱动程序将无法检测到它，因此您可以在此处对其进行设置。 此参数为可选的。 ## socketFactory + **默认值** – null + **数据类型** – 字符串 此选项指定了用于创建套接字的套接字产生组件。 此参数为可选的。 ## socketTimeout + **默认值** - 0 + **数据类型** – 整数 套接字读取操作发生超时前等待的秒数。如果操作用时长于此阈值，则连接将被关闭。当此属性设置为 0 时，连接不会发生超时。 此参数为可选的。 ## SSL + **默认值** – TRUE + **数据类型** – 字符串 使用此属性可以打开或关闭连接的 SSL。 此参数为可选的。 可以指定以下值： **TRUE** 驱动程序通过 SSL 连接到服务器。 **FALSE** 驱动程序在不使用 SSL 的情况下连接到服务器。IAM 身份验证不支持此选项。 或者，您也可以配置 AuthMech 属性。 ## SSL\$1Insecure + **默认值** – true + **数据类型** – 字符串 此属性指示是否应验证 IDP 主机服务器证书。 此参数为可选的。 可以指定以下值： **true** 驱动程序不检查 IDP 服务器证书的真实性。 **false** 驱动程序检查 IDP 服务器证书的真实性。 ## SSLCert + **默认值** – 无 + **数据类型** – 字符串 .pem 或 .crt 文件的完整路径，其中包含在使用 SSL 时用于验证 Amazon Redshift 服务器实例的其他受信任 CA 证书。 如果指定了 SSLKey，则此参数为必填项。 ## SSLFactory + **默认值** – 无 + **数据类型** – 字符串 在不使用服务器证书的情况下，通过 TLS/SSL 连接到服务器时使用的 SSL 出厂设置。 ## SSLKey + **默认值** – 无 + **数据类型** – 字符串 .der 文件的完整路径，包含用于验证 SSLCert 中指定的证书的 PKCS8 密钥文件。 如果指定了 SSLCert，则此参数为必填项。 ## SSLMode + **默认值** – verify-ca + **数据类型** – 字符串 使用此属性指定启用 TLS/SSL 时驱动程序如何验证证书。 此参数为可选的。 可以指定以下值： **verify-ca** 驱动程序验证证书是否来自受信任的证书颁发机构 (CA)。 **verify-full** 驱动程序验证证书来自受信任的 CA，以及证书中的主机名是否与连接 URL 中指定的主机名匹配。 ## SSLPassword + **默认值** - 0 + **数据类型** – 字符串 在 SSLKey 中指定的加密密钥文件的密码。 如果指定了 SSLKey 且对密钥文件进行了加密，则此参数为必填项。 ## SSLRootCert + **默认值** – 无 + **数据类型** – 字符串 .pem 或 .crt 文件的完整路径，其中包含在使用 SSL 时用于验证 Amazon Redshift 服务器实例的根 CA 证书。 ## StsEndpointUrl + **默认值** – null + **数据类型** – 字符串 您可以指定 AWS Security Token Service (AWS STS) 端点。如果指定此选项，则“区域”选项将被忽略。您只能为此端点指定安全协议 (HTTPS)。 ## tcpKeepAlive + **默认值** – TRUE + **数据类型** – 字符串 使用此属性可打开或关闭 TCP Keepalive。 此参数为可选的。 可以指定以下值： **TRUE** 驱动程序将使用 TCP Keepalive 来防止连接超时。 **FALSE** 驱动程序不使用 TCP Keepalive。 ## 令牌 + **默认值** – 无 + **数据类型** – 字符串 AWS IAM Identity Center 提供的访问令牌，或 OpenID Connect（OIDC）JSON Web 令牌（JWT，JSON Web Token），该令牌由与 AWS IAM Identity Center 关联的 Web 身份提供者提供。您的应用程序必须通过 AWS IAM Identity Center 或与 AWS IAM Identity Center 关联的身份提供者，对您的应用程序用户进行身份验证，从而生成此令牌。 此参数可用于 `IdpTokenAuthPlugin`。 ## token\$1type + **默认值** – 无 + **数据类型** – 字符串 `IdpTokenAuthPlugin` 中使用的令牌类型。 可以指定以下值： **ACCESS\$1TOKEN** 如果您使用 AWS IAM Identity Center 提供的访问令牌，请输入此项。 **EXT\$1JWT** 如果您使用 OpenID Connect（OIDC）JSON Web 令牌（JWT）（该令牌由与 AWS IAM Identity Center 集成的基于 Web 的身份提供者提供），请输入此项。 此参数可用于 `IdpTokenAuthPlugin`。 ## UID + **默认值** – 无 + **数据类型** – 字符串 用于访问数据库的数据库用户名。 此参数为必需参数。 ## 用户 + **默认值** – 无 + **数据类型** – 字符串 通过 IDP 使用 IAM 身份验证进行连接时，这是 idp\$1host 服务器的用户名。使用标准身份验证时，这可用于 Amazon Redshift 数据库用户名。 此参数为可选的。 ## webIdentityToken + **默认值** – 无 + **数据类型** – 字符串 身份提供者提供的 OAuth 2.1 访问令牌或 OpenID Connect ID 令牌。您的应用程序必须通过 Web 身份提供者对您的应用程序用户进行身份验证来获取此令牌。在为 Plugin\$1Name 选项指定 BasicJwtCredentialsProvider 时，请确保指定此参数。 如果您为 Plugin\$1Name 选项指定 BasicJwtCredentialsProvider，则此参数为必填项。 # JDBC 驱动程序版本 2.x 的以前版本 仅当您的工具需要使用某个特定版本的驱动程序时，才能下载 Amazon Redshift JDBC 驱动程序版本 2.x 的以前版本。 以下是以前的与 JDBC 4.2 兼容的 JDBC 驱动程序版本 2.x 驱动程序： + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.4/redshift-jdbc42-2.2.4.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.4/redshift-jdbc42-2.2.4.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.3/redshift-jdbc42-2.2.3.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.3/redshift-jdbc42-2.2.3.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.2/redshift-jdbc42-2.2.2.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.2/redshift-jdbc42-2.2.2.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.1/redshift-jdbc42-2.2.1.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.1/redshift-jdbc42-2.2.1.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.0/redshift-jdbc42-2.2.0.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.0/redshift-jdbc42-2.2.0.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.34/redshift-jdbc42-2.1.0.34.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.34/redshift-jdbc42-2.1.0.34.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.33/redshift-jdbc42-2.1.0.33.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.33/redshift-jdbc42-2.1.0.33.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.32/redshift-jdbc42-2.1.0.32.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.32/redshift-jdbc42-2.1.0.32.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.30/redshift-jdbc42-2.1.0.30.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.30/redshift-jdbc42-2.1.0.30.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.29/redshift-jdbc42-2.1.0.29.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.29/redshift-jdbc42-2.1.0.29.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.28/redshift-jdbc42-2.1.0.28.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.28/redshift-jdbc42-2.1.0.28.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.26/redshift-jdbc42-2.1.0.26.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.26/redshift-jdbc42-2.1.0.26.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.25/redshift-jdbc42-2.1.0.25.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.25/redshift-jdbc42-2.1.0.25.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.24/redshift-jdbc42-2.1.0.24.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.24/redshift-jdbc42-2.1.0.24.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.23/redshift-jdbc42-2.1.0.23.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.23/redshift-jdbc42-2.1.0.23.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.22/redshift-jdbc42-2.1.0.22.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.22/redshift-jdbc42-2.1.0.22.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.21/redshift-jdbc42-2.1.0.21.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.21/redshift-jdbc42-2.1.0.21.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.20/redshift-jdbc42-2.1.0.20.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.20/redshift-jdbc42-2.1.0.20.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.19/redshift-jdbc42-2.1.0.19.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.19/redshift-jdbc42-2.1.0.19.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.18/redshift-jdbc42-2.1.0.18.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.18/redshift-jdbc42-2.1.0.18.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.17/redshift-jdbc42-2.1.0.17.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.17/redshift-jdbc42-2.1.0.17.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.16/redshift-jdbc42-2.1.0.16.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.16/redshift-jdbc42-2.1.0.16.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.15/redshift-jdbc42-2.1.0.15.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.15/redshift-jdbc42-2.1.0.15.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.14/redshift-jdbc42-2.1.0.14.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.14/redshift-jdbc42-2.1.0.14.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.13/redshift-jdbc42-2.1.0.13.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.13/redshift-jdbc42-2.1.0.13.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.12/redshift-jdbc42-2.1.0.12.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.12/redshift-jdbc42-2.1.0.12.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.11/redshift-jdbc42-2.1.0.11.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.11/redshift-jdbc42-2.1.0.11.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.10/redshift-jdbc42-2.1.0.10.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.10/redshift-jdbc42-2.1.0.10.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.9/redshift-jdbc42-2.1.0.9.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.9/redshift-jdbc42-2.1.0.9.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.8/redshift-jdbc42-2.1.0.8.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.8/redshift-jdbc42-2.1.0.8.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.7/redshift-jdbc42-2.1.0.7.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.7/redshift-jdbc42-2.1.0.7.zip) # Amazon Redshift Python 连接器 通过使用适用于 Python 的 Amazon Redshift 连接器，您可以将工作与[适用于 Python 的 AWS SDK（Boto3）](https://github.com/boto/boto3)以及 Pandas 和 Numerical Python（NumPy）集成。有关 pandas 的更多信息，请参阅 [pandas GitHub 存储库](https://github.com/pandas-dev/pandas)。有关 NumPy 的更多信息，请参阅 [NumPy GitHub 存储库](https://github.com/numpy/numpy)。 Amazon Redshift Python 连接器提供了一个开源解决方案。您可以浏览源代码、请求增强功能、报告问题和提供文章。 要使用 Amazon Redshift Python 连接器，请确保使用 Python 3.6 或更高版本。有关更多信息，请参阅[Amazon Redshift Python 驱动程序许可协议](https://github.com/aws/amazon-redshift-python-driver/blob/master/LICENSE)。 Amazon Redshift Python 连接器提供以下内容： + AWS Identity and Access Management（IAM）身份验证 有关更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](redshift-iam-authentication-access-control.md)。 + 使用联合 API 访问进行身份提供者身份验证 企业身份提供者支持联合 API 访问，如下所示： + Azure AD 有关更多信息，请参阅 AWS 大数据博客文章 [Federate Amazon Redshift access with Microsoft Azure AD single sign-on](https://aws.amazon.com/blogs/big-data/federate-amazon-redshift-access-with-microsoft-azure-ad-single-sign-on/)。 + Active Directory 联合身份验证服务 有关更多信息，请参阅 AWS 大数据博客文章 [Federate access to your Amazon Redshift cluster with Active Directory Federation Services (AD FS): Part 1](https://aws.amazon.com/blogs/big-data/federate-access-to-your-amazon-redshift-cluster-with-active-directory-federation-services-ad-fs-part-1/)。 + Okta。有关更多信息，有关更多信息，请参阅 AWS 大数据博客文章 [Federate Amazon Redshift access with Okta as an identity provider](https://aws.amazon.com/blogs/big-data/federate-amazon-redshift-access-with-okta-as-an-identity-provider/)。 + PingFederate。有关更多信息，请参阅 [PingFederate 站点](https://www.pingidentity.com/en/software/pingfederate.html)。 + JumpCloud。有关的更多信息，请参阅 [JumpCloud 站点](https://jumpcloud.com/)。 + Amazon Redshift 数据类型。 Amazon Redshift Python 连接器实施 Python 数据库 API 规范 2.0。有关更多信息，请参阅 Python 网站上的 [PEP 249 – Python 数据库 API 规范 v2.0](https://www.python.org/dev/peps/pep-0249/)。 **Topics** + [安装 Amazon Redshift Python 连接器](python-driver-install.md) + [Amazon Redshift Python 连接器的配置选项](python-configuration-options.md) + [导入 Python 连接器](python-start-import.md) + [将 Python 连接器与 NumPy 集成](python-connect-integrate-numpy.md) + [将 Python 连接器与 pandas 集成](python-connect-integrate-pandas.md) + [使用身份提供者插件](python-connect-identity-provider-plugins.md) + [使用 Amazon Redshift Python 连接器的示例](python-connect-examples.md) + [Amazon Redshift Python 连接器的 API 参考](python-api-reference.md) # 安装 Amazon Redshift Python 连接器 您可以使用以下任意一种方法安装 Amazon Redshift Python 连接器： + Python 包索引（PyPI） + Conda + 克隆 GitHub 存储库 ## 从 PyPI 安装 Python 连接器 要从 Python 包索引（PyPI）安装 Python 连接器，您可以使用 pip。要执行此操作，请运行以下命令。 ``` >>> pip install redshift_connector ``` 您可以在虚拟环境中安装连接器。要执行此操作，请运行以下命令。 ``` >>> pip install redshift_connector ``` 或者，你可以用连接器安装 pandas 和 NumPy。 ``` >>> pip install 'redshift_connector[full]' ``` 有关 pip 的更多信息，请参阅 [pip 站点](https://pip.pypa.io/en/stable/)。 ## 从 Conda 安装 Python 连接器 你可以从 Anaconda.org 安装 Python 连接器。 ``` >>>conda install -c conda-forge redshift_connector ``` ## 通过从 AWS 中克隆 GitHub 存储库来安装 Python 连接器 要从源代码安装 Python 连接器，请从 AWS 克隆 GitHub 存储库。安装 Python 和 virtualenv 之后，通过运行以下命令来设置环境并安装所需的依赖项。 ``` $ git clone https://github.com/aws/amazon-redshift-python-driver.git $ cd amazon-redshift-python-driver $ virtualenv venv $ . venv/bin/activate $ python -m pip install -r requirements.txt $ python -m pip install -e . $ python -m pip install redshift_connector ``` # Amazon Redshift Python 连接器的配置选项 下面，您可以找到您可以为 Amazon Redshift Python 连接器指定的选项的说明。除非另有说明，否则以下选项适用于最新的可用连接器版本。 ## access\$1key\$1id + **默认值** – 无 + **数据类型** – 字符串 为 IAM 数据库身份验证配置的 IAM 角色或用户的访问密钥 ID。 此参数为可选的。 ## allow\$1db\$1user\$1override + **默认值** – False + **数据类型** – Boolean True 指定连接器使用安全断言标记语言（SAML）断言中的 `DbUser` 值。 False 指定使用 `DbUser` 连接参数中的值。 此参数为可选的。 ## app\$1name + **默认值** – 无 + **数据类型** – 字符串 用于身份验证的身份提供者（IdP）应用程序的名称。 此参数为可选的。 ## application\$1name + **默认值** – 无 + **数据类型** – 字符串 传递给 Amazon Redshift 以供审计的客户端应用程序的名称。您提供的应用程序名称显示在 [SYS\$1CONNECTION\$1LOG](https://docs.aws.amazon.com/redshift/latest/dg/SYS_CONNECTION_LOG.html) 表的“application\$1name”列中。这有助于在调试问题时跟踪连接源并对其进行故障排除。 此参数为可选的。 ## auth\$1profile + **默认值** – 无 + **数据类型** – 字符串 连接属性为 JSON 的 Amazon Redshift 身份验证配置文件的名称。有关命名连接参数的更多信息，请参阅 `RedshiftProperty` 类。`RedshiftProperty` 类存储由最终用户提供的连接参数，如果适用，在 IAM 身份验证过程中生成（例如，临时 IAM 凭证）。有关更多信息，请参阅 [RedshiftProperty 类](https://github.com/aws/amazon-redshift-python-driver/blob/master/redshift_connector/redshift_property.py#L9)。 此参数为可选项。 ## auto\$1create + **默认值** – False + **数据类型** – Boolean 一个值，指示在用户不存在的情况下是否创建用户。 此参数为可选的。 ## client\$1id + **默认值** – 无 + **数据类型** – 字符串 Azure IdP 中的客户端 ID。 此参数为可选的。 ## client\$1secret + **默认值** – 无 + **数据类型** – 字符串 Azure IdP 中的客户端密钥。 此参数为可选的。 ## cluster\$1identifier + **默认值** – 无 + **数据类型** – 字符串 Amazon Redshift 集群的集群标识符。 此参数为可选的。 ## credentials\$1provider + **默认值** – 无 + **数据类型** – 字符串 对 Amazon Redshift 进行身份验证的 IdP。有效值如下所示： + `AdfsCredentialsProvider` + `AzureCredentialsProvider` + `BrowserAzureCredentialsProvider` + `BrowserAzureOAuth2CredentialsProvider` + `BrowserIdcAuthPlugin` – 使用 AWS IAM Identity Center 的授权插件。 + `BrowserSamlCredentialsProvider` + `IdpTokenAuthPlugin` – 一种授权插件，可接受 AWS IAM Identity Center 令牌，或者基于 OpenID Connect（OIDC）JSON 的身份令牌（JWT），该令牌由与 AWS IAM Identity Center 关联的任意 Web 身份提供者提供。 + `PingCredentialsProvider` + `OktaCredentialsProvider` 此参数为可选的。 ## database + **默认值** – 无 + **数据类型** – 字符串 要连接到的数据库的名称。 此参数为必需参数。 ## database\$1metadata\$1current\$1db\$1only + **默认值** – True + **数据类型** – Boolean 一个值，指示应用程序是否支持多数据库数据共享目录。默认值 True 表示应用程序不支持多数据库数据共享目录以实现向后兼容性。 此参数为可选的。 ## db\$1groups + **默认值** – 无 + **数据类型** – 字符串 DbUser 指示的用户为当前会话加入的现有数据库组名称的逗号分隔列表。 此参数为可选的。 ## db\$1user + **默认值** – 无 + **数据类型** – 字符串 用于 Amazon Redshift 的用户 ID。 此参数为可选的。 ## endpoint\$1url + **默认值** – 无 + **数据类型** – 字符串 Amazon Redshift 端点 URL。此选项仅供 AWS 内部使用。 此参数为可选的。 ## group\$1federation + **默认值** – False + **数据类型** – Boolean 此选项指定是否使用 Amazon Redshift IDP 组。 此参数为可选的。 **true** 使用 Amazon Redshift 身份提供者 (IDP) 组。 **false** 使用 STS API 和 GetClusterCredentials 进行用户联合身份验证，并指定用于连接的 **db\$1groups**。 ## host + **默认值** – 无 + **数据类型** – 字符串 Amazon Redshift 集群的主机名。 此参数为可选的。 ## IAM + **默认值** – False + **数据类型** – Boolean IAM 身份验证已启用。 此参数为必需参数。 ## iam\$1disable\$1cache + **默认值** – False + **数据类型** – Boolean 此选项指定是否缓存 IAM 凭证。IAM 凭证将默认被缓存。当对 API 网关的请求受到限制时，这样可以提高性能。 此参数为可选的。 ## idc\$1client\$1display\$1name + **默认值** – Amazon Redshift Python 连接器 + **数据类型** – 字符串 要用于使用 BrowserIdcAuthPlugin 的客户端的显示名称。 此参数为可选的。 ## idc\$1region + **默认值** – 无 + **数据类型** – 字符串 AWS IAM Identity Center 实例所在的 AWS 区域。 只有在 credentials\$1provider 配置选项中使用 `BrowserIdcAuthPlugin` 进行身份验证时，才需要此参数。 ## idp\$1partition + **默认值** – 无 + **数据类型** – 字符串 指定在其中配置身份提供者（IdP）的云分区。这决定了驱动程序连接到哪个 IdP 身份验证端点。 如果将此参数留空，则驱动程序默认为商业分区。可能的值有： + `us-gov`：如果在 Azure Government 中配置了 IdP，请使用此值。例如，Azure AD Government 使用端点 `login.microsoftonline.us`。 + `cn`：如果在中国云分区中配置了 IdP，请使用此值。例如，Azure AD China 使用 `login.chinacloudapi.cn` 端点。 此参数为可选的。 ## idpPort + **默认值** – 7890 + **数据类型** – 整数 IdP 将 SAML 断言发送到的侦听端口。 此参数为必需参数。 ## idp\$1response\$1timeout + **默认值** – 120 + **数据类型** – 整数 从 IdP 检索 SAML 断言的超时时间。 此参数为必需参数。 ## idp\$1tenant + **默认值** – 无 + **数据类型** – 字符串 IdP 租户。 此参数为可选的。 ## issuer\$1url + **默认值** – 无 + **数据类型** – 字符串 指向 AWS IAM Identity Center 服务器的实例端点。 只有在 credentials\$1provider 配置选项中使用 `BrowserIdcAuthPlugin` 进行身份验证时，才需要此参数。 ## listen\$1port + **默认值** – 7890 + **数据类型** – 整数 通过浏览器插件使用 SAML、Azure AD 或 AWS IAM Identity Center 服务时，驱动程序用于接收来自身份提供者的 SAML 响应的端口。 此参数为可选的。 ## login\$1url + **默认值** – 无 + **数据类型** – 字符串 IdP 的单点登录 Url。 此参数为可选的。 ## max\$1prepared\$1statements + **默认值**：1000 + **数据类型** – 整数 每个连接将缓存的最大预处理语句数。将该参数设置为 0 将禁用缓存机制。为此参数输入负数会将其设置为默认值。 此参数为可选的。 ## numeric\$1to\$1float + **默认值** – False + **数据类型** – Boolean 此选项指定连接器是否将数字数据类型值从 decimal.Decimal 转换为浮点数。默认情况下，连接器将数字数据类型值作为 decimal.Decimal 接收，而不会转换它们。 我们不建议为需要精确度的用例启用 numeric\$1to\$1float（数字转浮点），因为结果可能会四舍五入。 有关 decimal.Decimal 以及它与浮点数之间的权衡的更多信息，请参阅 Python 网站上的 [decimal — 十进制定点和浮点算术](https://docs.python.org/3/library/decimal.html)。 此参数为可选的。 ## partner\$1sp\$1id + **默认值** – 无 + **数据类型** – 字符串 用于 Ping 身份验证的合作伙伴 SP ID。 此参数为可选的。 ## password + **默认值** – 无 + **数据类型** – 字符串 用于身份验证的密码。 此参数为可选的。 ## port + **默认值** – 5439 + **数据类型** – 整数 Amazon Redshift 集群的端口号。 此参数为必需参数。 ## preferred\$1role + **默认值** – 无 + **数据类型** – 字符串 当前连接首选的 IAM 角色。 此参数为可选的。 ## principal\$1arn + **默认值** – 无 + **数据类型** – 字符串 要为其生成策略的用户或 IAM 角色的 Amazon 资源名称（ARN）。建议您将策略附加到角色，然后将该角色分配给用户以进行访问。 此参数为可选的。 ## 配置文件 + **默认值** – 无 + **数据类型** – 字符串 包含 AWS 凭据的 AWS 凭据文件中的配置文件的名称。 此参数为可选的。 ## provider\$1name + **默认值** – 无 + **数据类型** – 字符串 Redshift 本机验证提供程序的名称。 此参数为可选的。 ## region + **默认值** – 无 + **数据类型** – 字符串 集群所在的 AWS 区域。 此参数为可选的。 ## role\$1arn + **默认值** – 无 + **数据类型** – 字符串 调用方承担的角色的 Amazon 资源名称（ARN）。此参数由 `JwtCredentialsProvider` 指示的提供程序使用。 对于 `JwtCredentialsProvider` 提供商，此参数为必填项。否则，此参数位可选项。 ## role\$1session\$1name + **默认值** – jwt\$1redshift\$1session + **数据类型** – 字符串 所代入角色会话的标识符。通常，您可以传递与使用您的应用程序的用户关联的名称或标识符。您的应用程序使用的临时安全凭证与该用户相关联。此参数由 `JwtCredentialsProvider` 指示的提供程序使用。 此参数为可选的。 ## 范围 + **默认值** – 无 + **数据类型** – 字符串 用户可以同意的范围列表，以空格分隔。您可以指定此参数，以便应用程序可以获得您想调用的 API 的同意。在为 credentials\$1provider 选项指定 BrowserAzureOAuth2CredentialsProvider 时，您可以指定此参数。 此参数是 BrowserAzureOAuth2CredentialsProvider 插件必需的。 ## secret\$1access\$1key\$1id + **默认值** – 无 + **数据类型** – 字符串 为 IAM 数据库身份验证配置的 IAM 角色或用户的秘密访问密钥。 此参数为可选的。 ## session\$1token + **默认值** – 无 + **数据类型** – 字符串 为 IAM 数据库身份验证配置的 IAM 角色或用户的访问密钥 ID。如果使用临时 AWS 凭证，则需要此参数。 此参数为可选的。 ## serverless\$1acct\$1id + **默认值** – 无 + **数据类型** – 字符串 Amazon Redshift Serverless 账户 ID。 此参数为可选的。 ## serverless\$1work\$1group + **默认值** – 无 + **数据类型** – 字符串 Amazon Redshift Serverless 工作组名称。 此参数为可选的。 ## ssl + **默认值** – True + **数据类型** – Boolean 已启用安全套接字层（SSL） 此参数为必需参数。 ## ssl\$1insecure + **默认值** – False + **数据类型** – Boolean 指定是否禁用 IdP 主机的服务器 SSL 证书验证的值。将此参数设置为 True，将禁用对 IdP 主机的服务器 SSL 证书的验证。我们建议您在生产环境中保持默认值 False。 此参数为可选的。 ## sslmode + **默认值** – verify-ca + **数据类型** – 字符串 与 Amazon Redshift 的连接的安全性。您可以指定以下任一值： + verify-ca + verify-full 此参数为必需参数。 ## tcp\$1keepalive + **默认值** – True + **数据类型** – Boolean 是否使用 TCP keepalive 来防止连接超时。可以指定以下值： + True：驱动程序将使用 TCP keepalive 来防止连接超时。 + False：驱动程序不使用 TCP Keepalive。 此参数为可选的。 ## tcp\$1keepalive\$1count + **默认值** – 无 + **数据类型** – 整数 所发送的未确认探测器的数量，超过此数量后将连接视为不活动。例如，将该值设置为 3 意味着，驱动程序在发送了 3 个未回应的 keepalive 数据包之后，就会确定连接不再处于活动状态。 如果未指定此参数，Amazon Redshift 将使用系统默认值。 此参数为可选的。 ## tcp\$1keepalive\$1interval + **默认值** – 无 + **数据类型** – 整数 驱动程序在未收到上一个探测器的确认时，发送后续 keepalive 探测器时的间隔（以秒为单位）。指定此参数时，必须使用正整数。 如果未指定此参数，Amazon Redshift 将使用系统默认值。 此参数为可选的。 ## tcp\$1keepalive\$1idle + **默认值** – 无 + **数据类型** – 整数 不活动的持续时间（以秒为单位），驱动程序将在此时间之后发送第一个 keepalive 探测器。例如，将该值设置为 120 意味着，对于不活动状态，驱动程序将会等待 2 分钟，然后发送第一个 keepalive 数据包。指定此参数时，必须使用正整数。 如果未指定此参数，Amazon Redshift 将使用系统默认值。 此参数为可选的。 ## timeout + **默认值** – 无 + **数据类型** – 整数 连接服务器时发生超时前等待的秒数。 此参数为可选的。 ## 令牌 + **默认值** – 无 + **数据类型** – 字符串 AWS IAM Identity Center 提供的访问令牌，或 OpenID Connect（OIDC）JSON Web 令牌（JWT，JSON Web Token），该令牌由与 AWS IAM Identity Center 关联的 Web 身份提供者提供。您的应用程序必须通过 AWS IAM Identity Center 或与 AWS IAM Identity Center 关联的身份提供者，对您的应用程序用户进行身份验证，从而生成此令牌。 此参数可用于 `IdpTokenAuthPlugin`。 ## token\$1type + **默认值** – 无 + **数据类型** – 字符串 `IdpTokenAuthPlugin` 中使用的令牌类型。 可以指定以下值： **ACCESS\$1TOKEN** 如果您使用 AWS IAM Identity Center 提供的访问令牌，请输入此项。 **EXT\$1JWT** 如果您使用 OpenID Connect（OIDC）JSON Web 令牌（JWT）（该令牌由与 AWS IAM Identity Center 集成的基于 Web 的身份提供者提供），请输入此项。 此参数可用于 `IdpTokenAuthPlugin`。 ## 用户 + **默认值** – 无 + **数据类型** – 字符串 用于身份验证的用户名。 此参数为可选的。 ## web\$1identity\$1token + **默认值** – 无 + **数据类型** – 字符串 身份提供者提供的 OAuth 2.0 访问令牌或 OpenID Connect ID 令牌。通过使用 Web 身份提供者对使用您的应用程序的用户进行身份验证，确保您的应用程序获取此令牌。`JwtCredentialsProvider` 指示的提供商使用此参数。 对于 `JwtCredentialsProvider` 提供商，此参数为必填项。否则，此参数位可选项。 # 导入 Python 连接器 要导入 Python 连接器，请运行以下命令。 ``` >>> import redshift_connector ``` 要使用 AWS 凭证连接到 Amazon Redshift 集群，请运行以下命令。 ``` conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', port=5439, database='dev', user='awsuser', password='my_password' ) ``` # 将 Python 连接器与 NumPy 集成 以下是将 Python 连接器与 NumPy 集成的示例。 ``` >>> import numpy #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', port=5439, database='dev', user='awsuser', password='my_password' ) # Create a Cursor object >>> cursor = conn.cursor() # Query and receive result set cursor.execute("select * from book") result: numpy.ndarray = cursor.fetch_numpy_array() print(result) ``` 以下是结果。 ``` [['One Hundred Years of Solitude' 'Gabriel García Márquez'] ['A Brief History of Time' 'Stephen Hawking']] ``` # 将 Python 连接器与 pandas 集成 以下是将 Python 连接器与 pandas 集成的示例。 ``` >>> import pandas #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', port=5439, database='dev', user='awsuser', password='my_password' ) # Create a Cursor object >>> cursor = conn.cursor() # Query and receive result set cursor.execute("select * from book") result: pandas.DataFrame = cursor.fetch_dataframe() print(result) ``` # 使用身份提供者插件 有关如何使用身份提供者插件的一般信息，请参阅[用于提供 IAM 凭证的选项](options-for-providing-iam-credentials.md)。有关管理 IAM 身份的更多信息，包括 IAM 角色的最佳实践，请参阅 [Amazon Redshift 中的 Identity and Access Management](redshift-iam-authentication-access-control.md)。 ## 使用 ADFS 身份提供者插件进行身份验证 以下是使用 Active Directory 联合身份验证服务（ADFS）身份提供者插件对连接到 Amazon Redshift 数据库的用户进行身份验证的示例。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='AdfsCredentialsProvider', user='brooke@myadfshostname.com', password='Hunter2', idp_host='myadfshostname.com' ) ``` ## 使用 Azure 身份提供者插件进行身份验证 以下是使用 Azure 身份提供者插件进行身份验证的示例。您可以为 `client_id` 和 `client_secret` 创建值用于 Azure 企业应用程序，如下所示。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='AzureCredentialsProvider', user='brooke@myazure.org', password='Hunter2', idp_tenant='my_idp_tenant', client_id='my_client_id', client_secret='my_client_secret', preferred_role='arn:aws:iam:123:role/DataScientist' ) ``` ## 使用 AWS IAM Identity Center 身份提供者插件进行身份验证 以下是使用 AWS IAM Identity Center 身份提供者插件进行身份验证的示例。 ``` with redshift_connector.connect( credentials_provider='BrowserIdcAuthPlugin', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', database='dev', idc_region='us-east-1', issuer_url='https://identitycenter.amazonaws.com/ssoins-790723ebe09c86f9', idp_response_timeout=60, listen_port=8100, idc_client_display_name='Test Display Name', # port value of 5439 is specified by default ) ``` ## 使用 Azure 浏览器身份提供者插件进行身份验证 以下是使用 Azure 浏览器身份提供者插件对连接到 Amazon Redshift 数据库的用户进行身份验证的示例。 浏览器中会发生多重身份验证，其中登录凭证由用户提供。 ``` >>>con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='BrowserAzureCredentialsProvider', idp_tenant='my_idp_tenant', client_id='my_client_id', ) ``` ## 使用 Okta 身份提供者插件进行身份验证 以下是使用 Okta 身份提供者插件进行身份验证的示例。你可以通过 Okta 应用程序获取 `idp_host`、`app_id` 和 `app_name` 的值。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='OktaCredentialsProvider', user='brooke@myazure.org', password='hunter2', idp_host='my_idp_host', app_id='my_first_appetizer', app_name='dinner_party' ) ``` ## 使用 JumpCloud 和通用 SAML 浏览器身份提供者插件进行身份验证 以下是使用 JumpCloud 和通用 SAML 浏览器身份提供者插件进行身份验证的示例。 密码参数是必需的。但是，您不必输入此参数，因为浏览器中会发生多重验证。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='BrowserSamlCredentialsProvider', user='brooke@myjumpcloud.org', password='', login_url='https://sso.jumpcloud.com/saml2/plustwo_melody' ) ``` # 使用 Amazon Redshift Python 连接器的示例 以下为如何使用 Amazon Redshift Python 连接器的示例。要运行它们，您必须先安装 Python 连接器。有关安装 Amazon Redshift Python 连接器的更多信息，请参阅[安装 Amazon Redshift Python 连接器](python-driver-install.md)。有关可以与 Python 连接器一起使用的配置选项的更多信息，请参阅 [Amazon Redshift Python 连接器的配置选项](python-configuration-options.md)。 **Topics** + [使用 AWS 凭证连接到 Amazon Redshift 集群并进行查询](#python-connect-cluster) + [启用自动提交](#python-connect-enable-autocommit) + [配置游标参数样式](#python-connect-config-paramstyle) + [使用 COPY 从 Amazon S3 桶中复制数据，然后使用 UNLOAD 将数据写入该桶](#python-connect-copy-unload-s3) ## 使用 AWS 凭证连接到 Amazon Redshift 集群并进行查询 下面的示例将指导您使用 AWS 凭证连接到 Amazon Redshift 集群，然后查询表并检索查询结果。 ``` #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', database='dev', port=5439, user='awsuser', password='my_password' ) # Create a Cursor object >>> cursor = conn.cursor() # Query a table using the Cursor >>> cursor.execute("select * from book") #Retrieve the query result set >>> result: tuple = cursor.fetchall() >>> print(result) >> (['One Hundred Years of Solitude', 'Gabriel García Márquez'], ['A Brief History of Time', 'Stephen Hawking']) ``` ## 启用自动提交 根据 Python 数据库 API 规范，默认情况下自动提交属性处于关闭状态。在执行回滚命令后，您可以使用以下命令打开连接的 autocommit 属性，以确保事务不在进行中。 ``` #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect(...) # Run a rollback command >>> conn.rollback() # Turn on autocommit >>> conn.autocommit = True >>> conn.run("VACUUM") # Turn off autocommit >>> conn.autocommit = False ``` ## 配置游标参数样式 可以通过 cursor.paramstyle 修改游标的参数样式。使用的原定设置参数样式是 `format`。参数样式的有效值为 `qmark`、`numeric`、`named`、`format` 和 `pyformat`。 以下是使用各种参数样式将参数传递给示例 SQL 语句的示例。 ``` # qmark redshift_connector.paramstyle = 'qmark' sql = 'insert into foo(bar, jar) VALUES(?, ?)' cursor.execute(sql, (1, "hello world")) # numeric redshift_connector.paramstyle = 'numeric' sql = 'insert into foo(bar, jar) VALUES(:1, :2)' cursor.execute(sql, (1, "hello world")) # named redshift_connector.paramstyle = 'named' sql = 'insert into foo(bar, jar) VALUES(:p1, :p2)' cursor.execute(sql, {"p1":1, "p2":"hello world"}) # format redshift_connector.paramstyle = 'format' sql = 'insert into foo(bar, jar) VALUES(%s, %s)' cursor.execute(sql, (1, "hello world")) # pyformat redshift_connector.paramstyle = 'pyformat' sql = 'insert into foo(bar, jar) VALUES(%(bar)s, %(jar)s)' cursor.execute(sql, {"bar": 1, "jar": "hello world"}) ``` ## 使用 COPY 从 Amazon S3 桶中复制数据，然后使用 UNLOAD 将数据写入该桶 以下示例说明如何将数据从 Amazon S3 桶复制到表中，然后从该表卸载回到此桶中。 包含以下数据的名为 `category_csv.txt` 的文本文件将上载到 Amazon S3 桶中。 ``` 12,Shows,Musicals,Musical theatre 13,Shows,Plays,"All ""non-musical"" theatre" 14,Shows,Opera,"All opera, light, and ""rock"" opera" 15,Concerts,Classical,"All symphony, concerto, and choir concerts" ``` 以下是 Python 代码的示例，该代码首先连接到 Amazon Redshift 数据库。然后创建一个名为 `category` 的表并将 S3 桶中的 CSV 数据复制到表中。 ``` #Connect to the cluster and create a Cursor >>> import redshift_connector >>> with redshift_connector.connect(...) as conn: >>> with conn.cursor() as cursor: #Create an empty table >>> cursor.execute("create table category (catid int, cargroup varchar, catname varchar, catdesc varchar)") #Use COPY to copy the contents of the S3 bucket into the empty table >>> cursor.execute("copy category from 's3://testing/category_csv.txt' iam_role 'arn:aws:iam::123:role/RedshiftCopyUnload' csv;") #Retrieve the contents of the table >>> cursor.execute("select * from category") >>> print(cursor.fetchall()) #Use UNLOAD to copy the contents of the table into the S3 bucket >>> cursor.execute("unload ('select * from category') to 's3://testing/unloaded_category_csv.txt' iam_role 'arn:aws:iam::123:role/RedshiftCopyUnload' csv;") #Retrieve the contents of the bucket >>> print(cursor.fetchall()) >> ([12, 'Shows', 'Musicals', 'Musical theatre'], [13, 'Shows', 'Plays', 'All "non-musical" theatre'], [14, 'Shows', 'Opera', 'All opera, light, and "rock" opera'], [15, 'Concerts', 'Classical', 'All symphony, concerto, and choir concerts']) ``` 如果您未将 `autocommit` 设置为 true，请在运行 `execute()` 语句后使用 `conn.commit()` 提交。 数据卸载到 S3 桶的 `unloaded_category_csv.text0000_part00` 文件中，内容如下： ``` 12,Shows,Musicals,Musical theatre 13,Shows,Plays,"All ""non-musical"" theatre" 14,Shows,Opera,"All opera, light, and ""rock"" opera" 15,Concerts,Classical,"All symphony, concerto, and choir concerts" ``` # Amazon Redshift Python 连接器的 API 参考 您可以在文中找到有关 Amazon Redshift Python 连接器 API 操作的说明。 ## redshift\$1connector 在下文中，您可以找到有关 `redshift_connector` API 操作的描述。 `connect(user, database, password[, port, …])` 创建到 Amazon Redshift 集群的连接。此函数可验证用户输入，可以选择使用身份提供者插件进行身份验证，然后构造连接对象。 `apilevel` 支持的 DBAPI 级别，目前为“2.0”。 `paramstyle``str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str` 要在全局使用的数据库 API 参数样式。 ## 连接 您可以在文中找到有关 Amazon Redshift Python 连接器的连接 API 操作的说明。 `__init__(user, password, database[, host, …])` 初始化原始连接对象。 `cursor` 创建绑定到此连接的游标对象。 `commit` 提交当前数据库事务。 `rollback` 回滚当前的数据库事务。 `close` 关闭数据库连接。 `execute(cursor, operation, vals)` 运行指定的 SQL 命令。您可以将参数作为序列或映射提供，具体取决于 `redshift_connector.paramstyle` 的值。 `run(sql[, stream])` 运行指定的 SQL 命令。或者，您也可以提供与 COPY 命令一起使用的流。 `xid(format_id, global_transaction_id, …)` 创建事务 ID。postgres 中只使用了 `global_transaction_id` 参数。postgres 中不使用 format\$1id 和 branch\$1qualifier。`global_transaction_id` 可以是 postgres 支持的任何返回元组的字符串标识符（`format_id`、`global_transaction_id`、`branch_qualifier`）。 `tpc_begin(xid)` 使用由格式 ID、全局事务 ID 和分支限定符组成的事务 ID `xid` 开始 TPC 事务。 `tpc_prepare` 执行以 .tpc\$1begin 开始的事务的第一阶段。 `tpc_commit([xid])` 在没有参数的情况下进行调用时，.tpc\$1commit 会提交之前使用 .tpc\$1prepare() 准备的 TPC 事务。 `tpc_rollback([xid])` 在没有参数的情况下进行调用时，.tpc\$1rollback 会回滚 TPC 事务。 `tpc_recover` 返回适合与 .tpc\$1commit(xid) 或 .tpc\$1rollback(xid) 一起使用的待处理事务 ID 列表。 ## Cursor 在下文中，您可以找到有关 游标 API 操作的描述。 `__init__(connection[, paramstyle])` 初始化原始游标对象。 `insert_data_bulk(filename, table_name, parameter_indices, column_names, delimiter, batch_size)` 运行批量 INSERT 语句。 `execute(operation[, args, stream, …])` 运行数据库操作。 `executemany(operation, param_sets)` 准备数据库操作，然后为提供的所有参数序列或映射运行该操作。 `fetchone` 获取查询结果集的下一行。 `fetchmany([num])` 获取查询结果的下一个行集。 `fetchall` 获取查询结果的所有剩余行。 `close` 立即关闭光标。 `__iter__` 可以迭代游标对象以从查询中检索行。 `fetch_dataframe([num])` 返回最后查询结果的数据框。 `write_dataframe(df, table)` 将相同的结构数据框写入 Amazon Redshift 数据库。 `fetch_numpy_array([num])` 返回最后查询结果的 NumPy 数组。 `get_catalogs` Amazon Redshift 不支持来自单个连接的多个目录。Amazon Redshift 只返回当前目录。 `get_tables([catalog, schema_pattern, …])` 返回系统中用户定义的唯一公共表。 `get_columns([catalog, schema_pattern, …])` 返回 Amazon Redshift 数据库中特定表中所有列的列表。 ## AdfsCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 AdfsCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.AdfsCredentialsProvider() ``` ## AzureCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 AzureCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.AzureCredentialsProvider() ``` ## BrowserAzureCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 BrowserAzureCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.BrowserAzureCredentialsProvider() ``` ## BrowserSamlCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 BrowserSamlCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.BrowserSamlCredentialsProvider() ``` ## OktaCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 OktaCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.OktaCredentialsProvider() ``` ## PingCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 PingCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.PingCredentialsProvider() ``` ## SamlCredentialsProvider 插件 以下是 Amazon Redshift Python 连接器的 SamlCredentialsProvider 插件 API 操作的语法。 ``` redshift_connector.plugin.SamlCredentialsProvider() ``` # 适用于 Apache Spark 的 Amazon Redshift 集成 [Apache Spark](https://aws.amazon.com/emr/features/spark/) 是一个分布式处理框架和编程模型，可帮助您进行机器学习、流处理或图形分析。Spark 与 Apache Hadoop 类似，也是一款常用于大数据工作负载的开源、分布式处理系统。Spark 具有优化的有向无环图（DAG）执行引擎，可主动在内存中缓存数据。这可以提高性能，特别适合某些算法和交互式查询。 此集成为您提供了 Spark 连接器，您可以将其用于构建 Apache Spark 应用程序，这些应用程序在 Amazon Redshift 和 Amazon Redshift Serverless 中读取和写入数据。这些应用程序不会影响应用程序性能或数据的事务一致性。此集成自动包括在 [Amazon EMR](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/) 和 [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/) 中，因此您可以立即运行 Apache Spark 作业，在数据摄取和转换管道过程中访问数据并将其加载到 Amazon Redshift 中。 目前，可以使用 Spark 的 3.3.x、3.4.x、3.5.x 和 4.0.0 版本进行此集成。 此集成提供以下内容： + AWS Identity and Access Management（IAM）身份验证 有关更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。 + 利用谓词和查询下推来提高性能。 + Amazon Redshift 数据类型。 + 与 Amazon Redshift 和 Amazon Redshift Serverless 的连接。 ## 使用 Spark 连接器时的注意事项和限制 + tempdir URI 指向 Amazon S3 位置。此临时目录不会自动清理，可能会增加额外的成本。我们建议使用《Amazon Simple Storage Service 用户指南》**中的 [Amazon S3 生命周期策略](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，定义 Amazon S3 存储桶的保留规则。 + 原定设置情况下，如果 S3 桶和 Redshift 集群位于不同的 AWS 区域，则 Amazon S3 和 Redshift 之间的复制不起作用。要使用单独的 AWS 区域，请将 `tempdir_region` 参数设置为对 `tempdir` 使用的 S3 存储桶的区域。 + 如果使用 `tempformat` 参数写入 Parquet 数据，则在 S3 和 Redshift 之间进行跨区域写入。 + 我们建议使用 [Amazon S3 服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)以加密使用的 Amazon S3 存储桶。 + 我们建议[阻止对 Amazon S3 存储桶的公有访问](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html)。 + 我们建议不要公开访问 Amazon Redshift 集群。 + 我们建议启用 [Amazon Redshift 审核日志记录](https://docs.aws.amazon.com/redshift/latest/mgmt/db-auditing.html)。 + 我们建议启用 [Amazon Redshift 静态加密](https://docs.aws.amazon.com/redshift/latest/mgmt/security-server-side-encryption.html)。 + 我们建议您为从 Spark on Amazon EMR 到 Amazon Redshift 的 JDBC 连接启用 SSL。 + 我们建议使用参数 `aws_iam_role` 为 Amazon Redshift 身份验证参数传递 IAM 角色。 # 使用 Spark 连接器进行身份验证 下图描述了 Amazon S3、Amazon Redshift、Spark 驱动程序和 Spark 执行程序之间的身份验证。 ![\[这是 Spark 连接器身份验证的示意图。\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/images/spark-connector-authentication.png) ## Redshift 和 Spark 之间的身份验证 您可以使用 Amazon Redshift 提供的 JDBC 驱动程序版本 2.x 驱动程序，通过指定登录凭证，使用 Spark 连接器连接到 Amazon Redshift。要使用 IAM，[请将您的 JDBC url 配置为使用 IAM 身份验证](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-iam-credentials-configure-jdbc-odbc.html)。要从 Amazon EMR 或 AWS Glue 连接到 Redshift 集群，确保您的 IAM 角色具有检索临时 IAM 凭证所必需的权限。以下列表描述了您的 IAM 角色检索凭证和运行 Amazon S3 操作所需的所有权限。 + [ Redshift:GetClusterCredentials](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentials.html)（适用于预置的 Redshift 集群） + [ Redshift:DescribeClusters](https://docs.aws.amazon.com/redshift/latest/APIReference/API_DescribeClusters.html)（适用于预置的 Redshift 集群） + [Redshift:GetWorkgroup](https://docs.aws.amazon.com/redshift-serverless/latest/APIReference/API_GetWorkgroup.html)（适用于 Amazon Redshift Serverless 工作组） + [ Redshift:GetCredentials](https://docs.aws.amazon.com/redshift-serverless/latest/APIReference/API_GetCredentials.html)（适用于 Amazon Redshift Serverless 工作组） + [s3:ListBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) + [ s3:GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetBucket.html) + [ s3:GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) + [ s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) + [ s3:GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycleConfiguration.html) 有关 GetClusterCredentials 的更多信息，请参阅 [GetClusterCredentials 的 IAM 策略](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-identity-based.html#redshift-policy-resources.getclustercredentials-resources)。 您还必须确保 Amazon Redshift 可以在 `COPY` 和 `UNLOAD` 操作期间担任 IAM 角色。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "redshift.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 如果您使用的是最新的 JDBC 驱动程序，则驱动程序将自动管理从 Amazon Redshift 自签名证书到 ACM 证书的转换。但是，您必须[为 JDBC url 指定 SSL 选项](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-configuration-options.html#jdbc20-ssl-option)。 以下是有关如何指定 JDBC 驱动程序 URL 和 `aws_iam_role` 以连接到 Amazon Redshift 的示例。 ``` df.write \ .format("io.github.spark_redshift_community.spark.redshift ") \ .option("url", "jdbc:redshift:iam://") \ .option("dbtable", "") \ .option("tempdir", "s3a:///") \ .option("aws_iam_role", "") \ .mode("error") \ .save() ``` ## Amazon S3 和 Spark 之间的身份验证 如果您使用 IAM 角色在 Spark 和 Amazon S3 之间进行身份验证，则使用以下方法之一： + AWS SDK for Java 会自动尝试使用由 DefaultAWSCredentialsProviderChain 类实施的默认凭证提供程序链来查找 AWS 凭证。有关更多信息，请参阅[使用默认凭证提供程序链](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default)。 + 您可以通过 [Hadoop 配置属性](https://github.com/apache/hadoop/blob/trunk/hadoop-tools/hadoop-aws/src/site/markdown/tools/hadoop-aws/index.md)指定 AWS 密钥。例如，如果您的 `tempdir` 配置指向 `s3n://` 文件系统，请在 Hadoop XML 配置文件中设置 `fs.s3n.awsAccessKeyId` 和 `fs.s3n.awsSecretAccessKey` 属性或调用 `sc.hadoopConfiguration.set()` 以更改 Spark 的全局 Hadoop 配置。 例如，如果您使用的是 s3n 文件系统，则添加： ``` sc.hadoopConfiguration.set("fs.s3n.awsAccessKeyId", "YOUR_KEY_ID") sc.hadoopConfiguration.set("fs.s3n.awsSecretAccessKey", "YOUR_SECRET_ACCESS_KEY") ``` 对于 s3a 文件系统，请添加： ``` sc.hadoopConfiguration.set("fs.s3a.access.key", "YOUR_KEY_ID") sc.hadoopConfiguration.set("fs.s3a.secret.key", "YOUR_SECRET_ACCESS_KEY") ``` 如果您使用的是 Python，则使用以下操作： ``` sc._jsc.hadoopConfiguration().set("fs.s3n.awsAccessKeyId", "YOUR_KEY_ID") sc._jsc.hadoopConfiguration().set("fs.s3n.awsSecretAccessKey", "YOUR_SECRET_ACCESS_KEY") ``` + 在 `tempdir` URL 中对身份验证密钥进行编码。例如，URI `s3n://ACCESSKEY:SECRETKEY@bucket/path/to/temp/dir` 对密钥对（`ACCESSKEY`，`SECRETKEY`）进行编码。 ## Redshift 和 Amazon S3 之间的身份验证 如果您在查询中使用 COPY 和 UNLOAD 命令，则还必须向 Amazon S3 授予访问 Amazon Redshift 的权限，这样才能代表您运行查询。为此，请先[授权 Amazon Redshift 访问其他 AWS 服务](https://docs.aws.amazon.com/redshift/latest/mgmt/authorizing-redshift-service.html)，然后[使用 IAM 角色授权 COPY 和 UNLOAD 操作](https://docs.aws.amazon.com/redshift/latest/mgmt/copy-unload-iam-role.html)。 作为最佳实践，我们建议将权限策略附加到 IAM 角色，然后根据需要将其分配给用户和组。有关更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。 ## 与 AWS Secrets Manager 集成 您可以从 AWS Secrets Manager 中存储的密钥检索您的 Redshift 用户名和密码凭证。要自动提供 Redshift 凭证，请使用 `secret.id` 参数。有关如何创建 Redshift 凭证密钥的更多信息，请参阅[创建 AWS Secrets Manager 数据库密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/redshift-spark-connector-authentication.html) **注意** 致谢：本文档包含 [Apache Software Foundation](http://www.apache.org/) 根据 [Apache 2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0)的许可而开发的示例代码和语言。 # 通过下推提高性能 Spark 连接器自动应用谓词和查询下推来优化性能。有了这种支持就意味着，如果您在查询中使用支持的函数，Spark 连接器会将该函数转换成 SQL 查询，并在 Amazon Redshift 中运行该查询。这种优化会减少需要检索的数据，因此 Apache Spark 可以处理更少的数据并获得更好的性能。默认情况下，自动激活下推。要停用它，请将 `autopushdown` 设置为 false。 ``` import sqlContext.implicits._val sample= sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url",jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "event") .option("autopushdown", "false") .load() ``` 下推支持以下函数。如果您使用不在此列表中的函数，Spark 连接器将在 Spark 中（而不是在 Amazon Redshift 中）执行此函数，从而导致性能未优化。有关 Spark 中函数的完整列表，请参阅[内置函数](https://spark.apache.org/docs/latest/api/sql/index.html)。 + 聚合函数 + avg + count + max + min + sum + stddev\$1samp + stddev\$1pop + var\$1samp + var\$1pop + 布尔运算符 + in + isnull + isnotnull + contains + endswith + startswith + 逻辑运算符 + and + or + not (or \$1) + 数学函数 + \$1 + - + \$1 + / + - (unary) + abs + acos + asin + atan + ceil + cos + EXP + floor + greatest + least + log10 + pi + pow + round + sin + sqrt + tan + 其他函数 + cast + coalesce + decimal + if + in + 关系运算符 + \$1= + = + > + >= + < + <= + 字符串函数 + ascii + lpad + rpad + 翻译 + upper + lower + length + trim + ltrim + rtrim + like + substring + concat + 日期和时间函数 + add\$1months + date + date\$1add + date\$1sub + date\$1trunc + timestamp + trunc + 数学运算 + CheckOverflow + PromotePrecision + 关系运算 + Aliases（例如，AS） + CaseWhen + Distinct + InSet + 联接和交叉联接 + Limits + Unions，union all + ScalarSubquery + Sorts（升序和降序） + UnscaledValue # 其他配置选项 在本页中，您可以找到可为 Amazon Redshift Spark 连接器指定的选项的说明。 ## 字符串列的最大大小 Redshift 在创建表时将字符串列创建为文本列，它们存储为 VARCHAR(256)。如果您想要支持更大大小的列，则可以使用 maxlength 来指定字符串列的最大长度。下面是说明如何指定 `maxlength` 的示例。 ``` columnLengthMap.foreach { case (colName, length) => val metadata = new MetadataBuilder().putLong("maxlength", length).build() df = df.withColumn(colName, df(colName).as(colName, metadata)) } ``` ## 列类型 要设置列类型，请使用 `redshift_type` 字段。 ``` columnTypeMap.foreach { case (colName, colType) => val metadata = new MetadataBuilder().putString("redshift_type", colType).build() df = df.withColumn(colName, df(colName).as(colName, metadata)) } ``` ## 列上的压缩编码 要对列使用特定的压缩编码，请使用编码字段。有关支持的压缩编码的完整列表，请参阅[压缩编码](https://docs.aws.amazon.com/redshift/latest/dg/c_Compression_encodings.html)。 ## 列的描述 要设置描述，请使用 `description` 字段。 ## Redshift 和 Amazon S3 之间的身份验证 默认情况下，结果将以 Parquet 格式转存到 Amazon S3。要以竖线分隔的文本文件转存结果，请指定以下选项。 ``` .option("unload_s3_format", "TEXT") ``` ## 下推语句 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/spark-redshift-connector-other-config.html) ## 连接器参数 Spark SQL 中的参数映射或 `OPTIONS` 支持以下设置。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/spark-redshift-connector-other-config.html) **注意** 致谢：本文档包含 [Apache Software Foundation](http://www.apache.org/) 根据 [Apache 2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0)的许可而开发的示例代码和语言。 # 支持的数据类型 Spark 连接器支持 Amazon Redshift 中的以下数据类型。有关 Amazon Redshift 中支持的数据类型的完整列表，请参阅[数据类型](https://docs.aws.amazon.com//redshift/latest/dg/c_Supported_data_types.html)。如果某个数据类型不在下表中，则 Spark 连接器不支持该数据类型。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/spark-redshift-connector-data-types.html) ## 复杂的数据类型 您可以使用 spark 连接器在 Redshift SUPER 数据类型列中读写 Spark 复杂数据类型，如 `ArrayType`、`MapType` 和 `StructType`。如果您在读取操作期间提供架构，则该列中的数据将在 Spark 中转换为相应的复杂类型，包括任何嵌套类型。此外，如果启用 `autopushdown`，嵌套属性、映射值和数组索引的投影将下推到 Redshift，这样，当只访问一部分数据时，就不再需要卸载整个嵌套数据结构。 从连接器写入 DataFrame 时，任何类型为 `MapType`（使用 `StringType`）、`StructType` 或 `ArrayType` 的列都会写入 Redshift SUPER 数据类型列。在写入这些嵌套数据结构时，`tempformat` 参数必须为类型 `CSV`、`CSV GZIP` 或 `PARQUET`。使用 `AVRO` 将导致异常。写入一个键类型不是 `StringType` 的 `MapType` 数据结构也会导致异常。 ### StructType 以下示例演示如何使用包含结构的 SUPER 数据类型创建表 ``` create table contains_super (a super); ``` 然后，您可以使用连接器，使用下面示例中的类似架构，从表中的 SUPER 列 `a` 查询 `StringType` 字段 `hello`。 ``` import org.apache.spark.sql.types._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", StructType(StructField("hello", StringType) ::Nil)) :: Nil) val helloDF = sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url", jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "contains_super") .schema(schema) .load().selectExpr("a.hello") ``` 以下示例演示如何向列 `a` 写入结构。 ``` import org.apache.spark.sql.types._ import org.apache.spark.sql._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", StructType(StructField("hello", StringType) ::Nil)) :: Nil) val data = sc.parallelize(Seq(Row(Row("world")))) val mydf = sqlContext.createDataFrame(data, schema) mydf.write.format("io.github.spark_redshift_community.spark.redshift"). option("url", jdbcUrl). option("dbtable", tableName). option("tempdir", tempS3Dir). option("tempformat", "CSV"). mode(SaveMode.Append).save ``` ### MapType 如果您更喜欢使用 `MapType` 来表示数据，那么您可以在架构中使用 `MapType` 数据结构，并检索映射中与键对应的值。请注意，`MapType` 数据结构中的所有键都必须是 String 类型，并且所有值都必须是相同的类型，例如 int。 以下示例演示如何获取列 `a` 中键 `hello` 的值。 ``` import org.apache.spark.sql.types._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", MapType(StringType, IntegerType))::Nil) val helloDF = sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url", jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "contains_super") .schema(schema) .load().selectExpr("a['hello']") ``` ### ArrayType 如果该列包含数组而不是结构，则可以使用连接器查询数组中的第一个元素。 ``` import org.apache.spark.sql.types._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", ArrayType(IntegerType)):: Nil) val helloDF = sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url", jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "contains_super") .schema(schema) .load().selectExpr("a[0]") ``` ### 限制 通过 spark 连接器使用复杂数据类型有以下限制： + 所有嵌套的结构字段名称和映射键必须为小写。如果查询带有大写字母的复杂字段名称，可以尝试省略架构，并使用 `from_json` spark 函数在本地转换返回的字符串来作为解决方法。 + 在读取或写入操作中使用的任何映射字段都必须只有 `StringType` 键。 + 只有 `CSV`、`CSV GZIP` 和 `PARQUET ` 是支持将复杂类型写入 Redshift 的临时格式值。尝试使用 `AVRO ` 会引发异常。 # 为 Amazon Redshift 配置 ODBC 驱动程序版本 2.x 连接 您可以使用 ODBC 连接将许多第三方 SQL 客户端工具和应用程序连接到您的 Amazon Redshift 集群。如果您的客户端工具支持 JDBC，您可以选择使用 JDBC 类型的连接，而非 ODBC 连接，因为 JDBC 连接更加易于配置。但是，如果您的客户端工具不支持 JDBC，您可以按照本节中的步骤在您的客户端计算机或 Amazon EC2 实例上设置 ODBC 连接。 Amazon Redshift 提供了适用于 Linux、Windows 和 Mac 操作系统的 64 位 ODBC 驱动程序；32 位 ODBC 驱动程序已停用。除了紧急安全补丁外，不会发布针对 32 位 ODBC 驱动程序的进一步更新。 有关 ODBC 驱动程序更改的最新信息，请参阅[更改日志](https://github.com/aws/amazon-redshift-odbc-driver/blob/master/CHANGELOG.md)。 **Topics** + [获取 ODBC URL](odbc20-getting-url.md) + [在 Microsoft Windows 上使用 Amazon Redshift ODBC 驱动程序](odbc20-install-config-win.md) + [在 Linux 上使用 Amazon Redshift ODBC 驱动程序](odbc20-install-config-linux.md) + [在 Apple macOS 上使用 Amazon Redshift ODBC 驱动程序](odbc20-install-config-mac.md) + [身份验证方法](odbc20-authentication-ssl.md) + [数据类型转换](odbc20-converting-data-types.md) + [ODBC 驱动程序选项](odbc20-configuration-options.md) + [早期 ODBC 驱动程序版本](odbc20-previous-versions.md) # 获取 ODBC URL Amazon Redshift 在 Amazon Redshift 控制台中显示您的集群的 ODBC URL。此 URL 包含在您的客户端计算机与数据库之间建立连接所需的信息。 ODBC URL 采用以下格式： ``` Driver={driver}; Server=endpoint_host; Database=database_name; UID=user_name; PWD=password; Port=port_number ``` 上述格式的字段具有以下值： | Field | Value | | --- | --- | | Driver | 要使用的 64 位 ODBC 驱动程序的名称：Amazon Redshift ODBC 驱动程序(x64) | | Server | Amazon Redshift 集群的端点主机。 | | Database | 您为集群创建的数据库。 | | UID | 有权连接到数据库的数据库用户账户的用户名。虽然此值是数据库级权限，而非集群级权限，但您可以使用您在启动集群时设置的 Redshift 管理员用户账户。 | | PWD | 数据库用户账户用于连接数据库的密码。 | | Port | 您在启动集群时指定的端口号。如果您启用了防火墙，请确保此端口处于打开状态，可供您使用。 | 以下是一个示例 ODBC URL： ``` Driver={Amazon Redshift ODBC Driver (x64)}; Server=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com; Database=dev; UID=adminuser; PWD=insert_your_admin_user_password_here; Port=5439 ``` 有关在何处查找 ODBC URL 的信息，请参阅[查找集群连接字符串](https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html#connecting-connection-string)。 # 在 Microsoft Windows 上使用 Amazon Redshift ODBC 驱动程序 您必须在可访问 Amazon Redshift 数据仓库的客户端计算机上安装 Amazon Redshift ODBC 驱动程序。对于您要在其上安装该驱动程序的每台计算机，有以下最低要求： + 计算机上的管理员权限。 + 计算机满足以下系统要求： + 以下操作系统之一： + Windows 10 或 8.1。 + Windows Server 2019、2016 或 2012。 + 100MB 可用磁盘空间。 + 已安装适用于 64 位 Windows 的 Visual C\$1\$1 Redistributable for Visual Studio 2015。您可以在 Microsoft 网站上的[下载 Visual C\$1\$1 Redistributable for Visual Studio 2022](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022) 下载安装包。 # 下载并安装 Amazon Redshift ODBC 驱动程序 使用以下过程下载并安装适用于 Windows 操作系统的 Amazon Redshift ODBC 驱动程序。仅在您当前运行的第三方应用程序获得了使用 Amazon Redshift 的认证并且需要不同驱动程序时，才能使用该特定驱动程序。 要下载并安装 ODBC 驱动程序，请执行以下操作： 1. 下载以下驱动程序：[64 位 ODBC 驱动程序版本 2.1.15.0](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC64-2.1.15.0.msi) 此驱动程序的名称为 **Amazon Redshift ODBC 驱动程序(x64)**。 1. 审核 [Amazon Redshift ODBC 驱动程序版本 2.x 许可证](https://github.com/aws/amazon-redshift-odbc-driver/blob/master/LICENSE)。 1. 双击 .msi 文件，然后按照向导中的步骤安装驱动程序。 # 为 ODBC 连接创建系统 DSN 条目 下载并安装 ODBC 驱动程序后，将数据来源名称 (DSN) 条目添加到客户端计算机或 Amazon EC2 实例。SQL 客户端工具可以使用此数据来源连接到 Amazon Redshift 数据库。 建议您创建系统 DSN 而不是用户 DSN。有些应用程序使用不同的数据库用户账户加载数据，因而可能无法检测在其他数据库用户账户下创建的用户 DSN。 **注意** 对于使用 AWS Identity and Access Management (IAM) 凭证或身份提供者 (IdP) 凭证进行的身份验证，需要执行其他步骤。有关更多信息，请参阅[配置 JDBC 或 ODBC 连接以使用 IAM 凭证](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-iam-credentials-configure-jdbc-odbc.html)。 要为 ODBC 连接创建系统 DSN 条目，请执行以下操作： 1. 在**开始**菜单上，键入“ODBC 数据来源”。选择 **ODBC 数据来源**。 请确保您选择的 ODBC Data Source Administrator 的位数与用于连接 Amazon Redshift 的客户端应用程序的位数相同。 1. 在 **ODBC 数据来源管理器**中，选择**驱动程序**选项卡，然后找到以下驱动程序文件夹：**Amazon Redshift ODBC 驱动程序(x64)**。 1. 选择**系统 DSN** 选项卡为计算机上的所有用户配置驱动程序，或选择**用户 DSN** 选项卡仅为您的数据库用户账户配置驱动程序。 1. 选择**添加**。系统随即打开 **Create New Data Source** 窗口。 1. 选择 **Amazon Redshift ODBC 驱动程序(x64)**，然后选择**完成**。系统随即打开 ** Amazon Redshift ODBC Driver DSN Setup** 窗口。 1. 在**连接设置**部分下，输入以下信息： + **Data source name** 输入数据来源的名称。例如，如果您遵循的是《Amazon Redshift 入门指南》**，则可键入 `exampleclusterdsn`，以便轻松记住将与此 DSN 关联的集群。 + **服务器** 为您的 Amazon Redshift 集群指定端点主机。您可以在 Amazon Redshift 控制台中的集群详细信息页面上找到该信息。有关更多信息，请参阅[在 Amazon Redshift 中配置连接](https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html)。 + **端口** 输入数据库使用的端口号。根据您在创建、修改或迁移集群时选择的端口，允许访问所选端口。 + **数据库** 输入 Amazon Redshift 数据库的名称。如果您在未指定数据库名称的情况下启动了集群，请输入 `dev`。否则，请使用您在启动过程中选择的名称。如果您遵循的是《Amazon Redshift 入门指南》**，输入 `dev`。 1. 在**身份验证**下，指定配置选项以配置标准或 IAM 身份验证。 1. 选择**SSL 选项**，然后指定以下项目的值： + **身份验证模式** 选择处理安全套接字层 (SSL) 的模式。在测试环境中，可以使用 `prefer`。但是，对于生产环境以及在需要安全交换数据时，请使用 `verify-ca` 或 `verify-full`。 + **最低 TLS** （可选）选择驱动程序允许数据存储用来对连接进行加密的最低 TLS/SSL 版本。例如，如果您指定了 TLS 1.2，则无法使用 TLS 1.1 对连接进行加密。默认版本为 TLS 1.2。 1. 在**代理**选项卡中，指定任何代理连接设置。 1. 在**游标**选项卡中，指定有关如何将查询结果返回至您的 SQL 客户端工具或应用程序的选项。 1. 在**高级选项**中，指定 `logLevel`、`logPath`、`compression` 和其他选项的值。 1. 选择**测试**。如果客户端计算机可以连接到 Amazon Redshift 数据库，将显示以下消息：**连接成功**。如果客户端计算机无法连接到数据库，您可以通过生成日志文件并联系 AWS 支持部门，对可能的问题进行故障排除。有关生成日志的信息，请参阅 (LINK)。 1. 选择**确定**。 # 在 Linux 上使用 Amazon Redshift ODBC 驱动程序 您必须在可访问 Amazon Redshift 数据仓库的客户端计算机上安装 Amazon Redshift ODBC 驱动程序。对于您要在其上安装该驱动程序的每台计算机，有以下最低要求： + 计算机上的根访问权限。 + 以下分发之一： + Red Hat® Enterprise Linux®（RHEL）8 或更高版本 + CentOS 8 或更高版本。 + 150MB 可用磁盘空间。 + unixODBC 2.2.14 或更高版本。 + glibc 2.26 或更高版本。 # 下载并安装 Amazon Redshift ODBC 驱动程序 要下载并安装适用于 Linux 的 Amazon Redshift ODBC 驱动程序版本 2.x，请执行以下操作： 1. 下载以下驱动程序： + [x86 64 位 RPM 驱动程序版本 2.1.15.0](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC-64-bit-2.1.15.0.x86_64.rpm)。 + [ARM 64 位 RPM 驱动程序版本 2.1.15.0](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC-64-bit-2.1.15.0.aarch64.rpm)。 **注意** 32 位 ODBC 驱动程序已停用。除了紧急安全补丁外，不会发布进一步的更新。 1. 转至您下载程序包的位置，然后运行以下命令之一。使用适用于您的 Linux 发行版的命令。 在 RHEL 和 CentOS 操作系统上，运行以下命令： ``` yum --nogpgcheck localinstall RPMFileName ``` 将 `RPMFileName` 替换为 RPM 包文件名。例如，以下命令将演示如何安装 64 位驱动程序： ``` yum --nogpgcheck localinstall AmazonRedshiftODBC-64-bit-2.x.xx.xxxx.x86_64.rpm ``` # 使用 ODBC 驱动程序管理器配置 ODBC 驱动程序 在 Linux 上，您可以使用 ODBC 驱动程序管理器来配置 ODBC 连接设置。ODBC 驱动程序管理器使用配置文件来定义和配置 ODBC 数据来源和驱动程序。您可以使用的 ODBC 驱动程序管理器取决于您使用的操作系统。 ## 使用 unixODBC 驱动程序管理器配置 ODBC 驱动程序 要配置 Amazon Redshift ODBC 驱动程序，需要以下文件： + ` amazon.redshiftodbc.ini ` + ` odbc.ini ` + ` odbcinst.ini ` 如果您将驱动程序安装在默认位置，则 `amazon.redshiftodbc.ini` 配置文件将位于 `/opt/amazon/redshiftodbcx64` 中。 此外，在 `/opt/amazon/redshiftodbcx64` 下，您可以找到示例 `odbc.ini` 和 `odbcinst.ini` 文件。您可以使用这些文件作为配置 Amazon Redshift ODBC 驱动程序和数据来源名称 (DSN) 的示例。 我们不建议使用 Amazon Redshift ODBC 驱动程序安装目录来存储配置文件。安装目录中的示例文件仅用作示例。如果您日后重新安装 Amazon Redshift ODBC 驱动程序，或将其升级到新版本，安装目录会被覆盖。您将丢失对安装目录中的文件所做的所有更改。 为了避免出现这种情况，请将 `amazon.redshiftodbc.ini` 文件复制到安装目录以外的其他目录中。如果您要将此文件复制到用户的主目录，请在文件名的开头添加一个句点 (.)，使其成为隐藏文件。 对于 `odbc.ini` 和 `odbcinst.ini` 文件，应在用户的主目录中使用配置文件，或者在其他目录中创建新版本。默认情况下，您的 Linux 操作系统应在用户的主目录（`/home/$USER` 或 `~/.`）中包含 `odbc.ini` 文件和 `odbcinst.ini` 文件。这些默认文件均为隐藏文件（通过在每个文件名的前面添加圆点 (.) 表示）。这些文件仅当您使用 `-a` 标志列出目录内容时显示。 对于 `odbc.ini` 和 `odbcinst.ini` 文件，不管您选择哪个选项，都需对这些文件进行修改，以添加驱动程序和 DSN 配置信息。如果您创建新文件，则还需设置环境变量，以指定这些配置文件的目标存储位置。 默认情况下，ODBC 驱动程序管理器将配置为使用位于主目录中的 `odbc.ini` 和 `odbcinst.ini` 配置文件的隐藏版本（名为 `.odbc.ini` 和 `.odbcinst.ini`）。它们也被配置为使用驱动程序安装目录中的 `amazon.redshiftodbc.ini` 文件。如果您将这些配置文件存储在其他位置，请设置如下所述的环境变量，以便驱动程序管理器能够找到这些文件。 如果您使用的是 unixODBC，请执行以下操作： + 将 `ODBCINI` 设置到 `odbc.ini` 文件的完整路径和文件名。 + 将 `ODBCSYSINI` 设置到包含 `odbcinst.ini` 文件的目录的完整路径。 + 将 `AMAZONREDSHIFTODBCINI` 设置到 `amazon.redshiftodbc.ini` 文件的完整路径和文件名。 以下是设置上述值的示例： ``` export ODBCINI=/usr/local/odbc/odbc.ini export ODBCSYSINI=/usr/local/odbc export AMAZONREDSHIFTODBCINI=/etc/amazon.redshiftodbc.ini ``` ## 在 Linux 上使用数据来源名称 (DSN) 配置连接 在使用数据来源名称 (DSN) 连接到数据存储时，请配置 `odbc.ini` 文件以定义数据来源名称 (DSN)。在 `odbc.ini` 文件中设置属性以创建指定数据存储的连接信息的 DSN。 在 Linux 操作系统上，使用以下格式： ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/driver_file Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下示例显示了在 Linux 操作系统上使用 64 位 ODBC 驱动程序配置 `odbc.ini`。 ``` [ODBC Data Sources] Amazon_Redshift_x64=Amazon Redshift ODBC Driver (x64) [Amazon_Redshift_x64] Driver=/opt/amazon/redshiftodbcx64/librsodbc64.so Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932Database=dev locale=en-US ``` ## 在 Linux 上配置没有 DSN 的连接 要通过不带 DSN 的连接来连接到数据存储，请在 `odbcinst.ini` 文件中定义驱动程序。然后，在应用程序中提供一个无 DSN 的连接字符串。 在 Linux 操作系统上，使用以下格式： ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/driver_file ... ``` 以下示例显示了在 Linux 操作系统上使用 64 位 ODBC 驱动程序配置 `odbcinst.ini`。 ``` [ODBC Drivers] Amazon Redshift ODBC Driver (x64)=Installed [Amazon Redshift ODBC Driver (x64)] Description=Amazon Redshift ODBC Driver (64-bit) Driver=/opt/amazon/redshiftodbcx64/librsodbc64.so ``` # 在 Apple macOS 上使用 Amazon Redshift ODBC 驱动程序 您必须在可访问 Amazon Redshift 数据仓库的客户端计算机上安装 Amazon Redshift ODBC 驱动程序。对于您要安装该驱动程序的每台计算机，有以下最低要求： + 计算机上的根访问权限。 + Apple macOS 系统要求： + 需要 64 位版本的 Apple macOS 版本 11.7 或更高版本（例如，Apple macOS Big Sur、Monterey、Ventura 或更高版本）。Redshift ODBC 驱动程序仅支持 64 位客户端应用程序。 + 150MB 可用磁盘空间。 + 该驱动程序支持使用 iODBC 3.52.9\$1 或 unixODBC 2.3.7\$1 构建的应用程序。 # 下载并安装 Amazon Redshift ODBC 驱动程序 使用以下过程在 Apple macOS 上下载并安装 Amazon Redshift ODBC 驱动程序。仅在您当前运行的第三方应用程序获得了使用 Amazon Redshift 的认证并且需要不同驱动程序时，才能使用该特定驱动程序。 要下载并安装 ODBC 驱动程序，请执行以下操作： 1. 下载以下驱动程序：[64 位 ODBC 驱动程序版本 2.1.15.0](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC-64-bit.2.1.15.0.universal.pkg) x86\$164 和 arm64 架构都支持该驱动程序。此驱动程序的名称为 **Amazon Redshift ODBC 驱动程序(x64)**。 1. 审核 [Amazon Redshift ODBC 驱动程序版本 2.x 许可证](https://github.com/aws/amazon-redshift-odbc-driver/blob/master/LICENSE)。 1. 双击 .pkg 文件，然后按照向导中的步骤操作来安装该驱动程序。或者，运行以下命令： ``` sudo installer -pkg PKGFileName -target / ``` 将 `PKGFileName` 替换为 pkg 包文件名。例如，以下命令将演示如何安装 64 位驱动程序： ``` sudo installer -pkg ./AmazonRedshiftODBC-64-bit.X.X.XX.X.universal.pkg -target / ``` # 使用 ODBC 驱动程序管理器配置 ODBC 驱动程序 在 Mac 上，您可以使用 ODBC 驱动程序管理器来配置 ODBC 连接设置。ODBC 驱动程序管理器使用配置文件来定义和配置 ODBC 数据来源和驱动程序。您可以使用的 ODBC 驱动程序管理器取决于您使用的操作系统。 ## 使用 iODBC 或 unixODBC 驱动程序管理器配置 ODBC 驱动程序 要配置 Amazon Redshift ODBC 驱动程序，需要以下文件： + ` amazon.redshiftodbc.ini ` + ` odbc.ini ` + ` odbcinst.ini ` 如果您将驱动程序安装在默认位置，则 `amazon.redshiftodbc.ini` 配置文件将位于 `/opt/amazon/redshiftodbcx64` 中。 此外，在 `/opt/amazon/redshiftodbcx64` 下，您可以找到示例 `odbc.ini` 和 `odbcinst.ini` 文件。您可以使用这些文件作为配置 Amazon Redshift ODBC 驱动程序和数据来源名称 (DSN) 的示例。安装目录中的示例文件仅用作示例。 我们不建议使用 Amazon Redshift ODBC 驱动程序安装目录来存储配置文件。如果您日后重新安装 Amazon Redshift ODBC 驱动程序，或将其升级到新版本，安装目录会被覆盖。您将丢失对安装目录中的文件所做的所有更改。 为了避免出现这种情况，请将 `odbc.ini`、`odbcinst.ini` 和 `amazon.redshiftodbc.ini` 文件复制到安装目录以外的其他目录中。如果您要将这些文件复制到用户的主目录，请在这些文件名的开头添加一个句点（.），使其成为隐藏文件。 修改文件以添加 DSN 配置信息。在创建新文件时，还需设置环境变量，以指定这些配置文件的目标存储位置。 以下示例演示如何设置环境变量： ``` export ODBCINI=/Library/ODBC/odbc.ini export ODBCSYSINI=/Library/ODBC export ODBCINSTINI=${ODBCSYSINI}/odbcinst.ini ``` 对于命令行应用程序：将导出命令添加到 Shell 启动文件（例如，`~/.bash_profile` 或 `~/.zshrc`）中。 有关支持的驱动程序管理器版本，请参阅[此处](https://docs.aws.amazon.com/redshift/latest/mgmt/odbc20-install-config-mac.html) ### 在 Apple macOS 上使用数据来源名称（DSN）配置连接 在使用数据来源名称 (DSN) 连接到数据存储时，请配置 `odbc.ini` 文件以定义数据来源名称 (DSN)。在 `odbc.ini` 文件中设置属性以创建一个 DSN，来指定 Redshift 数据仓库的连接信息。 在 Apple macOS 上，使用以下格式： ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/driver_file Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下示例展示了在 Apple macOS 上使用 64 位 ODBC 驱动程序配置 `odbc.ini`。 ``` [ODBC Data Sources] Amazon_Redshift_x64=Amazon Redshift ODBC Driver (x64) [Amazon_Redshift_x64] Driver=/opt/amazon/redshiftodbcx64/librsodbc64.dylib Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` ### 在 Apple macOS 上配置没有 DSN 的连接 要通过不带 DSN 的连接来连接到 Redshift 数据仓库，请在 `odbcinst.ini` 文件中定义驱动程序。然后，在应用程序中提供一个无 DSN 的连接字符串。 在 Apple macOS 上，使用以下格式： ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/driver_file ... ``` 以下示例展示了在 Apple macOS 上使用 64 位 ODBC 驱动程序配置 `odbcinst.ini`。 ``` [ODBC Drivers] Amazon Redshift ODBC Driver (x64)=Installed [Amazon Redshift ODBC Driver (x64)] Description=Amazon Redshift ODBC Driver (64-bit) Driver=/opt/amazon/redshiftodbcx64/librsodbc64.dylib ``` # 身份验证方法 为了防止数据遭到未经授权的访问，Amazon Redshift 数据存储要求所有连接都使用用户凭据进行身份验证。 下表说明了可用于连接到 Amazon Redshift ODBC 驱动程序版本 2.x 的每种身份验证方法的必需和可选连接选项： | 身份验证方法 | 必需 | 可选 | | --- | --- | --- | | 标准 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | | | IAM 配置文件 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | IAM 凭证 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | AD FS | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | Azure AD | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | JWT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | | Okta | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | Ping Federate | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | 浏览器 Azure AD | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | 浏览器 SAML | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | 身份验证配置文件 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | | | 浏览器 Azure AD OAUTH2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果没有单独设置 **ClusterID** 和**区域**，则必须在**主机**中设置它们。 | | AWS IAM Identity Center | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/odbc20-authentication-ssl.html) | ## 使用外部凭证服务 除了对 AD FS、Azure AD 和 Okta 的内置支持外，Amazon Redshift ODBC 驱动程序的 Windows 版本还提供了对其他凭证服务的支持。该驱动程序可以使用您选择的任何基于 SAML 的凭证提供程序插件对连接进行身份验证。 要在 Windows 上配置外部凭证服务，请执行以下操作： 1. 创建一个 IAM 配置文件，根据需要指定凭证提供程序插件和其他身份验证参数。配置文件必须采用 ASCII 编码，并且必须包含以下键值对，其中 `PluginPath` 是插件应用程序的完整路径： ``` plugin_name = PluginPath ``` 例如： ``` plugin_name = C:\Users\kjson\myapp\CredServiceApp.exe ``` 有关如何创建配置文件的信息，请参阅《Amazon Redshift 集群管理指南》中的[使用配置文件](https://docs.aws.amazon.com/redshift/latest/mgmt/options-for-providing-iam-credentials.html#using-configuration-profile)。 1. 将驱动程序配置为使用此配置文件。驱动程序将检测并使用配置文件中指定的身份验证设置。 # 数据类型转换 Amazon Redshift ODBC 驱动程序版本 2.x 支持许多常见的数据格式，从而可在 Amazon Redshift 和 SQL 数据类型之间进行转换。 下表列出了支持的数据类型映射。 | Amazon Redshift 类型 | SQL 类型 | | --- | --- | | BIGINT | SQL\$1BIGINT | | BOOLEAN | SQL\$1BIT | | CHAR | SQL\$1CHAR | | DATE | SQL\$1TYPE\$1DATE | | DECIMAL | SQL\$1NUMERIC | | DOUBLE PRECISION | SQL\$1DOUBLE | | GEOGRAPHY | SQL\$1 LONGVARBINARY | | GEOMETRY | SQL\$1 LONGVARBINARY | | INTEGER | SQL\$1INTEGER | | REAL | SQL\$1REAL | | SMALLINT | SQL\$1SMALLINT | | SUPER | SQL\$1LONGVARCHAR | | TEXT | SQL\$1LONGVARCHAR | | TIME | SQL\$1TYPE\$1TIME | | TIMETZ | SQL\$1TYPE\$1TIME | | TIMESTAMP | SQL\$1TYPE\$1 TIMESTAMP | | TIMESTAMPTZ | SQL\$1TYPE\$1 TIMESTAMP | | VARBYTE | SQL\$1LONGVARBINARY | | VARCHAR | SQL\$1VARCHAR | # ODBC 驱动程序选项 可以使用驱动程序配置选项来控制 Amazon Redshift ODBC 驱动程序的行为。驱动程序选项不区分大小写。 在 Microsoft Windows 中，您通常可以在配置数据来源名称 (DSN) 时设置驱动程序选项。您还能在以编程方式连接时，或者通过在 `HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\your_DSN` 中添加或更改注册表项来设置驱动程序选项。 在 Linux 中，可以在 `odbc.ini` 和 `amazon.redshiftodbc.ini` 文件中设置驱动程序配置选项。在 `amazon.redshiftodbc.ini` 文件中设置的配置选项适用于所有连接。相反，`odbc.ini` 文件中的设置配置选项特定于一个连接。在 `odbc.ini` 中设置的配置选项优先于在 `amazon.redshiftodbc.ini` 中设置的配置选项。 以下是您可以为 Amazon Redshift ODBC 版本 2.x 驱动程序指定的选项的说明： ## AccessKeyID + **默认值** – 无 + **数据类型** – 字符串 用户或角色的 IAM 访问密钥。如果您设置此参数，则还必须指定 **SecretAccessKey**。 此参数为可选的。 ## app\$1id + **默认值** – 无 + **数据类型** – 字符串 Okta 提供的与您的 Amazon Redshift 应用程序关联的唯一 ID。 此参数为可选的。 ## ApplicationName + **默认值** – 无 + **数据类型** – 字符串 传递给 Amazon Redshift 以供审计的客户端应用程序的名称。您提供的应用程序名称显示在 [SYS\$1CONNECTION\$1LOG](https://docs.aws.amazon.com/redshift/latest/dg/SYS_CONNECTION_LOG.html) 表的“application\$1name”列中。这有助于在调试问题时跟踪连接源并对其进行故障排除。 此参数为可选的。 ## app\$1name + **默认值** – 无 + **数据类型** – 字符串 您用于验证与 Amazon Redshift 的连接的 Okta 应用程序的名称。 此参数为可选的。 ## AuthProfile + **默认值** – 无 + **数据类型** – 字符串 用于管理连接设置的身份验证配置文件。如果您设置此参数，则还必须设置 **AccessKeyID** 和 **SecretAccessKey**。 此参数为可选的。 ## AuthType + **默认值**：标准 + **数据类型** – 字符串 此选项指定在您使用“Amazon Redshift ODBC 驱动程序 DSN 设置”对话框配置 DSN 时驱动程序使用的身份验证模式： + 标准：使用您的 Amazon Redshift 用户名和密码的标准身份验证。 + AWS 配置文件：使用配置文件的 IAM 身份验证。 + AWS IAM 凭证：使用 IAM 凭证的 IAM 身份验证。 + 身份提供者：AD FS：使用 Active Directory 联合身份验证服务（AD FS）的 IAM 身份验证。 + 身份提供者：身份验证插件：一种授权插件，可接受 AWS IAM Identity Center 令牌，或基于 OpenID Connect（OIDC）JSON 的身份令牌（JWT），该令牌由与 AWS IAM Identity Center 关联的任意 Web 身份提供者提供。 + 身份提供者：Azure AD：使用 Azure AD 门户的 IAM 身份验证。 + 身份提供者：JWT：使用 JSON Web 令牌（JWT）的 IAM 身份验证。 + 身份提供者：Okta：使用 Okta 的 IAM 身份验证。 + 身份提供者：PingFederate：使用 PingFederate 的 IAM 身份验证。 仅当您使用 Windows 驱动程序中的“Amazon Redshift ODBC 驱动程序 DSN 设置”对话框配置 DSN 时，此选项才可用。当您使用连接字符串或非 Windows 计算机配置连接时，驱动程序将根据您指定的凭证，自动确定是使用“标准”、“AWS 配置文件”还是“AWS IAM 凭证”身份验证。要使用身份提供者，您必须设置 **plugin\$1name** 属性。 此参数为必需参数。 ## AutoCreate + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定当指定的用户不存在时驱动程序是否创建新用户。 + 1 \$1 TRUE：如果通过 **UID** 指定的用户不存在，则驱动程序将创建新用户。 + 0 \$1 FALSE：驱动程序不会创建新用户。如果指定的用户不存在，则身份验证将失败。 此参数为可选的。 ## CaFile + **默认值** – 无 + **数据类型** – 字符串 用于某些形式的 IAM 身份验证的 CA 证书文件的文件路径。 此参数仅在 Linux 上可用。 此参数为可选的。 ## client\$1id + **默认值** – 无 + **数据类型** – 字符串 与 Azure AD 中的 Amazon Redshift 应用程序关联的客户端 ID。 如果通过 Azure AD 服务进行身份验证，则此参数是必需的。 ## client\$1 secret + **默认值** – 无 + **数据类型** – 字符串 与 Azure AD 中的 Amazon Redshift 应用程序关联的秘密密钥。 如果通过 Azure AD 服务进行身份验证，则此参数是必需的。 ## ClusterId + **默认值** – 无 + **数据类型** – 字符串 您要连接到的 Amazon Redshift 集群的名称。它将在 IAM 身份验证中使用。集群 ID 不会在**服务器**参数中指定。 此参数为可选的。 ## 压缩 + **默认值** – 关闭 + **数据类型** – 字符串 用于 Amazon Redshift 服务器与客户端或驱动程序之间线路协议通信的压缩方法。 可以指定以下值： + lz4：将用于与 Amazon Redshift 进行线路协议通信的压缩方法设置为 `lz4`。 + zstd：将用于与 Amazon Redshift 进行线路协议通信的压缩方法设置为 `zstd`。 + off：与 Amazon Redshift 进行线路协议通信时不使用压缩方法。 此参数为可选的。 ## 数据库 + **默认值** – 无 + **数据类型** – 字符串 您要访问的 Amazon Redshift 数据库的名称。 此参数为必需参数。 ## DatabaseMetadataCurrentDbOnly + **默认值**：1 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是否从多个数据库和集群返回元数据。 + 1 \$1 TRUE：驱动程序仅从当前数据库返回元数据。 + 0 \$1 FALSE。驱动程序将跨多个 Amazon Redshift 数据库和集群返回元数据。 此参数为可选的。 ## dbgroups\$1filter + **默认值** – 无 + **数据类型** – 字符串 在使用 Azure、浏览器 Azure 和浏览器 SAML 身份验证类型时，您可以指定的正则表达式，用于筛选出从 Amazon Redshift 的 SAML 响应中收到的数据库组 (DbGroup)。 此参数为可选的。 ## 驱动程序 + **默认值**：Amazon Redshift ODBC 驱动程序 (x64) + **数据类型** – 字符串 驱动程序的名称。唯一受支持的值是 **Amazon Redshift ODBC 驱动程序(x64)**。 如果您未设置 **DSN**，则此参数是必需的。 ## DSN + **默认值** – 无 + **数据类型** – 字符串 驱动程序数据来源名称的名称。应用程序将在 SQLDriverConnect API 中指定 DSN。 如果您未设置**驱动程序**，则此参数是必需的。 ## EndpointUrl + **默认值** – 无 + **数据类型** – 字符串 用于与 Amazon Redshift Coral 服务通信以进行 IAM 身份验证的覆盖端点。 此参数为可选的。 ## ForceLowercase + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定在使用单点登录身份验证时，驱动程序是否会将从身份提供者发送到 Amazon Redshift 的所有数据库组 (DbGroup) 小写。 + 1 \$1 TRUE：驱动程序会将从身份提供者发送的所有 DbGroup 转换为小写。 + 0 \$1 FALSE：驱动程序不会更改 DbGroup。 此参数为可选的。 ## group\$1federation + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，指定 `getClusterCredentialsWithIAM` API 是否用于在预调配集群中获取临时集群凭证。此选项允许 IAM 用户在预调配集群中与 Redshift 数据库角色进行集成。请注意，此选项不适用于 Redshift Serverless 命名空间。 + 1 \$1 TRUE：驱动程序使用 `getClusterCredentialsWithIAM` API 来获取预调配集群中的临时集群凭证。 + 0 \$1 FALSE：驱动程序使用默认 `getClusterCredentials` API 来获取预调配集群中的临时集群凭证。 此参数为可选的。 ## https\$1proxy\$1host + **默认值** – 无 + **数据类型** – 字符串 您要通过其来传递 IAM 身份验证过程的代理服务器的主机名或 IP 地址。 此参数为可选的。 ## https\$1proxy\$1password + **默认值** – 无 + **数据类型** – 字符串 用于访问代理服务器的密码。它将用于 IAM 身份验证。 此参数为可选的。 ## https\$1proxy\$1port + **默认值** – 无 + **数据类型** – 整数 代理服务器用于侦听客户端连接的端口号。它将用于 IAM 身份验证。 此参数为可选的。 ## https\$1proxy\$1username + **默认值** – 无 + **数据类型** – 字符串 用于访问代理服务器的用户名。它用于 IAM 身份验证。 此参数为可选的。 ## IAM + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是否使用 IAM 身份验证方法对连接进行身份验证。 + 1 \$1 TRUE：驱动程序将使用某种 IAM 身份验证方法（使用访问密钥和秘密密钥对、配置文件或凭证服务）。 + 0 \$1 FALSE。驱动程序将使用标准身份验证（使用您的数据库用户名和密码）。 此参数为可选的。 ## idc\$1client\$1display\$1name + **默认值** – Amazon Redshift ODBC 驱动程序 + **数据类型** – 字符串 要用于使用 BrowserIdcAuthPlugin 的客户端的显示名称。 此参数为可选的。 ## idc\$1region + **默认值** – 无 + **数据类型** – 字符串 AWS IAM Identity Center 实例所在的 AWS 区域。 只有在 plugin\$1name 配置选项中使用 `BrowserIdcAuthPlugin` 进行身份验证时，才需要此参数。 ## idp\$1host + **默认值** – 无 + **数据类型** – 字符串 您用于对 Amazon Redshift 进行身份验证的 IdP（身份提供者）主机。 此参数为可选的。 ## idp\$1port + **默认值** – 无 + **数据类型** – 整数 您用于对 Amazon Redshift 进行身份验证的 IdP（身份提供者）的端口。根据您在创建、修改或迁移集群时选择的端口，允许访问所选端口。 此参数为可选的。 ## idp\$1response\$1timeout + **默认值** – 120 + **数据类型** – 整数 当通过浏览器插件使用 SAML 或 Azure AD 服务时，驱动程序等待身份提供者发出 SAML 响应的秒数。 此参数为可选的。 ## idp\$1tenant + **默认值** – 无 + **数据类型** – 字符串 与您的 Amazon Redshift 应用程序关联的 Azure AD 租户 ID。 如果通过 Azure AD 服务进行身份验证，则此参数是必需的。 ## idp\$1partition + **默认值** – 无 + **数据类型** – 字符串 指定在其中配置身份提供者（IdP）的云分区。这决定了驱动程序连接到哪个 IdP 身份验证端点。 如果将此参数留空，则驱动程序默认为商业分区。可能的值有： + `us-gov`：如果在 Azure Government 中配置了 IdP，请使用此值。例如，Azure AD Government 使用端点 `login.microsoftonline.us`。 + `cn`：如果在中国云分区中配置了 IdP，请使用此值。例如，Azure AD China 使用 `login.chinacloudapi.cn` 端点。 此参数为可选的。 ## idp\$1use\$1https\$1proxy + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是否通过代理服务器传递身份提供者（IdP）的身份验证过程。 + 1 \$1 TRUE：驱动程序将通过代理服务器传递 IdP 身份验证过程。 + 0 \$1 FALSE。驱动程序不会通过代理服务器传递 IdP 身份验证过程。 此参数为可选的。 ## InstanceProfile + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序在配置为使用配置文件进行身份验证时是否使用 Amazon EC2 实例配置文件。 + 1 \$1 TRUE：驱动程序将使用 Amazon EC2 实例配置文件。 + 0 \$1 FALSE。驱动程序将改用通过“配置文件名称”选项（**配置文件**）指定的串联角色配置文件。 此参数为可选的。 ## issuer\$1url + **默认值** – 无 + **数据类型** – 字符串 指向 AWS IAM Identity Center 服务器的实例端点。 只有在 plugin\$1name 配置选项中使用 `BrowserIdcAuthPlugin` 进行身份验证时，才需要此参数。 ## KeepAlive + **默认值**：1 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是否使用 TCP keepalive 来防止连接超时。 + 1 \$1 TRUE：驱动程序将使用 TCP keepalive 来防止连接超时。 + 0 \$1 FALSE。驱动程序不会使用 TCP keepalive。 此参数为可选的。 ## KeepAliveCount + **默认值** - 0 + **数据类型** – 整数 连接被视为断开前可能丢失的 TCP keepalive 包的数量。当此参数设置为 0 时，驱动程序将使用此设置的系统默认值。 此参数为可选的。 ## KeepAliveInterval + **默认值** - 0 + **数据类型** – 整数 两次传输 TCP keepalive 间隔的秒数。当此参数设置为 0 时，驱动程序将使用此设置的系统默认值。 此参数为可选的。 ## KeepAliveTime + **默认值** - 0 + **数据类型** – 整数 驱动程序发送 TCP Keepalive 包前处于不活动状态的秒数。当此参数设置为 0 时，驱动程序将使用此设置的系统默认值。 此参数为可选的。 ## listen\$1port + **默认值**：7890 + **数据类型** – 整数 通过浏览器插件使用 SAML、Azure AD 或 AWS IAM Identity Center 服务时，驱动程序用于接收来自身份提供者的 SAML 响应的端口。 此参数为可选的。 ## login\$1url + **默认值** – 无 + **数据类型** – 字符串 在使用通用浏览器 SAML 插件时，身份提供者网站上的资源的 URL。 如果通过浏览器插件使用 SAML 或 Azure AD 服务进行身份验证，则此参数是必需的。 ## loginToRp + **默认值**：urn:amazon:webservices + **数据类型** – 字符串 要用于 AD FS 身份验证类型的信赖方信任。 此字符串为可选项。 ## LogLevel + **默认值** - 0 + **数据类型** – 整数 使用此属性可以启用或禁用驱动程序中的日志记录，并指定包含在日志中的详细信息量。我们建议您启用日志记录的时长仅足以捕获问题即可，因为日志记录会降低性能，并会占用大量磁盘空间。 将该属性设置为以下值之一： + 0：关闭。禁用所有日志记录。 + 1：错误。记录也许不会导致驱动程序中止运行但会生成错误的错误事件。 + 2：API\$1CALL。记录带有函数参数值的 ODBC API 函数调用。 + 3：信息。记录描述驱动程序进度的一般信息。 + 4：MSG\$1PROTOCOL。记录驱动程序消息协议的详细信息。 + 5：调试。记录所有驱动程序活动 + 6：DEBUG\$1APPEND。保留所有驱动程序活动的附加日志。 启用日志记录后，驱动程序将在您在 **LogPath** 属性中指定的位置生成以下日志文件： + 一个 `redshift_odbc.log.1` 文件，它将记录连接握手期间发生的驱动程序活动。 + 一个 `redshift_odbc.log` 文件，用于与数据库建立连接后的所有驱动程序活动。 此参数为可选的。 ## LogPath + **默认值**：特定于操作系统的 TEMP 目录 + **数据类型** – 字符串 当 **LogLevel** 大于 0 时，驱动程序保存日志文件的文件夹的完整路径。 此参数为可选的。 ## Min\$1TLS + **默认值** – 1.2 + **数据类型** – 字符串 驱动程序允许数据存储以用于对连接进行加密的 TLS/SSL 的最低版本。例如，如果指定了 TLS 1.2，则无法使用 TLS 1.1 对连接进行加密。 Min\$1TLS 接受以下值： + 1.0：连接必须至少使用 TLS 1.0。 + 1.1：连接必须至少使用 TLS 1.1。 + 1.2：连接必须至少使用 TLS 1.2。 此参数为可选的。 ## partner\$1spid + **默认值** – 无 + **数据类型** – 字符串 在使用 PingFederate 服务验证连接时使用的合作伙伴 SPID（服务提供商 ID）值。 此参数为可选的。 ## 密码\$1 PWS + **默认值** – 无 + **数据类型** – 字符串 与您在“用户”字段（**UID** \$1 **用户**\$1 **LogonID**）中提供的数据库用户名相对应的密码。 此参数为可选的。 ## plugin\$1name + **默认值** – 无 + **数据类型** – 字符串 要用于身份验证的凭证提供程序插件名称。 支持下列值： + `ADFS`：使用 Active Directory 联合身份验证服务进行身份验证。 + `AzureAD`：使用 Microsoft Azure Active Directory (AD) 服务进行身份验证。 + `BrowserAzureAD`：使用适用于 Microsoft Azure Active Directory (AD) 服务的浏览器插件进行身份验证。 + `BrowserIdcAuthPlugin `：使用 AWS IAM Identity Center 的授权插件。 + `BrowserSAML`：使用适用于 SAML 服务（如 Okta 或 Ping）的浏览器插件进行身份验证。 + `IdpTokenAuthPlugin`：一种授权插件，可接受 AWS IAM Identity Center 令牌，或者基于 OpenID Connect（OIDC）JSON 的身份令牌（JWT），该令牌由与 AWS IAM Identity Center 关联的任意 Web 身份提供者提供。 + `JWT`：使用 JSON Web 令牌 (JWT) 进行身份验证。 + `Ping`：使用 PingFederate 服务进行身份验证。 + `Okta`：使用 Okta 服务进行身份验证。 此参数为可选的。 ## 端口 \$1 PortNumber + **默认值**：5439 + **数据类型** – 整数 Amazon Redshift 服务器用于侦听客户端连接的 TCP 端口号。 此参数为可选的。 ## preferred\$1role + **默认值** – 无 + **数据类型** – 字符串 您希望在 Amazon Redshift 连接期间担任的角色。它将用于 IAM 身份验证。 此参数为可选的。 ## 配置文件 + **默认值** – 无 + **数据类型** – 字符串 用于在 Amazon Redshift 中进行身份验证的用户 AWS 配置文件的名称。 + 如果“使用实例配置文件”参数（**InstanceProfile** 属性）设置为 1 \$1 TRUE，则该设置将优先，驱动程序将改用 Amazon EC2 实例配置文件。 + 包含配置文件的凭证文件的默认位置为 `~/.aws/Credentials`。`AWS_SHARED_CREDENTIALS_FILE` 环境变量可用于指向其他凭证文件。 此参数为可选的。 ## provider\$1name + **默认值** – 无 + **数据类型** – 字符串 用户使用 CREATE IDENTITY PROVIDER 查询创建的身份验证提供程序。它将用于本机 Amazon Redshift 身份验证。 此参数为可选的。 ## ProxyHost + **默认值** – 无 + **数据类型** – 字符串 要通过其连接的代理服务器的主机名或 IP 地址。 此参数为可选的。 ## ProxyPort + **默认值** – 无 + **数据类型** – 整数 代理服务器用于侦听客户端连接的端口号。 此参数为可选的。 ## ProxyPwd + **默认 ValPrevious ODBC 驱动程序版本**：无 + **数据类型** – 字符串 用于访问代理服务器的密码。 此参数为可选的。 ## ProxyUid + **默认值** – 无 + **数据类型** – 字符串 用于访问代理服务器的用户名。 此参数为可选的。 ## ReadOnly + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是否处于只读模式。 + 1 \$1 TRUE：连接处于只读模式，无法写入数据存储。 + 0 \$1 FALSE：连接不处于只读模式，可以写入数据存储。 此参数为可选的。 ## region + **默认值** – 无 + **数据类型** – 字符串 您的集群所在的 AWS 区域。 此参数为可选的。 ## SecretAccessKey + **默认值** – 无 + **数据类型** – 字符串 用户或角色的 IAM 秘密密钥。如果您设置此参数，则还必须设置 **AccessKeyID**。 此参数为可选的。 ## SessionToken + **默认值** – 无 + **数据类型** – 字符串 与您用于身份验证的 IAM 角色关联的临时 IAM 会话令牌。 此参数为可选的。 ## 服务器 \$1 HostName \$1 主机 + **默认值** – 无 + **数据类型** – 字符串 要连接到的端点服务器。 此参数为必需参数。 ## ssl\$1insecure + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是否检查 IdP 服务器证书的真实性。 + 1 \$1 TRUE：驱动程序不检查 IdP 服务器证书的真实性。 + 0 \$1 FALSE：驱动程序检查 IdP 服务器证书的真实性 此参数为可选的。 ## SSLMode + **默认值** – `verify-ca` + **数据类型** – 字符串 在连接到 Amazon Redshift 时要使用的 SSL 证书验证模式。以下是可能的值： + `verify-full`：仅使用 SSL、受信任的证书颁发机构和与证书匹配的服务器名称进行连接。 + `verify-ca`：仅使用 SSL 和受信任的证书颁发机构进行连接。 + `require`：仅使用 SSL 进行连接。 + `prefer`：使用 SSL 进行连接（如果可用）。否则，将在不使用 SSL 的情况下进行连接。 + `allow`：默认情况下，不使用 SSL 进行连接。如果服务器需要 SSL 连接，则使用 SSL。 + `disable`：不使用 SSL 进行连接。 此参数为可选的。 ## StsConnectionTimeout + **默认值** - 0 + **数据类型** – 整数 IAM 连接的最长等待时间（以秒为单位）。如果设置为 0 或未指定，驱动程序将为每次 AWS STS 调用等待 60 秒。 此参数为可选的。 ## StsEndpointUrl + **默认值** – 无 + **数据类型** – 字符串 此选项指定用于与 AWS Security Token Service (AWS STS) 通信的覆盖端点。 此参数为可选的。 ## 令牌 + **默认值** – 无 + **数据类型** – 字符串 AWS IAM Identity Center 提供的访问令牌，或 OpenID Connect（OIDC）JSON Web 令牌（JWT，JSON Web Token），该令牌由与 AWS IAM Identity Center 关联的 Web 身份提供者提供。您的应用程序必须通过 AWS IAM Identity Center 或与 AWS IAM Identity Center 关联的身份提供者，对您的应用程序用户进行身份验证，从而生成此令牌。 此参数可用于 `IdpTokenAuthPlugin`。 ## token\$1type + **默认值** – 无 + **数据类型** – 字符串 `IdpTokenAuthPlugin` 中使用的令牌类型。 可以指定以下值： **ACCESS\$1TOKEN** 如果您使用 AWS IAM Identity Center 提供的访问令牌，请输入此项。 **EXT\$1JWT** 如果您使用 OpenID Connect（OIDC）JSON Web 令牌（JWT）（该令牌由与 AWS IAM Identity Center 集成的基于 Web 的身份提供者提供），请输入此项。 此参数可用于 `IdpTokenAuthPlugin`。 ## UID \$1 用户 \$1 LogonID + **默认值** – 无 + **数据类型** – 字符串 用于访问 Amazon Redshift 服务器的用户名。 如果使用数据库身份验证，则此参数是必需项。 ## UseUnicode + **默认值** - 0 + **数据类型** – Boolean 一个布尔值，用于指定驱动程序是以 Unicode 还是常规 SQL 类型返回 Redshift 数据。 + 1 \$1 TRUE：驱动程序返回字符数据类型的宽 SQL 类型。 + 返回 SQL\$1WCHAR 而不是 SQL\$1CHAR。 + 返回 SQL\$1WVARCHAR 而不是 SQL\$1VARCHAR。 + 返回 SQL\$1WLONGVARCHAR 而不是 SQL\$1LONGVARCHAR。 + 0 \$1 FALSE：驱动程序返回字符数据类型的正常 SQL 类型。 + 返回 SQL\$1CHAR 而不是 SQL\$1WCHAR。 + 返回 SQL\$1VARCHAR 而不是 SQL\$1WVARCHAR。 + 返回 SQL\$1LONGVARCHAR 而不是 SQL\$1WLONGVARCHAR。 此参数为可选的。它在驱动程序版本 2.1.15 和更高版本中可用。 ## web\$1identity\$1token + **默认值** – 无 + **数据类型** – 字符串 身份提供者提供的 OAUTH 令牌。它将在 JWT 插件中使用。 如果您将 **plugin\$1name** 参数设置为 BasicJwtCredentialsProvider，则此参数是必需项。 # 早期 ODBC 驱动程序版本 仅当您的工具需要使用某个特定版本的驱动程序时，才能下载 Amazon Redshift ODBC 驱动程序版本 2.x 的以前版本。 ## 使用适用于 Microsoft Windows 的以前 ODBC 驱动程序版本 以下是适用于 Microsoft Windows 的旧 Amazon Redshift ODBC 驱动程序版本 2.x： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC64-2.1.14.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC64-2.1.14.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC64-2.1.13.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC64-2.1.13.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC64-2.1.12.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC64-2.1.12.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC64-2.1.11.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC64-2.1.11.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC64-2.1.10.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC64-2.1.10.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC64-2.1.8.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC64-2.1.8.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC64-2.1.7.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC64-2.1.7.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC64-2.1.6.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC64-2.1.6.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC64-2.1.4.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC64-2.1.4.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC64-2.1.3.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC64-2.1.3.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC64-2.1.2.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC64-2.1.2.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC64-2.1.1.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC64-2.1.1.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC64-2.1.0.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC64-2.1.0.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC64-2.0.1.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC64-2.0.1.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC64-2.0.0.11.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC64-2.0.0.11.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC64-2.0.0.9.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC64-2.0.0.9.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC64-2.0.0.8.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC64-2.0.0.8.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC64-2.0.0.7.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC64-2.0.0.7.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC64-2.0.0.6.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC64-2.0.0.6.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC64-2.0.0.5.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC64-2.0.0.5.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC64-2.0.0.3.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC64-2.0.0.3.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC64-2.0.0.1.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC64-2.0.0.1.msi) ## 使用适用于 Linux 的以前 ODBC 驱动程序版本 以下是适用于 Linux 的旧 Amazon Redshift ODBC 驱动程序版本 2.x： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC-64-bit-2.1.10.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC-64-bit-2.1.10.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC-64-bit-2.1.9.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC-64-bit-2.1.9.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC-64-bit-2.1.8.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC-64-bit-2.1.8.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC-64-bit-2.1.7.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC-64-bit-2.1.7.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC-64-bit-2.1.6.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC-64-bit-2.1.6.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC-64-bit-2.1.4.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC-64-bit-2.1.4.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC-64-bit-2.1.3.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC-64-bit-2.1.3.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC-64-bit-2.1.2.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC-64-bit-2.1.2.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC-64-bit-2.1.1.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC-64-bit-2.1.1.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC-64-bit-2.1.0.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC-64-bit-2.1.0.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC-64-bit-2.0.1.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC-64-bit-2.0.1.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC-64-bit-2.0.0.11.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC-64-bit-2.0.0.11.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC-64-bit-2.0.0.9.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC-64-bit-2.0.0.9.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC-64-bit-2.0.0.8.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC-64-bit-2.0.0.8.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC-64-bit-2.0.0.7.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC-64-bit-2.0.0.7.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC-64-bit-2.0.0.6.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC-64-bit-2.0.0.6.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC-64-bit-2.0.0.5.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC-64-bit-2.0.0.5.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC-64-bit-2.0.0.3.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC-64-bit-2.0.0.3.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC-64-bit-2.0.0.1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC-64-bit-2.0.0.1.x86_64.rpm) ## 使用适用于 Apple macOS 的早期 ODBC 驱动程序版本 以下是适用于 Apple macOS 的旧 Amazon Redshift ODBC 驱动程序版本 2.x： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit.2.1.14.0.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit.2.1.14.0.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit.2.1.13.0.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit.2.1.13.0.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit.2.1.12.0.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit.2.1.12.0.universal.pkg) # 配置 ODBC 驱动程序版本 1.x 连接 您可以使用 ODBC 连接将许多第三方 SQL 客户端工具和应用程序连接到您的 Amazon Redshift 集群。为此，请在您的客户端计算机或 Amazon EC2 实例上设置连接。如果您的客户端工具支持 JDBC，您可以选择使用 JDBC 连接而非 ODBC 连接，因为 JDBC 连接更加易于配置。但是，如果您的客户端工具不支持 JDBC，请按此部分中的步骤配置 ODBC 连接。 Amazon Redshift 提供了适用于 Linux、Windows 和 macOS X 操作系统的 64-bit ODBC 驱动程序。32 位 ODBC 驱动程序已停产。除了紧急安全补丁外，不会发布进一步的更新。 有关 ODBC 驱动程序功能和先决条件的最新信息，请参阅 [Amazon Redshift ODBC 驱动程序发布说明](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Release+Notes.pdf)。 有关 Amazon Redshift ODBC 驱动程序的安装和配置信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [获取 ODBC URL](obtain-odbc-url.md) + [在 Microsoft Windows 上使用 Amazon Redshift ODBC 驱动程序](install-odbc-driver-windows.md) + [在 Linux 上使用 Amazon Redshift ODBC 驱动程序](install-odbc-driver-linux.md) + [在 macOS X 上使用 Amazon Redshift ODBC 驱动程序](install-odbc-driver-mac.md) + [ODBC 驱动程序选项](configure-odbc-options.md) + [早期 ODBC 驱动程序版本](odbc-previous-versions.md) # 获取 ODBC URL Amazon Redshift 在 Amazon Redshift 控制台中显示您的集群的 ODBC URL。此 URL 包含在客户端计算机与数据库之间建立连接时所需的信息。 ODBC URL 采用以下格式：`Driver={driver};Server=endpoint;Database=database_name;UID=user_name;PWD=password;Port=port_number` 前面显示的格式的字段具有以下值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/obtain-odbc-url.html) 上表中的字段可以包含以下特殊字符： ``` []{}(),;?*=!@ ``` 如果您使用这些特殊字符，则必须用大括号括起值。例如，连接字符串 `PWD={Your;password123};` 中的密码值表示为 `Your;password123`。 由于 `Field=value` 对使用分号分隔，因此中间具有任意数量空格的 `}` 和 `;` 组合将被视为 `Field={value};` 对的结尾。我们建议您避免在字段值中使用序列 `};`。例如，如果您将密码值设置为 `PWD={This is a passwor} ;d};`，则密码将为 `This is a passwor} ;`，URL 将出错。 以下是一个示例 ODBC URL。 ``` Driver={Amazon Redshift (x64)}; Server=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com; Database=dev; UID=adminuser; PWD=insert_your_admin_user_password_here; Port=5439 ``` 有关如何获取 ODBC 连接的信息，请参阅 [查找集群连接字符串](connecting-connection-string.md)。 # 在 Microsoft Windows 上使用 Amazon Redshift ODBC 驱动程序 您可以在可访问 Amazon Redshift 数据仓库的客户端计算机上安装 Amazon Redshift ODBC 驱动程序。在其上安装该驱动程序的每台计算机都必须满足一系列最低系统要求。有关最低系统要求的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [下载并安装 Amazon Redshift ODBC 驱动程序](odbc-driver-windows-how-to-install.md) + [为 ODBC 连接创建系统 DSN 条目](create-dsn-odbc-windows.md) # 下载并安装 Amazon Redshift ODBC 驱动程序 使用以下过程下载适用于 Windows 操作系统的 Amazon Redshift ODBC 驱动程序。仅在您当前运行的第三方应用程序获得了使用 Amazon Redshift 的认证并且需要特定的驱动程序时，才使用上述驱动程序之外的驱动程序。 **安装 ODBC 驱动程序** 1. 根据您的 SQL 客户端工具或应用程序的系统架构，下载以下驱动程序之一： + [64 位 ODBC 驱动程序版本 1.6.3](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC64-1.6.3.1008.msi) 此驱动程序的名称为 Amazon Redshift (x64)。 + [32 位 ODBC 驱动程序版本 1.4.52](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC32-1.4.52.1000.msi) 此驱动程序的名称为 Amazon Redshift (x86)。32 位 ODBC 驱动程序已停产。除了紧急安全补丁外，不会发布进一步的更新。 **注意** 根据您的 SQL 客户端工具或应用程序的系统架构，下载相应的 MSI 包。例如，如果您的 SQL 客户端工具是 64 位，则安装 64 位驱动程序。 然后，下载并查看 [Amazon Redshift ODBC 和 JDBC 驱动程序许可证协议](https://s3.amazonaws.com/redshift-downloads/drivers/Amazon+Redshift+ODBC+and+JDBC+Driver+License+Agreement.pdf)。 1. 双击 .msi 文件，然后按照向导中的步骤安装驱动程序。 # 为 ODBC 连接创建系统 DSN 条目 下载并安装 ODBC 驱动程序后，将数据来源名称 (DSN) 条目添加到客户端计算机或 Amazon EC2 实例。SQL 客户端工具将使用此数据源连接到 Amazon Redshift 数据库。 建议您创建系统 DSN 而不是用户 DSN。一些应用程序使用不同的用户账户加载数据。这些应用程序可能无法检测在其他用户账户下创建的用户 DSN。 **注意** 对于使用 AWS Identity and Access Management (IAM) 凭证或身份提供者 (IdP) 凭证进行的身份验证，需要执行其他步骤。有关更多信息，请参阅 [步骤 5：配置 JDBC 或 ODBC 连接以使用 IAM 凭证](generating-iam-credentials-steps.md#generating-iam-credentials-configure-jdbc-odbc)。 有关如何创建系统 DSN 条目的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **在 Windows 上为 ODBC 连接创建系统 DSN 条目** 1. 在**开始**菜单上，打开**ODBC 数据源**。 请确保您选择的 ODBC Data Source Administrator 的位数与用于连接 Amazon Redshift 的客户端应用程序的位数相同。 1. 在 **ODBC 数据数据源管理器**中，选择**驱动程序**选项卡并找到驱动程序文件夹。 + **Amazon Redshift ODBC 驱动程序（64 位）** + **Amazon Redshift ODBC 驱动程序（32 位）** 1. 选择**系统 DSN** 选项卡为计算机上的所有用户配置驱动程序，或选择**用户 DSN** 选项卡仅为您的用户账户配置驱动程序。 1. 选择**添加**。系统随即打开 **Create New Data Source** 窗口。 1. 选择 **Amazon Redshift** ODBC 驱动程序，然后选择**完成**。系统随即打开 ** Amazon Redshift ODBC Driver DSN Setup** 窗口。 1. 在 **Connection Settings** 下，输入以下信息： **Data source name** 输入数据源的名称。在稍后创建到集群的连接时，您可以使用任何名称来标识该数据源。例如，如果您遵循的是《Amazon Redshift 入门指南》**，则可键入 `exampleclusterdsn`，以便轻松记住将与此 DSN 关联的集群。 **服务器** 为您的 Amazon Redshift 集群指定端点。您可以在 Amazon Redshift 控制台中的集群详细信息页面上找到该信息。有关更多信息，请参阅 [在 Amazon Redshift 中配置连接](configuring-connections.md)。 **端口** 输入数据库使用的端口号。使用集群在启动或修改时配置为使用的端口。 **数据库** 输入 Amazon Redshift 数据库的名称。如果您在未指定数据库名称的情况下启动了集群，请输入 `dev`。否则，请使用您在启动过程中选择的名称。如果您遵循的是《Amazon Redshift 入门指南》**，输入 `dev`。 1. 在**身份验证**下，指定配置选项以配置标准或 IAM 身份验证。有关身份验证选项的信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**中的“在 Windows 上配置身份验证”。 1. 在 **SSL Settings** 下，指定以下项目的值： **SSL authentication** 选择处理安全套接字层 (SSL) 的模式。在测试环境中，可以使用 `prefer`。但是，对于生产环境以及在需要安全交换数据时，请使用 `verify-ca` 或 `verify-full`。有关在 Windows 上使用 SSL 的更多信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**中的“在 Windows 上配置 SSL 验证”。 1. 在**其他选项**下，指定有关如何将查询结果返回至您的 SQL 客户端工具或应用程序的选项。有关更多信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**中的“在 Windows 上配置其他选项”。 1. 在**日志记录选项**中，指定日志记录选项的值。有关更多信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**中的“在 Windows 上配置日志记录选项”。 然后选择**确定**。 1. 在**数据类型选项** 下，指定数据类型的值。有关更多信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**中的“在 Windows 上配置数据类型选项”。 然后选择**确定**。 1. 选择**测试**。如果客户端计算机可以连接到 Amazon Redshift 数据库，您会看到以下消息：**连接成功**。 如果客户端计算机无法连接到数据库，您可以进行故障排除，解决可能存在的问题。有关更多信息，请参阅 [解决 Amazon Redshift 中的连接问题](troubleshooting-connections.md)。 1. 在 Windows 上配置 TCP Keepalive 以防止连接超时。有关如何在 Windows 上配置 TCP Keepalive 的信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**。 1. 要帮助进行故障排除，请配置日志记录。有关如何在 Windows 上配置日志记录的信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南》**。 # 在 Linux 上使用 Amazon Redshift ODBC 驱动程序 您可以在可访问 Amazon Redshift 数据仓库的客户端计算机上安装 Amazon Redshift ODBC 驱动程序。在其上安装该驱动程序的每台计算机都必须满足一系列最低系统要求。有关最低系统要求的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [下载并安装 Amazon Redshift ODBC 驱动程序](odbc-driver-linux-how-to-install.md) + [使用 ODBC 驱动程序管理器配置驱动程序](odbc-driver-configure-linux.md) # 下载并安装 Amazon Redshift ODBC 驱动程序 按照此部分中的步骤在受支持的 Linux 发行版上下载并安装 Amazon Redshift ODBC 驱动程序。在安装过程中，驱动程序文件将被安装到以下目录中： + `/opt/amazon/redshiftodbc/lib/64`（对于 64 位驱动程序） + `/opt/amazon/redshiftodbc/ErrorMessages` + `/opt/amazon/redshiftodbc/Setup` + `/opt/amazon/redshiftodbc/lib/32`（对于 32 位驱动程序） **要安装 Amazon Redshift ODBC 驱动程序** 1. 根据您的 SQL 客户端工具或应用程序的系统架构，下载以下驱动程序之一： + [64 位 RPM 驱动程序版本 1.6.3](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC-64-bit-1.6.3.1008-1.x86_64.rpm) + [64 位 Debian 驱动程序版本 1.6.3](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC-64-bit-1.6.3.1008-1.x86_64.deb) + [32 位驱动程序版本 1.4.52](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-32-bit-1.4.52.1000-1.i686.rpm) 这些驱动程序的名称均是 Amazon Redshift ODBC 驱动程序。32 位 ODBC 驱动程序已停产。除了紧急安全补丁外，不会发布进一步的更新。 **注意** 下载适用于您的 SQL 客户端工具或应用程序系统架构的程序包。例如，如果您的客户端工具是 64 位，则安装 64 位驱动程序。 然后，下载并查看 [Amazon Redshift ODBC 和 JDBC 驱动程序许可证协议](https://s3.amazonaws.com/redshift-downloads/drivers/Amazon+Redshift+ODBC+and+JDBC+Driver+License+Agreement.pdf)。 1. 转至您下载程序包的位置，然后运行以下命令之一。使用适用于您的 Linux 发行版的命令。 + 在 RHEL 和 CentOS 操作系统上，运行以下命令。 ``` yum -nogpgcheck localinstall RPMFileName ``` 将 *`RPMFileName`* 替换为 RPM 包文件名。例如，以下命令将演示如何安装 64 位驱动程序。 ``` yum -nogpgcheck localinstall AmazonRedshiftODBC-64-bit-1.x.xx.xxxx-x.x86_64.rpm ``` + 在 SLES 上，运行以下命令。 ``` zypper install RPMFileName ``` 将 *`RPMFileName`* 替换为 RPM 包文件名。例如，以下命令将演示如何安装 64 位驱动程序。 ``` zypper install AmazonRedshiftODBC-1.x.x.xxxx-x.x86_64.rpm ``` + 在 Debian 上，运行以下命令。 ``` sudo apt install ./DEBFileName.deb ``` 将 `DEBFileName.deb` 替换为 Debian 包文件名。例如，以下命令将演示如何安装 64 位驱动程序。 ``` sudo apt install ./AmazonRedshiftODBC-1.x.x.xxxx-x.x86_64.deb ``` **重要** 安装完驱动程序后，请对其进行配置以在您的系统上使用。有关驱动程序配置的更多信息，请参阅[使用 ODBC 驱动程序管理器配置驱动程序使用 ODBC 驱动程序管理器配置驱动程序](odbc-driver-configure-linux.md)。 # 使用 ODBC 驱动程序管理器配置驱动程序 在 Linux 操作系统上，您可以使用 ODBC 驱动程序管理器来配置 ODBC 连接设置。ODBC 驱动程序管理器使用配置文件来定义和配置 ODBC 数据来源和驱动程序。您可以使用的 ODBC 驱动程序管理器取决于您使用的操作系统。对于 Linux，则是 unixODBC 驱动程序管理器。 有关用来配置 Amazon Redshift ODBC 驱动程序的受支持的 ODBC 驱动程序管理器的更多信息，请参阅 [在 Linux 上使用 Amazon Redshift ODBC 驱动程序在 Linux 上使用 ODBC 驱动程序](install-odbc-driver-linux.md)（适用于 Linux 操作系统）。另请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上指定 ODBC 驱动程序管理器”。 要配置 Amazon Redshift ODBC 驱动程序，需要提供以下三个文件：`amazon.redshiftodbc.ini`、`odbc.ini` 和 `odbcinst.ini`。 如果您将驱动程序安装在默认位置，`amazon.redshiftodbc.ini` 配置文件则位于以下目录之一： + `/opt/amazon/redshiftodbc/lib/64`（适用于 Linux 操作系统上的 64 位驱动程序） + `/opt/amazon/redshiftodbc/lib/32`（适用于 Linux 操作系统上的 32 位驱动程序） 此外，在 Linux 上的 `/opt/amazon/redshiftodbc/Setup` 下，还有示例 `odbc.ini` 和 `odbcinst.ini` 文件。您可以使用这些文件作为配置 Amazon Redshift ODBC 驱动程序和数据来源名称 (DSN) 的示例。 我们不建议使用 Amazon Redshift ODBC 驱动程序安装目录来存储配置文件。`Setup` 目录中的示例文件仅用作示例。如果您日后重新安装 Amazon Redshift ODBC 驱动程序，或将其升级到新版本，安装目录会被覆盖。之后，您将丢失对这些文件所做的全部更改。 为了避免出现这种情况，请将 `amazon.redshiftodbc.ini` 文件复制到安装目录以外的其他目录中。如果您要将此文件复制到用户的主目录，请在文件名的开头添加一个句点 (.)，使其成为隐藏文件。 对于 `odbc.ini` 和 `odbcinst.ini` 文件，应在用户的主目录中使用配置文件，或者在其他目录中创建新版本。默认情况下，您的 Linux 操作系统应在用户的主目录（`/home/$USER` 或 `~/`）中包含 `odbc.ini` 文件和 `odbcinst.ini` 文件。这些默认文件均为隐藏文件（通过在每个文件名的前面添加圆点 (.) 表示）。这些文件仅当您使用 `-a` 标志列出目录内容时显示。 对于 `odbc.ini` 和 `odbcinst.ini` 文件，不管您选择哪个选项，都需对这些文件进行修改，以添加驱动程序和 DSN 配置信息。如果您创建新文件，则还需设置环境变量，以指定这些配置文件的目标存储位置。 默认情况下，ODBC 驱动程序管理器将配置为使用主目录中隐藏的 `odbc.ini` 和 `odbcinst.ini` 配置文件版本（名为 .`odbc.ini` 和 .`odbcinst.ini`）。它们也被配置为使用驱动程序安装目录的 `amazon.redshiftodbc.ini` 子文件夹中的 `/lib` 文件。如果您将这些配置文件存储在其他位置，请设置如下所述的环境变量，以便驱动程序管理器能够找到这些文件。有关更多信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“指定驱动程序配置文件的位置”。 ## 在 Linux 操作系统上创建数据来源名称 在使用数据源名称 (DSN) 连接到数据存储时，请配置 `odbc.ini` 文件以定义 DSN。在 `odbc.ini` 文件中设置属性以创建指定数据存储的连接信息的 DSN。 有关如何配置 `odbc.ini` 文件的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上创建数据源名称” 请在 Linux 操作系统上使用以下格式。 ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/driver_file Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下示例显示了在 Linux 操作系统上使用 64 位 ODBC 驱动程序配置 odbc.ini。 ``` [ODBC Data Sources] Amazon_Redshift_x64=Amazon Redshift (x64) [Amazon Redshift (x64)] Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` 以下示例显示了在 Linux 操作系统上使用 32 位 ODBC 驱动程序配置 odbc.ini。 ``` [ODBC Data Sources] Amazon_Redshift_x32=Amazon Redshift (x86) [Amazon Redshift (x86)] Driver=/opt/amazon/redshiftodbc/lib/32/libamazonredshiftodbc32.so Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` ## 在 Linux 操作系统上配置没有 DSN 的连接 要通过不带 DSN 的连接来连接到数据存储，请在 `odbcinst.ini` 文件中定义驱动程序。然后，在应用程序中提供一个无 DSN 的连接字符串。 有关在这种情况下如何配置 `odbcinst.ini` 文件的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上配置没有 DSN 的连接”。 请在 Linux 操作系统上使用以下格式。 ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/driver_file ... ``` 以下示例显示了安装在 Linux 操作系统默认目录中的 64 位驱动程序的 `odbcinst.ini` 配置。 ``` [ODBC Drivers] Amazon Redshift (x64)=Installed [Amazon Redshift (x64)] Description=Amazon Redshift ODBC Driver (64-bit) Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so ``` 以下示例显示了安装在 Linux 操作系统默认目录中的 32 位驱动程序的 `odbcinst.ini` 配置。 ``` [ODBC Drivers] Amazon Redshift (x86)=Installed [Amazon Redshift (x86)] Description=Amazon Redshift ODBC Driver (32-bit) Driver=/opt/amazon/redshiftodbc/lib/32/libamazonredshiftodbc32.so ``` ## 配置环境变量 使用正确的 ODBC 驱动程序管理器加载正确的驱动程序。为此，请设置库路径环境变量。有关更多信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上指定 ODBC 驱动程序管理器”。 默认情况下，ODBC 驱动程序管理器将配置为使用主目录中隐藏的 `odbc.ini` 和 `odbcinst.ini` 配置文件版本（名为 .`odbc.ini` 和 .`odbcinst.ini`）。它们也被配置为使用驱动程序安装目录的 `/lib` 子文件夹中的 `amazon.redshiftodbc.ini` 文件。如果您将这些配置文件存储在其他位置，请设置环境变量，以便驱动程序管理器能够找到这些文件。有关更多信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南**中的“指定驱动程序配置文件的位置”。 ## 配置连接功能 可以为 ODBC 设置配置以下连接功能： + 配置 ODBC 驱动程序以提供凭证并验证与 Amazon Redshift 数据库的连接。 + 如果要连接到启用了 SSL 的 Amazon Redshift 服务器，请将 ODBC 驱动程序配置为连接到启用了安全套接字层 (SSL) 的套接字。 + 将 ODBC 驱动程序配置为通过代理服务器连接到 Amazon Redshift。 + 将 ODBC 驱动程序配置为使用查询处理模式来防止查询占用过多内存。 + 将 ODBC 驱动程序配置为通过代理服务器传递 IAM 身份验证过程。 + 将 ODBC 驱动程序配置为使用 TCP Keepalive 来防止连接超时。 有关这些连接功能的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 # 在 macOS X 上使用 Amazon Redshift ODBC 驱动程序 您可以在可访问 Amazon Redshift 数据仓库的客户端计算机上安装驱动程序。在其上安装该驱动程序的每台计算机都必须满足一系列最低系统要求。有关最低系统要求的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [下载并安装 Amazon Redshift ODBC 驱动程序](odbc-driver-mac-how-to-install.md) + [使用 ODBC 驱动程序管理器配置驱动程序](odbc-driver-configure-mac.md) # 下载并安装 Amazon Redshift ODBC 驱动程序 按照此部分中的步骤操作，在受支持的 macOS X 版本上下载和安装 Amazon Redshift ODBC 驱动程序。在安装过程中，驱动程序文件将被安装到以下目录中： + `/opt/amazon/redshift/lib/universal` + `/opt/amazon/redshift/ErrorMessages` + `/opt/amazon/redshift/Setup` **要在 macOS X 上安装 Amazon Redshift ODBC 驱动程序** 1. 要在 macOS X 上安装 Amazon Redshift ODBC 驱动程序，请下载 [macOS 驱动程序版本 1.6.3](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC-64-bit.1.6.3.1008.universal.pkg)。 然后，下载并查看 [Amazon Redshift ODBC 和 JDBC 驱动程序许可证协议](https://s3.amazonaws.com/redshift-downloads/drivers/Amazon+Redshift+ODBC+and+JDBC+Driver+License+Agreement.pdf)。 1. 双击 **AmazonRedshiftODBC.pkg** 以运行安装程序。 1. 按照安装程序中的步骤完成驱动程序的安装过程。要执行安装，需同意许可协议的条款。 **重要** 安装完驱动程序后，请对其进行配置以在您的系统上使用。有关驱动程序配置的更多信息，请参阅[使用 ODBC 驱动程序管理器配置驱动程序使用 ODBC 驱动程序管理器配置驱动程序](odbc-driver-configure-mac.md)。 # 使用 ODBC 驱动程序管理器配置驱动程序 在 macOS X 操作系统上，您可以使用 ODBC 驱动程序管理器来配置 ODBC 连接设置。ODBC 驱动程序管理器使用配置文件来定义和配置 ODBC 数据来源和驱动程序。您可以使用的 ODBC 驱动程序管理器取决于您使用的操作系统。对于 macOS X 操作系统，则是 iODBC 驱动程序管理器。 有关用来配置 Amazon Redshift ODBC 驱动程序的受支持的 ODBC 驱动程序管理器的更多信息，请参阅 [在 macOS X 上使用 Amazon Redshift ODBC 驱动程序在 macOS X 上使用 ODBC 驱动程序](install-odbc-driver-mac.md)（适用于 macOS X 操作系统）。另请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上指定 ODBC 驱动程序管理器”。 要配置 Amazon Redshift ODBC 驱动程序，需要提供以下三个文件：`amazon.redshiftodbc.ini`、`odbc.ini` 和 `odbcinst.ini`。 如果您将驱动程序安装在默认位置，则 `amazon.redshiftodbc.ini` 配置文件将位于 `/opt/amazon/redshift/lib` 中。 此外，在 macOS X 上的 `/opt/amazon/redshift/Setup` 下，还有示例 `odbc.ini` 和 `odbcinst.ini` 文件。您可以使用这些文件作为配置 Amazon Redshift ODBC 驱动程序和数据来源名称 (DSN) 的示例。 我们不建议使用 Amazon Redshift ODBC 驱动程序安装目录来存储配置文件。`Setup` 目录中的示例文件仅用作示例。如果您日后重新安装 Amazon Redshift ODBC 驱动程序，或将其升级到新版本，安装目录会被覆盖。之后，您将丢失对这些文件所做的全部更改。 为了避免出现这种情况，请将 `amazon.redshiftodbc.ini` 文件复制到安装目录以外的其他目录中。如果您要将此文件复制到用户的主目录，请在文件名的开头添加一个句点 (.)，使其成为隐藏文件。 对于 `odbc.ini` 和 `odbcinst.ini` 文件，应在用户的主目录中使用配置文件，或者在其他目录中创建新版本。默认情况下，您的 macOS X 操作系统应在用户的主目录（`/home/$USER` 或 `~/`）中提供有 `odbc.ini` 文件和 `odbcinst.ini` 文件。这些默认文件均为隐藏文件（通过在每个文件名的前面添加圆点 (.) 表示）。这些文件仅当您使用 `-a` 标志列出目录内容时显示。 对于 `odbc.ini` 和 `odbcinst.ini` 文件，不管您选择哪个选项，都需对这些文件进行修改，以添加驱动程序和 DSN 配置信息。如果您创建新文件，则还需设置环境变量，以指定这些配置文件的目标存储位置。 默认情况下，ODBC 驱动程序管理器将配置为使用主目录中隐藏的 `odbc.ini` 和 `odbcinst.ini` 配置文件版本（名为 .`odbc.ini` 和 .`odbcinst.ini`）。它们也被配置为使用驱动程序安装目录的 `amazon.redshiftodbc.ini` 子文件夹中的 `/lib` 文件。如果您将这些配置文件存储在其他位置，请设置如下所述的环境变量，以便驱动程序管理器能够找到这些文件。有关更多信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“指定驱动程序配置文件的位置”。 ## 在 macOS X 操作系统上创建数据来源名称 在使用数据源名称 (DSN) 连接到数据存储时，请配置 `odbc.ini` 文件以定义 DSN。在 `odbc.ini` 文件中设置属性以创建指定数据存储的连接信息的 DSN。 有关如何配置 `odbc.ini` 文件的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上创建数据源名称” 请在 macOS X 操作系统上使用以下格式。 ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/lib/amazonredshiftodbc.dylib Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下示例显示了 `odbc.ini` 在 macOS X 操作系统上的配置。 ``` [ODBC Data Sources] Amazon_Redshift_dylib=Amazon Redshift DSN for macOS X [Amazon Redshift DSN for macOS X] Driver=/opt/amazon/redshift/lib/amazonredshiftodbc.dylib Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` ## 在 macOS X 操作系统上配置没有 DSN 的连接 要通过不带 DSN 的连接来连接到数据存储，请在 `odbcinst.ini` 文件中定义驱动程序。然后，在应用程序中提供一个无 DSN 的连接字符串。 有关在这种情况下如何配置 `odbcinst.ini` 文件的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上配置没有 DSN 的连接”。。 请在 macOS X 操作系统上使用以下格式。 ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/lib/amazonredshiftodbc.dylib ... ``` 以下示例显示了安装在 macOS X 操作系统默认目录中的驱动程序的 `odbcinst.ini` 配置。 ``` [ODBC Drivers] Amazon RedshiftODBC DSN=Installed [Amazon RedshiftODBC DSN] Description=Amazon Redshift ODBC Driver for macOS X Driver=/opt/amazon/redshift/lib/amazonredshiftodbc.dylib ``` ## 配置环境变量 使用正确的 ODBC 驱动程序管理器加载正确的驱动程序。为此，请设置库路径环境变量。有关更多信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的“在非 Windows 计算机上指定 ODBC 驱动程序管理器”。 默认情况下，ODBC 驱动程序管理器将配置为使用主目录中隐藏的 `odbc.ini` 和 `odbcinst.ini` 配置文件版本（名为 .`odbc.ini` 和 .`odbcinst.ini`）。它们也被配置为使用驱动程序安装目录的 `/lib` 子文件夹中的 `amazon.redshiftodbc.ini` 文件。如果您将这些配置文件存储在其他位置，请设置环境变量，以便驱动程序管理器能够找到这些文件。有关更多信息，请参阅《Amazon Redshift ODBC 连接器安装和配置指南**中的“指定驱动程序配置文件的位置”。 ## 配置连接功能 可以为 ODBC 设置配置以下连接功能： + 配置 ODBC 驱动程序以提供凭证并验证与 Amazon Redshift 数据库的连接。 + 如果要连接到启用了 SSL 的 Amazon Redshift 服务器，请将 ODBC 驱动程序配置为连接到启用了安全套接字层 (SSL) 的套接字。 + 将 ODBC 驱动程序配置为通过代理服务器连接到 Amazon Redshift。 + 将 ODBC 驱动程序配置为使用查询处理模式来防止查询占用过多内存。 + 将 ODBC 驱动程序配置为通过代理服务器传递 IAM 身份验证过程。 + 将 ODBC 驱动程序配置为使用 TCP Keepalive 来防止连接超时。 有关这些连接功能的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 # ODBC 驱动程序选项 可以使用配置选项来控制 Amazon Redshift ODBC 驱动程序的行为。 在 Microsoft Windows 中，您通常可以在配置数据源名称 (DSN) 时设置驱动程序选项。您还能在以编程方式连接时，或者通过在 `HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\your_DSN` 中添加或更改注册表项来设置驱动程序选项。有关配置 DSN 的更多信息，请参阅[在 Microsoft Windows 上使用 Amazon Redshift ODBC 驱动程序](install-odbc-driver-windows.md)。 在 macOS X 中，您可以在 `odbc.ini` 和 `amazon.redshiftodbc.ini` 文件中设置驱动程序配置选项，如 [使用 ODBC 驱动程序管理器配置驱动程序使用 ODBC 驱动程序管理器配置驱动程序](odbc-driver-configure-mac.md) 中所述。在 `amazon.redshiftodbc.ini` 文件中设置的配置选项适用于所有连接。相反，`odbc.ini` 文件中的设置配置选项特定于一个连接。在 `odbc.ini` 中设置的配置选项优先于在 `amazon.redshiftodbc.ini` 中设置的配置选项。 有关如何设置 ODBC 驱动程序配置选项的信息，请参阅 [Amazon Redshift ODBC 连接器安装和配置指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 # 早期 ODBC 驱动程序版本 仅当您的工具需要使用某个特定版本的驱动程序时，才能下载 Amazon Redshift ODBC 驱动程序的以前版本。 ## 适用于 Windows 的早期 ODBC 驱动程序版本 以下是 64 位驱动程序： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC64-1.6.3.1006.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC64-1.6.3.1006.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC64-1.6.1.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC64-1.6.1.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC64-1.5.20.1024.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC64-1.5.20.1024.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC64-1.5.16.1019.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC64-1.5.16.1019.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC64-1.5.9.1011.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC64-1.5.9.1011.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC64-1.5.7.1007.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC64-1.5.7.1007.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC64-1.4.65.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC64-1.4.65.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC64-1.4.62.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC64-1.4.62.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC64-1.4.59.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC64-1.4.59.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC64-1.4.56.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC64-1.4.56.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.53.1000/AmazonRedshiftODBC64-1.4.53.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.53.1000/AmazonRedshiftODBC64-1.4.53.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC64-1.4.52.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC64-1.4.52.1000.msi) 32 位驱动程序已停用，并且早期版本不受支持。 ## 适用于 Linux 的早期 ODBC 驱动程序版本 以下是 64 位驱动程序版本： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit-1.6.3.1006-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit-1.6.3.1006-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit-1.6.1.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit-1.6.1.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-64-bit-1.5.20.1024-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-64-bit-1.5.20.1024-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-64-bit-1.5.16.1019-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-64-bit-1.5.16.1019-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-64-bit-1.5.9.1011-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-64-bit-1.5.9.1011-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-64-bit-1.5.7.1007-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-64-bit-1.5.7.1007-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-64-bit-1.4.65.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-64-bit-1.4.65.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-64-bit-1.4.62.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-64-bit-1.4.62.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86\$164.deb](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86_64.deb) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86\$164.deb](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86_64.deb) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86\$164.deb](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.deb) 32 位驱动程序已停用，并且早期版本不受支持。 ## 适用于 macOS X 的早期 ODBC 驱动程序版本 以下是适用于 macOS X 的 Amazon Redshift ODBC 驱动程序版本： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit.1.6.3.1006.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit.1.6.3.1006.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit.1.6.1.1000.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit.1.6.1.1000.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.arm64.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.arm64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-1.5.16.1019.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-1.5.16.1019.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-1.5.9.1011.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-1.5.9.1011.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-1.5.7.1007.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-1.5.7.1007.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-1.4.65.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-1.4.65.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-1.4.62.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-1.4.62.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-1.4.59.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-1.4.59.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-1.4.56.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-1.4.56.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-1.4.52.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-1.4.52.1000.dmg) # 配置连接的安全选项 Amazon Redshift 支持安全套接字层 (SSL) 连接来加密数据和服务器证书，以验证客户端连接到的服务器证书。 ## SSL 为了支持 SSL 连接，Amazon Redshift 会在每个集群中创建并安装 [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) 颁发的 SSL 证书。ACM 证书受到大多数操作系统、Web 浏览器和客户端的公开信任。如果您的 SQL 客户端或应用程序使用 SSL 连接到 Amazon Redshift，并且 `sslmode` 连接选项设置为 `require`、`verify-ca` 或 `verify-full`，则您可能需要下载证书捆绑包。如果您的客户需要，Amazon Redshift 会提供如下捆绑证书： + 捆绑包下载地址：[https://s3.amazonaws.com/redshift-downloads/amazon-trust-ca-bundle.crt](https://s3.amazonaws.com/redshift-downloads/amazon-trust-ca-bundle.crt)。 + 预期的 MD5 校验码为 418dea9b6d5d5d5de7a8f1ac42e164cdcf。 + sha256 校验码为 36dba8e4b8041cd14b9d601593963301bcbb92e1c456847784de2acb5bd550。 不要使用位于 `https://s3.amazonaws.com/redshift-downloads/redshift-ca-bundle.crt` 的之前的证书捆绑包。 + 在中国 AWS 区域，请从以下网址下载捆绑包：[https://s3---cn-north-1.amazonaws.com.rproxy.govskope.us.cn/redshift-downloads-cn/amazon-trust-ca-bundle.crt](https://s3---cn-north-1.amazonaws.com.rproxy.govskope.us.cn/redshift-downloads-cn/amazon-trust-ca-bundle.crt)。 + 预期的 MD5 校验码为 418dea9b6d5d5d5de7a8f1ac42e164cdcf。 + sha256 校验码是 36dba8e4b8041cd14b9d601593963301bcbb92e1c456847784de2acb5bd550。 不要使用位于 `https://s3---cn-north-1.amazonaws.com.rproxy.govskope.us.cn/redshift-downloads-cn/redshift-ca-bundle.crt` 和 `https://s3---cn-north-1.amazonaws.com.rproxy.govskope.us.cn/redshift-downloads-cn/redshift-ssl-ca-cert.pem` 的以前的证书捆绑包 **重要** Amazon Redshift 改变了我们管理 SSL 证书的方法。您可能需要更新当前的信任根 CA 证书，才能继续使用 SSL 连接集群。有关更多信息，请参阅 [将 SSL 连接过渡到 ACM 证书](connecting-transitioning-to-acm-certs.md)。 默认情况下，无论连接是否使用 SSL，集群数据库都会接受该连接。要将您的集群配置为需要使用 SSL 连接，请在与集群关联的参数组中将 `require_SSL` 参数设置为 `true`。 Amazon Redshift 支持符合联邦信息处理标准 (FIPS) 140-2 的 SSL 模式。符合 FIPS 的 SSL 模式在默认情况下处于禁用状态。 **重要** 仅在您的系统需要与 FIPS 兼容时才启用与 FIPS 兼容的 SSL 模式。 要启用符合 FIPS 的 SSL 模式，请在与 Amazon Redshift 集群或 Redshift Serverless 工作组关联的参数组中，将 `use_fips_ssl` 参数和 `require_SSL` 参数设置为 `true`。有关修改集群上的参数组的信息，请参阅 [Amazon Redshift 参数组](working-with-parameter-groups.md)。有关修改工作组上的参数组的信息，请参阅[配置与 Amazon Redshift Serverless 的符合 FIPS 的 SSL 连接](serverless-connecting.md#serverless_secure-fips-ssl)。 Amazon Redshift 支持 Elliptic Curve Diffie—Hellman Ephemeral (ECDHE) 密钥协商协议。ECDHE 使得客户端和服务器各有一个椭圆曲线公有/私有密钥对，用来在不安全的通道上创建共享密钥。您无需在 Amazon Redshift 中进行任何配置即可启用 ECDHE。如果您从使用 ECDHE 来加密客户端与服务器间通信的 SQL 客户端工具进行连接，则 Amazon Redshift 将使用提供的密码列表来建立合适的连接。有关更多信息，请参阅 Wikipedia 上的 [Elliptic curve diffie—hellman](https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman) 和 OpenSSL 网站上的[密码](https://www.openssl.org/)。 ## ODBC 中的 SSL 和信任 CA 证书 如果您使用最新 Amazon Redshift ODBC 驱动程序 (1.3.7.1000 版或更高版本) 连接，则可以跳过此部分。要下载最新驱动程序，请参阅[为 Amazon Redshift 配置 ODBC 驱动程序版本 2.x 连接](odbc20-install.md)。 您可能需要更新当前的信任根 CA 证书，才能继续使用 SSL 连接集群。有关更多信息，请参阅 [SSL](#connect-using-ssl)。 您可以验证下载的证书是否与此预期的 MD5 校验和码匹配。为此，您可以在 Linux 操作系统上使用 Md5sum 程序，或者在 Windows 和 macOS X 操作系统上使用其他工具。 ODBC DSN 中的 `sslmode` 设置用于确定如何处理客户端连接加密和服务器证书验证。Amazon Redshift 支持客户端连接中的以下 `sslmode` 值： + `disable` SSL 处于禁用状态，且连接未加密。 + `allow` 如果服务器需要，则使用 SSL。 + `prefer` 如果服务器支持，则使用 SSL。Amazon Redshift 支持 SSL，因此您可以在将 `sslmode` 设置为 `prefer` 时使用 SSL。 + `require` 需要使用 SSL。 + `verify-ca` 必须使用 SSL，且必须验证服务器证书。 + `verify-full` 必须使用 SSL。必须验证服务器证书，且服务器主机名必须与证书上的主机名属性一致。 您可以确定是否使用了 SSL 以及是否在客户端和服务器之间的连接中验证了服务器证书。为此，您需要查看客户端上 ODBC DSN 的 `sslmode` 设置以及服务器上 Amazon Redshift 集群的 `require_SSL` 设置。下表介绍了各种客户端与服务器设置组合的加密结果： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/connecting-ssl-support.html) ### 在 Microsoft Windows 上使用服务器证书和 ODBC 进行连接 如果要使用 SSL 和服务器证书连接到集群，请先将证书下载到客户端计算机或 Amazon EC2 实例。然后配置 ODBC DSN。 1. 将 Amazon Redshift 证书颁发机构包下载到客户端计算机上的驱动程序安装目录中的 `lib` 文件夹，然后将该文件另存为 `root.crt`。有关下载信息，请参阅[SSL](#connect-using-ssl)。 1. 打开 **ODBC Data Source Administrator**，然后添加或编辑 ODBC 连接的系统 DSN 条目。对于 **SSL Mode**，如果不使用 DNS 别名，请选择 `verify-full`。如果您使用 DNS 别名，请选择 `verify-ca`。然后选择**保存**。 有关配置 ODBC DSN 的更多信息，请参阅[为 Amazon Redshift 配置 ODBC 驱动程序版本 2.x 连接](odbc20-install.md)。 ## Java 中的 SSL 和服务器证书 SSL 通过加密可在您的客户端与集群之间移动的数据来提供一个安全层。使用服务器证书可验证集群是否为 Amazon Redshift 集群，从而提供一个额外的安全层。具体方法是，检查自动安装在您预配置的所有集群上的服务器证书。有关将服务器证书 JDBC 一起使用的更多信息，请转到 PostgreSQL 文档中的[配置客户端](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client)。 ### 在 Java 中使用信任 CA 证书以进行连接 **重要** Amazon Redshift 改变了我们管理 SSL 证书的方法。您可能需要更新当前的信任根 CA 证书，才能继续使用 SSL 连接集群。有关更多信息，请参阅 [SSL](#connect-using-ssl)。 **使用信任 CA 证书进行连接** 您可以使用 `redshift-keytool.jar` 文件将 Amazon Redshift 证书颁发机构包中的 CA 证书导入 Java 信任存储库或您的私有信任存储库中。 1. 如果您使用 Java 命令行 `-Djavax.net.ssl.trustStore` 选项，请尽量将其从命令行中删除。 1. 下载 [redshift-keytool.jar](https://s3.amazonaws.com/redshift-downloads/redshift-keytool.jar)。 1. 请执行下列操作之一： + 要将 Amazon Redshift 证书颁发机构捆绑包导入 Java 信任存储库中，请运行以下命令。 ``` java -jar redshift-keytool.jar -s ``` + 要将 Amazon Redshift 证书颁发机构捆绑包导入您的私有信任存储库中，请运行以下命令： ``` java -jar redshift-keytool.jar -k -p ``` # 将 SSL 连接过渡到 ACM 证书 Amazon Redshift 正将您的集群中的 SSL 证书替换为 [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) 颁发的证书。ACM 是一个可信的公有证书颁发机构 (CA)，受当前大多数系统信任。您可能需要更新当前的信任根 CA 证书，才能继续使用 SSL 连接集群。 仅当满足以下所有条件时，此更改才会影响到您： + 您的 SQL 客户端或应用程序使用 SSL 连接 Amazon Redshift 集群，并将 `sslMode` 连接选项设置为 `require`、`verify-ca` 或 `verify-full` 配置选项。 + 您不使用 Amazon Redshift ODBC 或 JDBC 驱动程序，或者您使用的是 ODBC 版本 1.3.7.1000 或 JDBC 版本 1.2.8.1005 之前的 Amazon Redshift 驱动程序。 如果此更改影响到您的 Amazon Redshift 商业区域，那么您必须在 2017 年 10 月 23 日之前更新当前的信任根 CA 证书。Amazon Redshift 会在现在至 2017 年 10 月 23 日之间将您的集群过渡为使用 ACM 证书。该更改对您集群的性能或可用性应该影响不大或者没有任何影响。 如果此更改对 AWS GovCloud (US)（美国）区域产生影响，则必须在 2020 年 4 月 1 日之前更新当前的信任根 CA 证书，以避免服务中断。从该日期开始，使用 SSL 加密连接来连接到 Amazon Redshift 集群的客户端需要额外的受信任的证书颁发机构 (CA)。当客户端连接到 Amazon Redshift 集群时，将使用受信任的证书颁发机构来确认该集群的身份。您需要执行相应操作来更新 SQL 客户端和应用程序，以使用包含新的受信任 CA 的更新的证书包。 **重要** 2021 年 1 月 5 日，在中国区域，Amazon Redshift 正在将您的集群中的 SSL 证书替换为 AWS Certificate Manager (ACM) 颁发的证书。如果此更改对中国（北京）区域或中国（宁夏）区域产生影响，则必须在 2021 年 1 月 5 日之前更新当前的信任根 CA 证书，以避免服务中断。从该日期开始，使用 SSL 加密连接来连接到 Amazon Redshift 集群的客户端需要额外的受信任的证书颁发机构 (CA)。当客户端连接到 Amazon Redshift 集群时，将使用受信任的证书颁发机构来确认该集群的身份。您需要执行相应操作来更新 SQL 客户端和应用程序，以使用包含新的受信任 CA 的更新的证书包。 + [使用最新的 Amazon Redshift ODBC 或 JDBC 驱动程序](#connecting-transitioning-to-acm-latest-odbc-jdbc) + [使用较早的 Amazon Redshift ODBC 或 JDBC 驱动程序](#connecting-transitioning-to-acm-earlier-odbc-jdbc) + [使用其他 SSL 连接类型](#connecting-transitioning-to-acm-other-ssl-types) ## 使用最新的 Amazon Redshift ODBC 或 JDBC 驱动程序 首选方法是使用最新的 Amazon Redshift ODBC 或 JDBC 驱动程序。从 ODBC 版本 1.3.7.1000 和 JDBC 版本 1.2.8.1005 开始的 Amazon Redshift 驱动程序可自动管理从 Amazon Redshift 自签名证书到 ACM 证书的过渡。要下载最新驱动程序，请参阅[为 Amazon Redshift 配置 JDBC 驱动程序版本 2.x 连接](jdbc20-install.md)。 如果您使用的是最新的 Amazon Redshift JDBC 驱动程序，最好不要使用 JVM 选项中的 `-Djavax.net.ssl.trustStore`。如果必须使用 `-Djavax.net.ssl.trustStore`，请将 Redshift 证书颁发机构包导入到它指向的信任存储库中。有关下载信息，请参阅[SSL](connecting-ssl-support.md#connect-using-ssl)。有关更多信息，请参阅 [将 Amazon Redshift 证书颁发机构捆绑包导入信任存储库](#importing-the-acm-bundle-to-truststore)。 ## 使用较早的 Amazon Redshift ODBC 或 JDBC 驱动程序 + 如果您的 ODBC DSN 配置了 `SSLCertPath`，请覆盖指定路径中的证书文件。 + 如果未设置 `SSLCertPath`，则请覆盖驱动程序 DLL 位置中名为 `root.crt` 的证书文件。 如果必须使用版本 1.2.8.1005 之前的 Amazon Redshift JDBC 驱动程序，请执行以下操作之一： + 如果您的 JDBC 连接字符串使用 `sslCert` 选项，请删除 `sslCert` 选项。然后，将 Redshift 证书颁发机构包导入到 Java 信任存储库中。有关下载信息，请参阅[SSL](connecting-ssl-support.md#connect-using-ssl)。有关更多信息，请参阅 [将 Amazon Redshift 证书颁发机构捆绑包导入信任存储库](#importing-the-acm-bundle-to-truststore)。 + 如果您使用 Java 命令行 `-Djavax.net.ssl.trustStore` 选项，请尽量将其从命令行中删除。然后，将 Redshift 证书颁发机构包导入到 Java 信任存储库中。有关下载信息，请参阅[SSL](connecting-ssl-support.md#connect-using-ssl)。有关更多信息，请参阅 [将 Amazon Redshift 证书颁发机构捆绑包导入信任存储库](#importing-the-acm-bundle-to-truststore)。 ### 将 Amazon Redshift 证书颁发机构捆绑包导入信任存储库 您可以使用 `redshift-keytool.jar` 将 Amazon Redshift 证书颁发机构包中的 CA 证书导入 Java 信任存储库或您的私有信任存储库中。 **要将 Amazon Redshift 证书颁发机构捆绑包导入信任存储库** 1. 下载 [redshift-keytool.jar](https://s3.amazonaws.com/redshift-downloads/redshift-keytool.jar)。 1. 请执行下列操作之一： + 要将 Amazon Redshift 证书颁发机构捆绑包导入 Java 信任存储库中，请运行以下命令。 ``` java -jar redshift-keytool.jar -s ``` + 要将 Amazon Redshift 证书颁发机构捆绑包导入您的私有信任存储库中，请运行以下命令： ``` java -jar redshift-keytool.jar -k -p ``` ## 使用其他 SSL 连接类型 如果您使用以下任何方式进行连接，请执行本部分中的步骤： + 开源 ODBC 驱动程序 + 开源 JDBC 驱动程序 + [Amazon Redshift RSQL](https://docs.aws.amazon.com/redshift/latest/mgmt/rsql-query-tool.html) 命令行界面 + 基于 libpq 的任何语言绑定，如 psycopg2 (Python) 和 ruby-pg (Ruby) **将 ACM 证书与其他 SSL 连接类型结合使用：** 1. 下载 Amazon Redshift 证书颁发机构捆绑包。有关下载信息，请参阅[SSL](connecting-ssl-support.md#connect-using-ssl)。 1. 将包中的证书放入您的 `root.crt` 文件中。 + 在 Linux 和 macOS X 操作系统中，该文件为 `~/.postgresql/root.crt`。 + 在 Microsoft Windows 上，该文件为 `%APPDATA%\postgresql\root.crt`。 # 通过客户端工具和代码连接 Amazon Redshift 提供 Amazon Redshift 查询编辑器 v2，用于连接到您的集群和工作组。有关更多信息，请参阅 [使用查询编辑器 v2 查询数据库使用 Amazon Redshift 查询编辑器 v2 查询数据库](query-editor-v2.md)。 此部分提供了一些用于第三方工具连接的选项。另外，此部分还介绍了如何以编程方式连接到您的集群。 **Topics** + [使用 Amazon Redshift RSQL 连接](rsql-query-tool.md) + [使用 Amazon Redshift RSQL 连接到集群](rsql-query-tool-starting-tool-connection.md) + [Amazon Redshift RSQL 元命令](rsql-query-tool-commands.md) + [Amazon Redshift RSQL 变量](rsql-query-tool-variables.md) + [Amazon Redshift RSQL 错误代码](rsql-query-tool-error-codes.md) + [Amazon Redshift RSQL 环境变量](rsql-query-tool-environment-variables.md) # 使用 Amazon Redshift RSQL 连接 Amazon Redshift RSQL 是一个命令行客户端，用于与 Amazon Redshift 集群和数据库进行交互。您可以连接到 Amazon Redshift 集群、描述数据库对象、查询数据以及查看各种输出格式的查询结果。 Amazon Redshift RSQL 支持 PostgreSQL psql 命令行工具的功能以及特定于 Amazon Redshift 的额外功能。这些功能包括： + 您可以使用 AD FS、PingIdentity、Okta、Azure ADm 或其它基于 SAML/JWT 的身份提供者实现单点登录身份验证。您还可以使用基于浏览器的 SAML 身份提供者进行多重身份验证（MFA）。 + 您可以描述 Amazon Redshift 对象的特性或属性，例如表分发键、表排序键、后期绑定视图（LBV）和实体化视图。您还可以描述 AWS Glue 目录或 Apache Hive Metastore 中外部表的特性或属性、Amazon RDS for PostgreSQL、Amazon Aurora PostgreSQL 兼容版、RDS for MySQL（预览版）和 Amazon Aurora MySQL 兼容版（预览版）中的外部数据库，以及使用 Amazon Redshift 数据共享共享的表。 + 您还可以使用增强的控制流命令，例如 `IF`（`\ELSEIF`、`\ELSE,` `\ENDIF`）`\GOTO` 和 `\LABEL`。 借助 Amazon Redshift RSQL 批处理模式（运行作为输入参数传递的脚本），您可以运行包含 SQL 和复杂业务逻辑的脚本。如果您有现有的自我管理的本地数据仓库，您可以使用 Amazon Redshift RSQL 替换现有的提取、转换、加载（ETL）和自动化脚本，例如 Teradata BTEQ 脚本。使用 RSQL 有助于避免以过程语言手动重新实现脚本。 Amazon Redshift RSQL 适用于 Linux、Windows 和 macOS X 操作系统。 如需报告 Amazon Redshift RSQL 的问题，请发送邮件至 redshift-rsql-support@amazon.com。 **Topics** + [Amazon Redshift RSQL 入门](rsql-query-tool-getting-started.md) + [Amazon Redshift RSQL 更改日志](rsql-query-tool-changelog.md) # Amazon Redshift RSQL 入门 在具有 Linux、macOS 或微软 Windows 操作系统的计算机上安装 Amazon Redshift RSQL。 ## 下载 RSQL + Linux 64 位 RPM：[RSQL 版本 1.1.2](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2.rhel.x86_64.rpm) + Linux 构件签名密钥：[密钥](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2-certificate.pem) + Linux 构件签名哈希：[哈希](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2-signature.bin) + Mac OS 64 位 PKG：[RSQL 版本 1.1.2](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2.universal.pkg) + Windows 64 位 MSI：[RSQL 版本 1.1.2](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2.x86_64.msi) 请在 [Amazon Redshift RSQL 更改日志](rsql-query-tool-changelog.md)中参阅以前版本的更改日志和下载。 ## 安装适用于 Linux 的 RSQL 请按照以下步骤，安装适用于 Linux 的 RSQL。 1. 使用以下命令安装驱动程序： ``` sudo yum install unixODBC ``` 1. 安装 ODBC 驱动程序：[下载并安装 Amazon Redshift ODBC 驱动程序下载并安装 ODBC 驱动程序](odbc20-install-linux.md)。 1. 将 ini 文件复制到您的主目录： ``` cp /opt/amazon/redshiftodbcx64/odbc.ini ~/.odbc.ini ``` 1. 将环境变量设置为指向文件的位置： ``` export ODBCINI=~/.odbc.ini export ODBCSYSINI=/opt/amazon/redshiftodbcx64/ export AMAZONREDSHIFTODBCINI=/opt/amazon/redshiftodbcx64/amazon.redshiftodbc.ini ``` 1. 现在，您可以通过运行以下命令安装 RSQL。 ``` sudo rpm -i AmazonRedshiftRsql-.rhel.x86_64.rpm ``` ## 安装适用于 Mac 的 RSQL 请按照以下步骤操作，安装适用于 Mac OSX 的 RSQL。 1. 使用以下命令安装驱动程序： ``` brew install unixodbc --build-from-source ``` 1. 安装 ODBC 驱动程序：[下载并安装 Amazon Redshift ODBC 驱动程序下载并安装 ODBC 驱动程序](odbc-driver-mac-how-to-install.md)。 1. 将 ini 文件复制到您的主目录： ``` cp /opt/amazon/redshift/Setup/odbc.ini ~/.odbc.ini ``` 1. 将环境变量设置为指向文件的位置： ``` export ODBCINI=~/.odbc.ini export ODBCSYSINI=/opt/amazon/redshift/Setup export AMAZONREDSHIFTODBCINI=/opt/amazon/redshift/lib/amazon.redshiftodbc.ini ``` 1. 如果它不在`/usr/local/lib` 中，则将 `DYLD_LIBRARY_PATH` 设置为 libodbc.dylib 的位置。 ``` export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/usr/local/lib ``` 1. 双击 pkg 文件运行安装程序。 1. 按照安装向导中的步骤完成安装。同意许可协议条款。 ## 安装适用于 Windows 的 RSQL 请按照以下步骤操作，安装适用于 Windows 的 RSQL。 1. 安装 ODBC 驱动程序：[下载并安装 Amazon Redshift ODBC 驱动程序下载并安装 ODBC 驱动程序](odbc-driver-windows-how-to-install.md)。 1. 请双击 RSQL 下载文件，以运行安装程序，然后按照提示完成安装。 # Amazon Redshift RSQL 更改日志 *1.1.2（2025-12-11）* 错误修复 + 修复了一个错误，该错误会导致 \$1goto 和 \$1label 命令失败。 + 修复了一个错误，当变量被引号引起来时，该错误会导致 RSQL 无法打印变量值。 + 修复了一个错误，在启用 UseDeclareFetch 后，如果查询结果超过 ODBC DSN Fetch 参数大小，该错误会导致 RSQL 发生崩溃。 + 修复了一个问题，即便已启用分页程序，该问题也会导致一次性返回多个结果页。 + 修复了一个错误，在事务块内的查询失败时，该错误会导致 RSQL 发生崩溃。 *1.1.1（2025-11-20）* 错误修复 + 修复了一个问题，在使用 -c 标志时，该问题会导致 RSQL 错误地解析查询。此修复适用于所有平台。 + 修复了 Mac 上的一个错误，该错误导致用户无法在 RSQL 中使用 \$1s 命令。 *1.1.0（2025-11-11）* 错误修复 + 解决了导致 RSQL 中意外发生崩溃的内存泄漏问题。 + 从 RSQL 中移除了 OpenSSL 依赖项。 + 修复了同一环境中的 libpq/psql 安装存在的链接冲突问题。 + 提升了针对 Amazon Linux 2023、Windows 和 macOS 的平台兼容性。 + 修复了一个问题，当输出超出当前显示大小时，该问题会导致输出被截断。 *1.0.8 (2023-06-19)* 错误修复 + 修复了使用 SHOW 命令时会截断输出的问题。 + 为 \$1de 添加了用于描述外部 Kinesis 流和 Kafka 主题的支持。 *1.0.7 (2023-03-22)* 错误修复 + 修复了 RSQL 无法描述实体化视图的问题。 + 修复了使用 Amazon Redshift Serverless 时 stl\$1connection\$1log 上出现的权限被拒绝错误。 + 修复了 RSQL 可能不正确地处理 \$1GOTO 标签的问题。 + 修复了在静默模式下输出 SSL 消息的问题。 + 修复了描述存储过程时显示随机字符的问题。 + 修复了重复输出 ERROR/INFO 消息的问题。 New + RSQL 现在可以直接从 ODBC 驱动程序获取 SSL 信息。 *1.0.6 (2023-02-21)* 错误修复 + 修复了在 Redshift 补丁 1.0.46086 (P173) 上，\$1d 引发错误（整数的输入语法无效："xid"）的问题。 New + 已重命名安装文件来体现支持的架构。 *1.0.5（2022 年 6 月 27 日）* 错误修复 + 将 SQL 错误消息发送到标准错误 (stderr)。 + 修复了使用 ON\$1ERROR\$1STOP 时退出代码的问题。现在，脚本将在遇到错误后终止，并返回正确的退出代码。 + Maxerror 现在不区分大小写。 New + 增加了对 ODBC 2.x 驱动程序的支持。 *1.0.4 (2022-03-19)* + 添加对 RSPASSWORD 环境变量的支持。设置密码以连接到 Amazon Redshift。例如 `export RSPASSWORD=TestPassw0rd`。 *1.0.3（2021 年 12 月 8 日）* 错误修复 + 修复了在 Windows 操作系统中使用 `\c` 或 `\logon` 切换数据库时弹出的对话框。 + 修复了检查 ssl 信息时发生的崩溃。 ## Amazon Redshift RSQL 的以前版本 请根据您的操作系统，选择其中一个链接以下载所需的 Amazon Redshift RSQL 版本。 **Linux 64 位 RPM** + [RSQL 版本 1.1.1](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.1/AmazonRedshiftRsql-1.1.1.rhel.x86_64.rpm) + [RSQL 版本 1.1.0](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.0/AmazonRedshiftRsql-1.1.0.rhel.x86_64.rpm) + [RSQL 版本 1.0.8](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.8/AmazonRedshiftRsql-1.0.8.x86_64.rpm) + [RSQL 版本 1.0.7](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.7/AmazonRedshiftRsql-1.0.7.x86_64.rpm) + [RSQL 版本 1.0.6](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.6/AmazonRedshiftRsql-1.0.6.x86_64.rpm) + [RSQL 版本 1.0.5](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.5/AmazonRedshiftRsql-1.0.5-1.x86_64.rpm) + [RSQL 版本 1.0.4](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.4/AmazonRedshiftRsql-1.0.4-1.x86_64.rpm) + [RSQL 版本 1.0.3](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.3/AmazonRedshiftRsql-1.0.3-1.x86_64.rpm) + [RSQL 版本 1.0.1](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.1/AmazonRedshiftRsql-1.0.1-1.x86_64.rpm) **Mac OS 64 位 DMG/PKG** + [RSQL 版本 1.1.1](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.1/AmazonRedshiftRsql-1.1.1.universal.pkg) + [RSQL 版本 1.1.0](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.0/AmazonRedshiftRsql-1.1.0.universal.pkg) + [RSQL 版本 1.0.8](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.8/AmazonRedshiftRsql-1.0.8.x86_64.dmg) + [RSQL 版本 1.0.7](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.7/AmazonRedshiftRsql-1.0.7.x86_64.dmg) + [RSQL 版本 1.0.6](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.6/AmazonRedshiftRsql-1.0.6.x86_64.dmg) + [RSQL 版本 1.0.5](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.5/AmazonRedshiftRsql-1.0.5.dmg) + [RSQL 版本 1.0.4](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.4/AmazonRedshiftRsql-1.0.4.dmg) + [RSQL 版本 1.0.3](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.3/AmazonRedshiftRsql-1.0.3.dmg) + [RSQL 版本 1.0.1](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.1/AmazonRedshiftRsql-1.0.1.dmg) **Windows 64 位 MSI** + [RSQL 版本 1.1.1](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.1/AmazonRedshiftRsql-1.1.1.x86_64.msi) + [RSQL 版本 1.1.0](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.0/AmazonRedshiftRsql-1.1.0.x86_64.msi) + [RSQL 版本 1.0.8](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.8/AmazonRedshiftRsql-1.0.8.x86_64.msi) + [RSQL 版本 1.0.7](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.7/AmazonRedshiftRsql-1.0.7.x86_64.msi) + [RSQL 版本 1.0.6](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.6/AmazonRedshiftRsql-1.0.6.x86_64.msi) + [RSQL 版本 1.0.5](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.5/AmazonRedshiftRsql-1.0.5.msi) + [RSQL 版本 1.0.4](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.4/AmazonRedshiftRsql-1.0.4.msi) + [RSQL 版本 1.0.3](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.3/AmazonRedshiftRsql-1.0.3.msi) + [RSQL 版本 1.0.1](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.1/AmazonRedshiftRsql-1.0.1.msi) # 使用 Amazon Redshift RSQL 连接到集群 使用 Amazon Redshift，您可以连接到集群并使用 RSQL 与之交互。这是一个命令行工具，提供了一种安全的方式来查询数据、创建数据库对象和管理 Amazon Redshift 集群。以下各节将指导您完成使用 RSQL（带或不带数据来源名称（DSN））与集群建立连接的步骤。 ## 在没有 DSN 的情况下连接 1. 在 Amazon Redshift 控制台上，选择要连接到的集群，然后记下端点、数据库和端口。 1. 在命令提示符下，使用命令行参数指定连接信息。 ``` rsql -h -U -d -p ``` 在这里，以下内容适用： + ** 是您在上一步中记录的**端点**。 + ** 是有权连接到集群的用户。 + ** 是您在上一步中记录的**数据库名称**。 + ** 是您在上一步中记录的**端口**。** 是一个可选参数。 以下为示例。 ``` rsql -h testcluster.example.amazonaws.com -U user1 -d dev -p 5439 ``` 1. 在密码提示符处，输入 ** 用户的密码。 成功的连接响应如下所示。 ``` % rsql -h testcluster.example.com -d dev -U user1 -p 5349 Password for user user1: DSN-less Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# ``` 要连接的命令在 Linux、Mac OS 和 Windows 上具有相同的参数。 ## 在使用 DSN 的情况下连接 可以使用 DSN 将 RSQL 连接到 Amazon Redshift，以简化连接属性的整理方式。本主题包括 ODBC 驱动程序安装说明和 DSN 属性的描述。 ### 使用带密码的 DSN 连接 下面显示使用密码的 DSN 连接配置的示例。对于 Mac OSX 而言，默认 `` 为 `/opt/amazon/redshift/lib/libamazonredshiftodbc.dylib`，对于 Linux 而言，则为 `/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so`。 ``` [testuser] Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so SSLMode=verify-ca Min_TLS=1.2 boolsaschar=0 Host= Port= Database= UID= PWD= sslmode=prefer ``` 连接成功后，输出结果如下。 ``` % rsql -D testuser DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# ``` ### 使用单点登录 DSN 您可以配置 DSN 以进行单点登录身份验证。下面显示使用 Okta 单点登录的 DSN 连接配置的示例。 ``` [testokta] Driver= SSLMode=verify-ca Min_TLS=1.2 boolsaschar=0 Host= clusterid= region= Database= locale=en-US iam=1 plugin_name= uid= pwd= idp_host= app_id= app_name= preferred_role= ``` 成功连接的输出示例。 ``` % rsql -D testokta DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# ``` 下面显示使用 Azure 单点登录的 DSN 连接配置的示例。 ``` [testazure] Driver= SSLMode=verify-ca Min_TLS=1.2 boolsaschar=0 Host= Port= clusterid= region= Database= locale=en-us iam=1 plugin_name= uid= pwd= idp_tenant= client_id= client_secret= ``` ### 将 DSN 连接与 IAM 配置文件结合使用 您可以使用配置的 IAM 配置文件连接到 Amazon Redshift。IAM 配置文件必须具有调用 `GetClusterCredentials` 的权限。以下示例演示了要使用的 DSN 属性。仅当 `Host` 不是 Amazon 提供的端点（如 `examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com`）时，才需要 `ClusterID` 和 `Region` 参数。 ``` [testiam] Driver=Default Host=testcluster.example.com Database=dev DbUser=testuser ClusterID=rsqltestcluster Region=us-east-1 IAM=1 Profile=default ``` `Profile` 密钥的值是您从 AWS CLI 凭证中选择的命名配置文件。此示例显示名为 `default` 的配置文件的凭证。 ``` $ cat .aws/credentials [default] aws_access_key_id = ASIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` 下面显示的是连接响应。 ``` $ rsql -D testiam DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) testuser@dev=> ``` ### 将 DSN 连接与实例配置文件结合使用 您可以使用 Amazon EC2 实例配置文件连接到 Amazon Redshift。实例配置文件必须具有调用 `GetClusterCredentials` 的权限。有关要使用的 DSN 属性，请参阅下面的示例。仅当 `Host` 不是 Amazon 提供的端点（如 `examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com`）时，才需要 `ClusterID` 和 `Region` 参数。 ``` [testinstanceprofile] Driver=Default Host=testcluster.example.com Database=dev DbUser=testuser ClusterID=rsqltestcluster Region=us-east-1 IAM=1 Instanceprofile=1 ``` 下面显示的是连接响应。 ``` $ rsql -D testinstanceprofile DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) testuser@dev=> ``` ### 将 DSN 连接与默认凭证提供程序链结合使用 要使用默认凭证提供程序链进行连接，请仅指定 IAM 属性，Amazon Redshift RSQL 将尝试按照适用于 Java 的 AWS SDK 中[使用 AWS 凭证](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)所述的顺序获取凭证。链中必须至少一个提供程序具有 `GetClusterCredentials` 权限。例如，这对于从 ECS 容器进行连接非常有用。 ``` [iamcredentials] Driver=Default Host=testcluster.example.com Database=dev DbUser=testuser ClusterID=rsqltestcluster Region=us-east-1 IAM=1 ``` # Amazon Redshift RSQL 元命令 Amazon Redshift RSQL 元命令返回有关数据库或特定数据库对象的信息性记录。结果可以包括各种列和元数据。其他命令会执行特定操作。这些命令的前面都有反斜杠。 ## \$1d[S\$1] 列出本地用户创建的表、常规视图、后期绑定视图和实体化视图。`\dS ` 还列出了表和视图，如 `\d`，但系统对象包含在返回的记录中。`+` 为所有列出的对象生成额外的元数据列 `description`。下面显示的是作为命令返回的示例记录。 ``` List of relations schema | name | type | owner --------+-----------+-------+--------- public | category | table | awsuser public | date | table | awsuser public | event | table | awsuser public | listing | table | awsuser public | sales | table | awsuser public | users | table | awsuser public | venue | table | awsuser (7 rows) ``` ## \$1d[S\$1] NAME 描述表、视图或索引。包括列名称和类型。它还提供了 diststyle、备份配置、创建日期（2018 年 10 月之后创建的表）和约束。例如，`\dS+ sample` 返回对象属性。附加 `S+` 会导致返回的记录中包含其它列。 ``` Table "public.sample" Column | Type | Collation | Nullable | Default Value | Encoding | DistKey | SortKey --------+-----------------------------+----------------+----------+---------------+-----------+---------+--------- col1 | smallint | | NO | | none | t | 1 col2 | character(100) | case_sensitive | YES | | none | f | 2 col3 | character varying(100) | case_sensitive | YES | | text32k | f | 3 col4 | timestamp without time zone | | YES | | runlength | f | 0 col5 | super | | YES | | zstd | f | 0 col6 | bigint | | YES | | az64 | f | 0 Diststyle: KEY Backup: YES Created: 2021-07-20 19:47:27.997045 Unique Constraints: "sample_pkey" PRIMARY KEY (col1) "sample_col2_key" UNIQUE (col2) Foreign-key constraints: "sample_col2_fkey" FOREIGN KEY (col2) REFERENCES lineitem(l_orderkey) ``` 表的分布样式或 *Diststyle* 可以是 KEY、AUTO、EVEN 或 ALL。 *备份*指示在拍摄快照时是否备份了表。有效值为 `YES` 或 `NO`。 *已创建*是创建表的时间的时间戳。创建日期不适用于 2018 年 11 月之前创建的 Amazon Redshift 表。在此日期之前创建的表显示 n/a（不可用）。 *独特约束*列出了表中的唯一的主键约束。 *外键约束*列出了表中的外键越塾。 ## \$1dC[\$1] [PATTERN] 列出转换。包括源类型、目标类型以及转换是否为隐式。 以下显示来自 `\dC+` 的结果子集： ``` List of casts source type | target type | function | implicit? | description -----------------------------+-----------------------------+---------------------+---------------+------------- "char" | character | bpchar | in assignment | "char" | character varying | text | in assignment | "char" | integer | int4 | no | "char" | text | text | yes | "path" | point | point | no | "path" | polygon | polygon | in assignment | abstime | date | date | in assignment | abstime | integer | (binary coercible) | no | abstime | time without time zone | time | in assignment | abstime | timestamp with time zone | timestamptz | yes | abstime | timestamp without time zone | timestamp | yes | bigint | bit | bit | no | bigint | boolean | bool | yes | bigint | character | bpchar | in assignment | bigint | character varying | text | in assignment | bigint | double precision | float8 | yes | bigint | integer | int4 | in assignment | bigint | numeric | numeric | yes | bigint | oid | oid | yes | bigint | real | float4 | yes | bigint | regclass | oid | yes | bigint | regoper | oid | yes | bigint | regoperator | oid | yes | bigint | regproc | oid | yes | bigint | regprocedure | oid | yes | bigint | regtype | oid | yes | bigint | smallint | int2 | in assignment | bigint | super | int8_partiql | in assignment | ``` ## \$1dd[S] [PATTERN] 显示在别处未显示的对象描述。 ## \$1de 列出外部表。这包括 AWS Glue Data Catalog 中的表、Hive Metastore 和来自 Amazon RDS/Aurora MySQL、Amazon RDS/Aurora PostgreSQL 和 Amazon Redshift 数据共享表的联合表。 ## \$1de NAME 描述外部表。 以下示例显示 AWS Glue 外部表。 ``` # \de spectrum.lineitem Glue External table "spectrum.lineitem" Column | External Type | Redshift Type | Position | Partition Key | Nullable -----------------+---------------+---------------+----------+---------------+---------- l_orderkey | bigint | bigint | 1 | 0 | l_partkey | bigint | bigint | 2 | 0 | l_suppkey | int | int | 3 | 0 | l_linenumber | int | int | 4 | 0 | l_quantity | decimal(12,2) | decimal(12,2) | 5 | 0 | l_extendedprice | decimal(12,2) | decimal(12,2) | 6 | 0 | l_discount | decimal(12,2) | decimal(12,2) | 7 | 0 | l_tax | decimal(12,2) | decimal(12,2) | 8 | 0 | l_returnflag | char(1) | char(1) | 9 | 0 | l_linestatus | char(1) | char(1) | 10 | 0 | l_shipdate | date | date | 11 | 0 | l_commitdate | date | date | 12 | 0 | l_receiptdate | date | date | 13 | 0 | l_shipinstruct | char(25) | char(25) | 14 | 0 | l_shipmode | char(10) | char(10) | 15 | 0 | l_comment | varchar(44) | varchar(44) | 16 | 0 | Location: s3://redshiftbucket/kfhose2019/12/31 Input_format: org.apache.hadoop.mapred.TextInputFormat Output_format: org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat Serialization_lib: org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe Serde_parameters: {"field.delim":"|","serialization.format":"|"} Parameters: {"EXTERNAL":"TRUE","numRows":"178196721475","transient_lastDdlTime":"1577771873"} ``` Hive Metastore 表。 ``` # \de emr.lineitem Hive Metastore External Table "emr.lineitem" Column | External Type | Redshift Type | Position | Partition Key | Nullable -----------------+---------------+---------------+----------+---------------+---------- l_orderkey | bigint | bigint | 1 | 0 | l_partkey | bigint | bigint | 2 | 0 | l_suppkey | int | int | 3 | 0 | l_linenumber | int | int | 4 | 0 | l_quantity | decimal(12,2) | decimal(12,2) | 5 | 0 | l_extendedprice | decimal(12,2) | decimal(12,2) | 6 | 0 | l_discount | decimal(12,2) | decimal(12,2) | 7 | 0 | l_tax | decimal(12,2) | decimal(12,2) | 8 | 0 | l_returnflag | char(1) | char(1) | 9 | 0 | l_linestatus | char(1) | char(1) | 10 | 0 | l_commitdate | date | date | 11 | 0 | l_receiptdate | date | date | 12 | 0 | l_shipinstruct | char(25) | char(25) | 13 | 0 | l_shipmode | char(10) | char(10) | 14 | 0 | l_comment | varchar(44) | varchar(44) | 15 | 0 | l_shipdate | date | date | 16 | 1 | Location: s3://redshiftbucket/cetas Input_format: org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat Output_format: org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat Serialization_lib: org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe Serde_parameters: {"serialization.format":"1"} Parameters: {"EXTERNAL":"TRUE", "numRows":"4307207", "transient_lastDdlTime":"1626990007"} ``` PostgreSQL 外部表。 ``` # \de pgrsql.alltypes Postgres Federated Table "pgrsql.alltypes" Column | External Type | Redshift Type | Position | Partition Key | Nullable --------+-----------------------------+-----------------------------+----------+---------------+---------- col1 | bigint | bigint | 1 | 0 | col2 | bigint | bigint | 2 | 0 | col5 | boolean | boolean | 3 | 0 | col6 | box | varchar(65535) | 4 | 0 | col7 | bytea | varchar(65535) | 5 | 0 | col8 | character(10) | character(10) | 6 | 0 | col9 | character varying(10) | character varying(10) | 7 | 0 | col10 | cidr | varchar(65535) | 8 | 0 | col11 | circle | varchar(65535) | 9 | 0 | col12 | date | date | 10 | 0 | col13 | double precision | double precision | 11 | 0 | col14 | inet | varchar(65535) | 12 | 0 | col15 | integer | integer | 13 | 0 | col16 | interval | varchar(65535) | 14 | 0 | col17 | json | varchar(65535) | 15 | 0 | col18 | jsonb | varchar(65535) | 16 | 0 | col19 | line | varchar(65535) | 17 | 0 | col20 | lseg | varchar(65535) | 18 | 0 | col21 | macaddr | varchar(65535) | 19 | 0 | col22 | macaddr8 | varchar(65535) | 20 | 0 | col23 | money | varchar(65535) | 21 | 0 | col24 | numeric | numeric(38,20) | 22 | 0 | col25 | path | varchar(65535) | 23 | 0 | col26 | pg_lsn | varchar(65535) | 24 | 0 | col28 | point | varchar(65535) | 25 | 0 | col29 | polygon | varchar(65535) | 26 | 0 | col30 | real | real | 27 | 0 | col31 | smallint | smallint | 28 | 0 | col32 | smallint | smallint | 29 | 0 | col33 | integer | integer | 30 | 0 | col34 | text | varchar(65535) | 31 | 0 | col35 | time without time zone | varchar(65535) | 32 | 0 | col36 | time with time zone | varchar(65535) | 33 | 0 | col37 | timestamp without time zone | timestamp without time zone | 34 | 0 | col38 | timestamp with time zone | timestamp with time zone | 35 | 0 | col39 | tsquery | varchar(65535) | 36 | 0 | col40 | tsvector | varchar(65535) | 37 | 0 | col41 | txid_snapshot | varchar(65535) | 38 | 0 | col42 | uuid | varchar(65535) | 39 | 0 | col43 | xml | varchar(65535) | 40 | 0 | ``` ## \$1df[anptw][S\$1] [PATTERN] 列出各种类型的函数。例如，命令 `\df` 返回函数列表。结果包括名称、返回的数据类型、访问权限和其它元数据等属性。函数类型可以包括触发器、存储过程、窗口函数和其它类型。当您将 `S+` 附加到命令（例如 `\dfantS+`）时，会包含其它元数据列，例如 `owner`、`security` 和 `access privileges`。 ## \$1dL[S\$1] [PATTERN] 列出与数据库关联的过程语言的数据。信息包括名称（例如 plpgsql）和其它元数据，其中包括名称是否受信任、访问权限和描述。例如，示例调用是 `\dLS+`，它列出了语言及其属性。当您将 `S+` 附加到命令时，会包含其它元数据列，例如 `call handler` 和 `access privileges`。 示例结果： ``` List of languages name | trusted | internal language | call handler | validator | access privileges | description -----------+---------+-------------------+-------------------------+------------------------------------------------------------+-------------------+-------------------------------- c | f | t | - | fmgr_c_validator(oid) | | Dynamically-loaded C functions exfunc | f | f | exfunc_call_handler() | - | rdsdb=U/rdsdb | internal | f | t | - | fmgr_internal_validator(oid) | | Built-in functions mlfunc | f | f | mlfunc_call_handler() | - | rdsdb=U/rdsdb | plpgsql | t | f | plpgsql_call_handler() | plpgsql_validator(oid) | | plpythonu | f | f | plpython_call_handler() | plpython_compiler(cstring,cstring,cstring,cstring,cstring) | rdsdb=U/rdsdb | sql | t | t | - | fmgr_sql_validator(oid) | =U/rdsdb | SQL-language functions ``` ## \$1dm[S\$1] [PATTERN] 列出实体化视图。例如，`\dmS+` 列出了实体化视图及其属性。当您将 `S+` 附加到命令时，会包含其它元数据列。 ## \$1dn[S\$1] [PATTERN] 列出架构。当您将 `S+` 附加到命令（例如 `\dnS+`）时，会包含其它元数据列，例如 `description` 和 `access privileges`。 ## \$1dp [PATTERN] 列出表、视图和序列访问权限。 ## \$1dt[S\$1] [PATTERN] 列出表 当您将 `S+` 附加到命令（例如 `\dtS+`）时，会包含其它元数据列，例如本例中的 `description`。 ## \$1du 列出数据库的用户。包括他们的姓名和角色，例如超级用户和属性。 ## \$1dv[S\$1] [PATTERN] 列出视图。包括架构、类型和拥有者数据。当您将 `S+` 附加到命令（例如 `\dvS+`）时，会包含其它元数据列。 ## \$1H 打开 HTML 输出。这对于快速返回格式化的结果非常有用。例如，`select * from sales; \H` 以 HTML 格式返回销售表中的结果。要切换回表格结果，请使用 `\q`，或者无提示。 ## \$1i 从文件中运行命令。例如，假设您的工作目录中有 rsql\$1steps.sql，以下将运行文件中的命令：`\i rsql_steps.sql`。 ## \$1l[\$1] [PATTERN] 列出数据库。包括所有者、编码和其它信息。 ## \$1q 退出，或者 `\q` 命令，注销数据库会话并退出 RSQL。 ## \$1sv[\$1] VIEWNAME 显示视图的定义。 ## \$1timing 例如，显示查询的运行时间。 ## \$1z [PATTERN] 输出与\$1 dp 相同。 ## \$1? 显示帮助信息。可选的参数指定要解释的项目。 ## \$1EXIT 注销所有数据库会话并退出 Amazon Redshift RSQL。此外，您可以指定可选的退出代码。例如，`\EXIT 15` 将退出 Amazon Redshift RSQL 终端并返回退出代码 15。 以下示例显示来自连接的输出并从 RSQL 退出。 ``` % rsql -D testuser DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.34.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# \exit 15 % echo $? 15 ``` ## \$1EXPORT 指定导出文件的名称，RSQL 将该文件用于存储后续 SQL SELECT 语句返回的数据库信息。 export\$101.sql ``` \export report file='E:\\accounts.out' \rset rformat off \rset width 1500 \rset heading "General Title" \rset titledashes on select * from td_dwh.accounts; \export reset ``` 控制台输出 ``` Rformat is off. Target width is 1500. Heading is set to: General Title Titledashes is on. (exported 40 rows) ``` ## \$1LOGON 连接到数据库。您可以使用位置语法指定连接参数或将其指定作为连接字符串。 命令语法如下所示：`\logon {[DBNAME|- USERNAME|- HOST|- PORT|- [PASSWORD]] | conninfo}` `DBNAME` 是要连接的数据库的名称。`USERNAME` 是连接的用户名。默认 `HOST` 为 `localhost`。默认 `PORT` 为 `5439`。 当在 `\LOGON` 命令中指定主机名时，它将成为其它 `\LOGON` 命令的默认主机名。要更改默认主机名，请在附加 `\LOGON` 命令中指定新的 `HOST`。 `user1` 的 `\LOGON` 命令输出示例如下。 ``` (testcluster) user1@redshiftdb=# \logon dev DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 You are now connected to database "dev" as user "user1". (testcluster) user1@dev=# ``` *user2* 的示例输出。 ``` (testcluster) user1@dev=# \logon dev user2 testcluster2.example.com Password for user user2: DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 You are now connected to database "dev" as user "user2" on host "testcluster2.example.com" at port "5439". (testcluster2) user2@dev=# ``` ## \$1REMARK `\echo` 命令的扩展。`\REMARK` 将指定的字符串打印到输出流。`\REMARK ` 通过添加在单独的行上中断输出的能力来扩展 `\echo`。 以下示例显示了命令的输出。 ``` (testcluster) user1@dev=# \remark 'hello//world' hello world ``` ## \$1RSET 该 `\rset` 命令将设置命令参数和变量。`\rset` 还具有交互式模式和批处理模式。它不支持 bash 选项（例如 *-x*）或参数（例如 *--*）。 它设置如下所示的变量： + ERRORLEVEL + HEADING 和 RTITLE + RFORMAT + MAXERROR + TITLEDASHES + WIDTH 以下示例指定一个标题。 ``` \rset heading "Winter Sales Report" ``` 有关如何使用 `\rset` 的更多示例，您可以在 [Amazon Redshift RSQL 变量](rsql-query-tool-variables.md) 主题中查找示例。 ## \$1RUN 运行包含在指定文件中的 Amazon Redshift RSQL 脚本。`\RUN` 通过添加一个选项来跳过文件中的标题行以扩展 `\i` 命令。 如果文件名包含逗号、分号或空格，请用单引号将其括起来。此外，如果文本在文件名后面，请将其括在引号中。在 UNIX 中，文件名区分大小写。在 Windows 中，文件名不区分大小写。 以下示例显示了命令的输出。 ``` (testcluster) user1@dev=# \! cat test.sql select count(*) as lineitem_cnt from lineitem; select count(*) as customer_cnt from customer; select count(*) as orders_cnt from orders; (testcluster) user1@dev=# \run file=test.sql lineitem_cnt -------------- 4307207 (1 row) customer_cnt -------------- 37796166 (1 row) orders_cnt ------------ 0 (1 row) (testcluster) user1@dev=# \run file=test.sql skip=2 2 records skipped in RUN file. orders_cnt ------------ 0 (1 row) ``` ## \$1OS `\!` 命令的别名。`\OS` 运行作为参数传递的操作系统命令。命令运行后，控制将返回到 Amazon Redshift RSQL。例如，您可以运行以下命令以打印当前系统日期时间并返回到 RSQL 终端：`\os date`。 ``` (testcluster) user1@dev=# \os date Tue Sep 7 20:47:54 UTC 2021 ``` ## \$1GOTO 适用于 Amazon Redshift RSQL 的新命令。`\GOTO` 跳过所有干预命令并在指定的 `\LABEL` 继续处理。`\LABEL` 必须是前向引用。您不能跳转到词汇上位于 `\GOTO` 之前的 `\LABEL`。 下面显示了示例输出。 ``` (testcluster) user1@dev=# \! cat test.sql select count(*) as cnt from lineitem \gset select :cnt as cnt; \if :cnt > 100 \goto LABELB \endif \label LABELA \remark 'this is label LABELA' \label LABELB \remark 'this is label LABELB' (testcluster) user1@dev=# \i test.sql cnt --------- 4307207 (1 row) \label LABELA ignored \label LABELB processed this is label LABELB ``` ## \$1LABEL 适用于 Amazon Redshift RSQL 的新命令。`\LABEL` 建立运行程序的入口点，作为 `\GOTO` 命令的目标。 以下显示了命令的输出。 ``` (testcluster) user1@dev=# \! cat test.sql select count(*) from lineitem limit 5; \goto LABELB \remark "this step was skipped by goto label"; \label LABELA \remark 'this is label LABELA' \label LABELB \remark 'this is label LABELB' (testcluster) user1@dev=# \i testgoto.sql count 4307193 (1 row) \label LABELA ignored \label LABELB processed this is label LABELB ``` ## \$1IF (\$1ELSEIF, \$1ELSE, \$1ENDIF) `\IF` 和相关命令有条件地运行部分输入脚本。PSQL `\if`（`\elif`、`\else`、`\endif`）命令的扩展。`\IF` 和 `\ELSEIF` 支持布尔表达式，包括 `AND`、`OR` 和 `NOT` 条件。 以下显示了命令的示例输出。 ``` (testcluster) user1@dev=# \! cat test.sql SELECT query FROM stv_inflight LIMIT 1 \gset select :query as query; \if :query > 1000000 \remark 'Query id is greater than 1000000' \elseif :query = 1000000 \remark 'Query id is equal than 1000000' \else \remark 'Query id is less than 1000000' \endif (testcluster) user1@dev=# \i test.sql query -------- 994803 (1 row) Query id is less than 1000000 ``` 在您的分支逻辑中使用 `ERRORCODE`。 ``` \if :'ERRORCODE' = '00000' \remark 'The statement was executed without error' \else \remark :LAST_ERROR_MESSAGE \endif ``` 在 `\IF` 块内使用 `\GOTO` 以控制代码的运行方式。 # Amazon Redshift RSQL 变量 有些关键字在 RSQL 中充当变量。您可以将每个值设置为特定值，也可以重新设置值。大多数值都由 `\rset` 设置，它具有交互式模式和批处理模式。命令可以用小写或大写定义。 ## ACTIVITYCOUNT 指示受上次提交的请求影响的行数。对于数据返回请求，这是从数据库返回到 RSQL 的行数。该值为 0 或正整数。最大值为 18,446,744,073,709,551,615。 经过特殊处理的变量 `ACTIVITYCOUNT` 类似于变量 `ROW_COUNT`。但是，在命令完成时，`ROW_COUNT` 不会向客户端应用程序报告受影响的 `SELECT`、`COPY` 或 `UNLOAD` 行数。而 `ACTIVITYCOUNT` 会报告相关行数。 activitycount\$101.sql： ``` select viewname, schemaname from pg_views where schemaname = 'not_existing_schema'; \if :ACTIVITYCOUNT = 0 \remark 'views do not exist' \endif ``` 控制台输出： ``` viewname | schemaname ----------+------------ (0 rows) views do not exist ``` ## ERRORLEVEL 为错误分配严重性级别。使用严重性级别来确定适当操作。如果尚未使用 `ERRORLEVEL` 命令，那么默认情况下，它的值为 `ON`。 errorlevel\$101.sql： ``` \rset errorlevel 42P01 severity 0 select * from tbl; select 1 as col; \echo exit \quit ``` 控制台输出： ``` Errorlevel is on. rsql: ERROR: relation "tbl" does not exist (1 row) col 1 exit ``` ## HEADING 和 RTITLE 允许用户指定显示在报告顶部的标题。使用 `RSET RTITLE` 命令指定的标题会自动包含客户端电脑的当前系统日期。 rset\$1heading\$1rtitle\$102.rsql 内容： ``` \remark Starting... \rset rtitle "Marketing Department||Confidential//Third Quarter//Chicago" \rset width 70 \rset rformat on select * from rsql_test.tbl_currency order by id limit 2; \exit \remark Finishing... ``` 控制台输出： ``` Starting... Rtitle is set to: &DATE||Marketing Department||Confidential//Third Quarter//Chicago (Changes will take effect after RFORMAT is switched ON) Target width is 70. Rformat is on. 09/11/20 Marketing Department Confidential Third Quarter Chicago id | bankid | name | start_date 100 | 1 | USD | 2020-09-11 10:51:39.106905 110 | 1 | EUR | 2020-09-11 10:51:39.106905 (2 rows) Press any key to continue . . . ``` ## MAXERROR 指定 RSQL 终止任务处理的最大错误严重性级别。在完成每个作业或任务后，返回代码是 RSQL 返回到客户端操作系统的整数值。返回代码的值表示作业或任务的完成状态。如果脚本包含生成错误严重性级别大于指定 `maxerror` 值的语句，RSQL 将立即退出。因此，要将 RSQL 退出的错误严重性级别设为 8，请使用 `RSET MAXERROR 7`。 maxerror\$101.sql 内容： ``` \rset maxerror 0 select 1 as col; \quit ``` 控制台输出： ``` Maxerror is default. (1 row) col 1 ``` ## RFORMAT 允许用户指定是否应用格式化命令的设置。 rset\$1rformat.rsql 内容： ``` \remark Starting... \pset border 2 \pset format wrapped \pset expanded on \pset title 'Great Title' select * from rsql_test.tbl_long where id = 500; \rset rformat select * from rsql_test.tbl_long where id = 500; \rset rformat off select * from rsql_test.tbl_long where id = 500; \rset rformat on select * from rsql_test.tbl_long where id = 500; \exit \remark Finishing... ``` 控制台输出： ``` Starting... Border style is 2. (Changes will take effect after RFORMAT is switched ON) Output format is wrapped. (Changes will take effect after RFORMAT is switched ON) Expanded display is on. (Changes will take effect after RFORMAT is switched ON) Title is "Great Title". (Changes will take effect after RFORMAT is switched ON) id | long_string 500 | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. (1 row) Rformat is on. Great Title +-[ RECORD 1 ]+---------------------------------------------------------------------------------------------------------------------- -----------+ | id | 500 | | long_string | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. | +-------------+---------------------------------------------------------------------------------------------------------------------- -----------+ Rformat is off. id | long_string 500 | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. (1 row) Rformat is on. Great Title +-[ RECORD 1 ]+---------------------------------------------------------------------------------------------------------------------- -----------+ | id | 500 | | long_string | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. | +-------------+---------------------------------------------------------------------------------------------------------------------- -----------+ Press any key to continue . . . ``` ## ROW\$1COUNT 获取受以前查询影响的记录数。它通常用于检查结果，如以下代码片段所示： ``` SET result = ROW_COUNT; IF result = 0 ... ``` ## TITLEDASHES 使用此控件，用户可以指定是否要在为 SQL 语句返回的列数据的上方打印一行破折号字符。 示例： ``` \rset titledashes on select dept_no, emp_no, salary from rsql_test.EMPLOYEE where dept_no = 100; \rset titledashes off select dept_no, emp_no, salary from rsql_test.EMPLOYEE where dept_no = 100; ``` 控制台输出： ``` dept_no emp_no salary ----------- ----------- -------------------- 100 1000346 1300.00 100 1000245 5000.00 100 1000262 2450.00 dept_no emp_no salary 100 1000346 1300.00 100 1000245 5000.00 100 1000262 2450.00 ``` ## WIDTH 将输出格式设置为换行并指定报告中每行的目标宽度。如果没有参数，它将返回格式和目标宽度的当前设置。 rset\$1width\$101.rsql 内容： ``` \echo Starting... \rset width \rset width 50 \rset width \quit \echo Finishing... ``` 控制台输出： ``` Starting... Target width is 75. Target width is 50. Target width is 50. Press any key to continue . . . ``` 使用参数的示例： ``` \echo Starting... \rset rformat on \pset format wrapped select * from rsql_test.tbl_long where id = 500; \rset width 50 select * from rsql_test.tbl_long where id = 500; \quit \echo Finishing... ``` 控制台输出： ``` Starting... Rformat is on. Output format is wrapped. id | long_string 500 | In general, the higher the number the more borders and lines the ta. |.bles will have, but details depend on the particular format. (1 row) Target width is 50. id | long_string 500 | In general, the higher the number the more. |. borders and lines the tables will have, b. |.ut details depend on the particular format. |.. (1 row) Press any key to continue . . . ``` # Amazon Redshift RSQL 错误代码 成功消息、警告和异常： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/rsql-query-tool-error-codes.html) 数据异常： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/rsql-query-tool-error-codes.html) 违反完整性约束： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/rsql-query-tool-error-codes.html) # Amazon Redshift RSQL 环境变量 Amazon Redshift RSQL 可以使用环境变量来选择默认参数值。 ## RSPASSWORD **重要** 出于安全原因，我们不建议使用此环境变量，因为有些操作系统允许非管理用户查看进程环境变量。 为 Amazon Redshift RSQL 设置连接到 Amazon Redshift 时要使用的密码。此环境变量需要 Amazon Redshift RSQL 1.0.4 及更高版本。 如果设置了 RSPASSWORD，RSQL 会优先考虑它。如果未设置 RSPASSWORD 并且您使用 DSN 进行连接，则 RSQL 将从 DSN 文件的参数中获取密码。最后，如果未设置 RSPASSWORD 且您没有使用 DSN，则 RSQL 会在尝试连接后提供密码提示。 下面为设置 RSPASSWORD 的示例： ``` export RSPASSWORD=TestPassw0rd ``` # 使用身份验证配置文件连接到 Amazon Redshift 如果您与 Amazon Redshift 有很多连接，则可能很难管理所有这些连接的设置。通常，每个 JDBC 或 ODBC 连接都使用特定的配置选项。借助身份验证配置文件，可以将连接选项存储在一起。这样，用户可以选择要连接的配置文件，避免管理单个选项的设置。配置文件可以应用于各种场景和用户类型。 创建身份验证配置文件后，用户可以将即用型配置文件添加到连接字符串。这样，他们即可使用针对每个角色和使用案例的正确设置连接到 Amazon Redshift。 有关 Amazon Redshift API 的信息，请参阅 [CreateAuthenticationProfile](https://docs.aws.amazon.com/redshift/latest/APIReference/redshift-api.pdf#API_CreateAuthenticationProfile)。 # 创建身份验证配置文件 通过 AWS CLI，您可以使用 `create-authentication-profile` 命令创建身份验证配置文件。这假定您已有一个 Amazon Redshift 集群和现有数据库。您的凭证必须具有连接到 Amazon Redshift 数据库的权限以及获取身份验证配置文件的权限。您可以将配置选项作为 JSON 字符串提供，或者引用包含 JSON 字符串的文件。 ``` create-authentication-profile --authentication-profile-name --authentication-profile-content ``` 以下示例创建一个名为 `ExampleProfileName` 的配置文件。在这里，您可以将定义集群名称和其它选项设置的键和值作为 JSON 字符串添加。 ``` create-authentication-profile --authentication-profile-name "ExampleProfileName" --authentication-profile-content "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" } ``` 此命令使用指定的 JSON 设置创建配置文件。返回以下内容，表示已创建配置文件。 `{"AuthenticationProfileName": "ExampleProfileName", "AuthenticationProfileContent": "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" } ` ## 创建身份验证配置文件的限制和配额 每位客户的配额为十（10）个身份验证配置文件。 身份验证配置文件可能发生某些错误 例如，如果您使用现有名称创建新的配置文件，或者您是否超过了配置文件配额。有关更多信息，请参阅 [CreateAuthenticationProfile](https://docs.aws.amazon.com/redshift/latest/APIReference/redshift-api.pdf#API_CreateAuthenticationProfile)。 您无法在身份验证配置文件存储中存储 JDBC、ODBC 和 Python 连接字符串的某些选项键和值： + `AccessKeyID` + `access_key_id` + `SecretAccessKey` + `secret_access_key_id` + `PWD` + `Password` + `password` 对于 JDBC 或 ODBC 连接字符串，您不能在配置文件存储中存储键或值 `AuthProfile`。对于 Python 连接，您无法存储 `auth_profile`。 身份验证配置文件存储在 Amazon DynamoDB 中并由 AWS 管理。 # 使用身份验证配置文件进行连接 创建身份验证配置文件后，您可以包含配置文件名称作为 JDBC 2.0 `AuthProfile` 版的连接选项。使用此连接选项可以检索存储的设置。 ``` jdbc:redshift:iam://endpoint:port/database?AuthProfile=&AccessKeyID=&SecretAccessKey= ``` 以下是 JDBC URL 字符串示例。 ``` jdbc:redshift:iam://examplecluster:us-west-2/dev?AuthProfile="ExampleProfile"&AccessKeyID="AKIAIOSFODNN7EXAMPLE"&SecretAccessKey="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` 在 JDBC URL 中指定 `AccessKeyID` 和 `SecretAccessKey`，以及身份验证配置文件名称。 在下面的示例中，您还可以使用分号分隔符分隔配置选项，其中包括日志记录选项。 ``` jdbc:redshift:iam://my_redshift_end_point:5439/dev?LogLevel=6;LogPath=/tmp;AuthProfile=my_profile;AccessKeyID="AKIAIOSFODNN7EXAMPLE";SecretAccessKey="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` **注意** 请勿向身份验证配置文件中添加机密信息。例如，不要在身份验证配置文件中存储 `AccessKeyID` 或 `SecretAccessKey` 值。身份验证配置文件存储具有禁止存储密钥的规则。如果尝试存储与敏感信息相关的密钥和值，则会出错。 # 获取身份验证配置文件 要列出现有身份验证配置文件，请调用以下命令。 ``` describe-authentication-profiles --authentication-profile-name ``` 下面的示例显示了两个检索配置文件。如果不指定配置文件名称，则返回所有配置文件。 `{ "AuthenticationProfiles": [ { "AuthenticationProfileName": "testProfile1", "AuthenticationProfileContent": "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" }, { "AuthenticationProfileName": "testProfile2", "AuthenticationProfileContent": "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" } ] } ` # 解决 Amazon Redshift 中的连接问题 如果您在从 SQL 客户端工具连接到集群时遇到问题，可以从几个方面进行排查以缩小问题范围。如果您使用了 SSL 或服务器证书，请在开始排查连接问题之前将其删除以降低复杂性。然后，在找出解决方案之后再添加。有关更多信息，请参阅 [配置连接的安全选项](connecting-ssl-support.md)。 有关 Amazon Redshift 功能中可能影响应用程序的行为更改的信息，请参阅 [Amazon Redshift 中的行为更改](behavior-changes.md)。 **重要** Amazon Redshift 改变了我们管理 SSL 证书的方法。如果您在使用 SSL 连接时遇到问题，您可能需要更新当前的信任根 CA 证书。有关更多信息，请参阅 [将 SSL 连接过渡到 ACM 证书](connecting-transitioning-to-acm-certs.md)。 以下部分提供了一些针对连接问题的示例错误消息和可能的解决方案。不同 SQL 客户端工具提供的错误消息不同，因此，虽然此非完整列表，但却是不错的问题排查切入点。 ## 从 Amazon EC2 外部连接时遇到防火墙超时问题 在运行 COPY 命令等较长的查询时，客户端到数据库的连接会挂起或超时。此时，您可能会发现，Amazon Redshift 控制台显示查询已完成，而客户端工具仍然显示正在运行查询。查询结果可能会丢失或不完整，具体取决于连接停止的时间。 ### 可能的解决方案 当您从 Amazon EC2 实例以外的计算机连接到 Amazon Redshift 时，会发生此问题。在此情况下，空闲连接将在处于不活动状态一段时间后被防火墙等中间网络组件终止。当您从 Virtual Private Network（VPN）或本地网络登录时，通常会出现这种行为。 为避免出现此类超时，建议您执行以下更改： + 提高用于处理 TCP/IP 超时的客户端系统值。在用来连接集群的计算机上进行这些更改。根据您的客户端和网络调整超时期限。有关更多信息，请参阅 [更改 TCP/IP 超时设置](#connecting-firewall-guidance.change-tcpip-settings)。 + （可选）在 DSN 级别设置 Keepalive 行为。有关更多信息，请参阅 [更改 DSN 超时设置](#connecting-firewall-guidance.change-dsn-settings)。 ### 更改 TCP/IP 超时设置 要更改 TCP/IP 超时设置，请根据您用来连接集群的操作系统配置超时设置。 + Linux — 如果您的客户端在 Linux 上运行，请以根用户身份运行以下命令来更改当前会话的超时设置： ``` /sbin/sysctl -w net.ipv4.tcp_keepalive_time=200 net.ipv4.tcp_keepalive_intvl=200 net.ipv4.tcp_keepalive_probes=5 ``` 要保存设置，请使用以下值创建或修改文件 `/etc/sysctl.conf`，然后重新启动您的系统。 ``` net.ipv4.tcp_keepalive_time=200 net.ipv4.tcp_keepalive_intvl=200 net.ipv4.tcp_keepalive_probes=5 ``` + Windows — 如果您的客户端在 Windows 上运行，请在 HKEY\$1LOCAL\$1MACHINE\$1SYSTEM\$1CurrentControlSet\$1Services\$1Tcpip\$1Parameters\$1 下编辑以下注册表设置的值： + KeepAliveTime：30000 + KeepAliveInterval：1000 + TcpMaxDataRetransmissions：10 这些设置使用 DWORD 数据类型。如果它们不在注册表路径下，您可以创建设置并指定这些建议值。有关编辑 Windows 注册表的更多信息，请参阅 Windows 文档。 在设置好这些值之后，重启您的计算机以使更改生效。 + Mac — 如果您的客户端在 Mac 上运行，请运行以下命令来更改当前会话的超时设置： ``` sudo sysctl net.inet.tcp.keepintvl=200000 sudo sysctl net.inet.tcp.keepidle=200000 sudo sysctl net.inet.tcp.keepinit=200000 sudo sysctl net.inet.tcp.always_keepalive=1 ``` 要保存设置，请使用以下值创建或修改文件 `/etc/sysctl.conf`： ``` net.inet.tcp.keepidle=200000 net.inet.tcp.keepintvl=200000 net.inet.tcp.keepinit=200000 net.inet.tcp.always_keepalive=1 ``` 重新启动计算机，然后运行以下命令来验证值是否已设置。 ``` sysctl net.inet.tcp.keepidle sysctl net.inet.tcp.keepintvl sysctl net.inet.tcp.keepinit sysctl net.inet.tcp.always_keepalive ``` ### 更改 DSN 超时设置 如果需要，您可以在 DSN 级别设置 Keepalive 行为。在 odbc.ini 文件中添加或修改以下参数即可实现： **KeepAlivesCount** 连接被视为断开前可能丢失的 TCP keepalive 包的数量。 **KeepAlivesIdle** 驱动程序发送 TCP Keepalive 包前处于不活动状态的秒数。 **KeepAlivesInterval** 两次传输 TCP keepalive 间隔的秒数。 如果这些参数不存在，或者其值为 0，则系统将使用为 TCP/IP 指定的 Keepalive 参数来确定 DSN Keepalive 行为。在 Windows 上，您可以在注册表中的 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\` 中查找 TCP/IP 参数。在 Linux 和 macOS 上，可以在 sysctl.conf 文件中查找 TCP/IP 参数。 ## 连接被拒绝或失败 当连接被拒绝或失败时，您可能会收到类似于以下其中一种的错误。 + “无法建立到 ** 的连接。” + “无法连接到服务器：连接超时。服务器是否在主机 *''* 上运行，是否接受端口 *''* 上的 TCP/IP 连接？” + “连接被拒。请检查主机名和端口是否正确无误，以及邮件管理员是否接受 TCP/IP 连接。” ### 可能的解决方案 通常，当您收到指示连接建立失败的错误消息时，是因为访问集群的权限或到达集群的网络流量存在问题。 要从集群所在的网络外部的客户端工具连接到集群，请将入站规则添加到集群的安全组中。规则配置取决于是否在 Virtual Private Cloud (VPC) 中创建了 Amazon Redshift 集群： + 如果您已在基于 Amazon VPC 的虚拟私有云 (VPC) 中创建 Amazon Redshift 集群，请在 Amazon VPC 中向指定客户端 CIDR/IP 地址的 VPC 安全组添加一条入站规则。有关为集群配置 VPC 安全组和可公开访问的选项的更多信息，请参阅[VPC 中的 Redshift 资源](managing-clusters-vpc.md)。 + 如果您已在 VPC 外部创建 Amazon VPC 集群，则需要将您的客户端 CIDR/IP 地址添加到 Amazon Redshift 中的集群安全组。有关配置集群安全组的更多信息，请参阅[Amazon Redshift 安全组](security-network-isolation.md#working-with-security-groups)。 如果您尝试从在 Amazon EC2 实例上运行的客户端工具连接到集群，也需要添加入站规则。在这种情况下，请向集群安全组添加规则。该规则必须指定与客户端工具的 Amazon EC2 实例关联的 Amazon EC2 安全组。 在某些情况下，客户端和服务器之间可能有一个层，例如防火墙。在这些情况下，请确保防火墙接受通过为集群配置的端口的入站连接。 ## 客户端和驱动程序不兼容 如果客户端和驱动程序不兼容，可能会收到“指定的 DSN 包含驱动程序和应用程序之间的架构不匹配”的错误信息。 ### 可能的解决方案 如果您在尝试连接时收到架构不匹配的错误，则说明客户端工具与驱动程序不兼容。此情况是由于其系统架构不匹配导致的。例如，如果您在 32 位客户端工具上安装 64 位驱动程序版本，便会发生这种情况。有时，64 位客户端工具可以使用 32 位驱动程序，但无法在 32 位应用程序上使用 64 位驱动程序。请确保驱动程序和客户端工具使用的是相同版本的系统架构。 ## 查询似乎挂起，有时无法连接到集群 您在完成查询时遇到问题，即在 SQL 客户端工具中，查询显示为正在进行，但实则处于挂起状态。有时，查询无法显示在集群中，如系统表或 Amazon Redshift 控制台中。 ### 可能的解决方案 此问题可能是由于数据包丢失导致的。在此情况下，两个 Internet 协议 (IP) 主机在网络路径中的最大传输单位 (MTU) 大小不同。MTU 大小用于确定可通过网络连接在单个以太网帧中传输的数据包的最大大小（以字节为单位）。在 AWS 中，一些 Amazon EC2 实例类型支持 1500 MTU（以太网 v2 帧），其他实例类型支持 9001 MTU（TCP/IP 巨型帧）。 为避免因 MTU 大小不同可能导致的各种问题，建议您执行以下操作之一： + 如果集群使用 EC2-VPC 平台，则使用将返回 `Destination Unreachable` 的入站自定义 互联网 控制消息协议 (ICMP) 规则配置 Amazon VPC 安全组。因此，该规则指示原始主机沿网络路径使用最小的 MTU 大小。有关此方法的详细信息，请参阅[配置安全组以允许 ICMP“无法到达目标”](#configure-custom-icmp)。 + 如果您的集群使用 EC2-Classic 平台，或者您无法允许 ICMP 入站规则，请禁用 TCP/IP 巨型帧以便使用以太网 v2 帧。有关此方法的详细信息，请参阅[配置实例的 MTU](#set-mtu)。 ### 配置安全组以允许 ICMP“无法到达目标” 当两个主机在网络中的 MTU 大小存在差异时，请先确保您的网络设置不会阻止路径 MTU 发现 (PMTUD)。PMTUD 使接收主机能够使用以下 ICMP 消息响应原始主机：`Destination Unreachable: fragmentation needed and DF set (ICMP Type 3, Code 4)`。此消息将指示原始主机在网络路径中使用最低 MTU 大小重新发送请求。若无此协商，当请求过大，导致接收主机无法接收时，数据包可能会丢失。有关此 ICMP 消息的更多信息，请转至 *国际互联网工程任务组 (IETF)* 网站上的 [RFC792](http://tools.ietf.org/html/rfc792)。 如果您没有为 Amazon VPC 安全组明确配置此 ICMP 入站规则，PMTUD 则将被阻止。在 AWS 中，安全组是虚拟防火墙，用于为到实例的入站和出站流量指定规则。有关 Amazon Redshift 集群安全组的信息，请参阅 [Amazon Redshift 安全组](security-network-isolation.md#working-with-security-groups)。对于使用 EC2-VPC 平台的集群，Amazon Redshift 将使用 VPC 安全组来允许或拒绝到集群的流量。默认情况下，安全组处于锁定状态，会拒绝所有入站流量。有关如何为 EC2-Classic 或 EC2-VPC 实例设置入站和出站规则的信息，请参阅《Amazon EC2 用户指南》**中的 [EC2-Classic 与 VPC 中的实例间的差异](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-classic-platform.html#ec2_classic_platform)。 有关如何向 VPC 安全组添加规则的更多信息，请参阅[VPC 安全组](managing-vpc-security-groups.md)。有关此规则中需要的特定 PMTUD 设置的更多信息，请参阅《Amazon EC2 用户指南》**中的[路径 MTU 发现](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/network_mtu.html#path_mtu_discovery)。 ### 配置实例的 MTU 在某些情况下，您的集群可能会使用 EC2-Classic 平台，或者您不能允许对入站流量使用自定义 ICMP 规则。在这些情况下，建议您在从中连接到 Amazon Redshift 集群的 EC2 实例的网络接口 (NIC) 上将 MTU 调整为 1500。此调整将禁用 TCP/IP 巨型帧，以确保连接始终使用同一数据包大小。但是，此选项将从整体上降低实例的最大网络吞吐量，而不仅仅是到 Amazon Redshift 的连接。有关更多信息，请参阅以下流程。 **在 Microsoft Windows 操作系统上设置 MTU** 如果客户端在 Microsoft Windows 操作系统上运行，则可使用 `netsh` 命令查看和设置以太网适配器的 MTU 值。 1. 运行以下命令可确定当前 MTU 值： ``` netsh interface ipv4 show subinterfaces ``` 1. 在输出中查看 `MTU` 适配器的 `Ethernet` 值。 1. 如果值不是 `1500`，则运行以下命令设置它： ``` netsh interface ipv4 set subinterface "Ethernet" mtu=1500 store=persistent ``` 设置好此值后，重启您的计算机以使更改生效。 **在 Linux 操作系统上设置 MTU** 如果客户端在 Linux 操作系统上运行，则可使用 `ip` 命令查看和设置 MTU 值。 1. 运行以下命令可确定当前 MTU 值： ``` $ ip link show eth0 ``` 1. 查看输出中 `mtu` 后面的值。 1. 如果值不是 `1500`，则运行以下命令设置它： ``` $ sudo ip link set dev eth0 mtu 1500 ``` **在 Mac 操作系统上设置 MTU** + 请按照 macOS 支持网站上关于 `How to change the MTU for troubleshooting purposes` 的说明操作。有关详细信息，请搜索 [ 支持网站。](https://support.apple.com) ## 设置 JDBC 提取大小参数 默认情况下，Redshift JDBC 驱动程序使用环形缓冲区来高效管理内存，并防止出现内存不足错误。仅当明确禁用环形缓冲区时，提取大小参数才适用。有关更多信息，请查看[链接](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-configuration-options.html#jdbc20-enablefetchringbuffer-option)。在此配置中，您应设置提取大小以控制每个批次中检索的行数。 在以下情况下使用提取大小参数： + 您需要对基于行的批处理实施精细控制 + 使用需要传统提取大小行为的旧式应用程序 在已禁用环形缓冲区的情况下，JDBC 驱动程序会默认一次性收集查询的所有结果。返回大型结果集的查询可能会占用过量内存。要分批而非一次性检索结果集，请在应用程序中设置 JDBC 提取大小参数。 **注意** ODBC 不支持提取大小。 为获得最佳性能，请将提取大小设置为不会导致内存不足错误的最大值。较小的提取大小值会导致更多的服务器通信，从而延长执行时间。服务器会预留资源，包括 WLM 查询槽和关联内存，直到客户端检索到整个结果集或查询取消为止。如果适当优化提取大小，则可以更快释放这些资源，使其能够供其他查询使用。 **注意** 如果需要提取大型数据集，建议使用 [UNLOAD](https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD.html) 语句将数据传输到 Amazon S3。使用 UNLOAD 时，计算节点并行工作，以加快数据的传输。 有关设置 JDBC 提取大小参数的更多信息，请参阅 PostgreSQL 文档中的[基于光标获取结果](https://jdbc.postgresql.org/documentation/query/#getting-results-based-on-a-cursor)。 # 使用 Amazon Redshift 数据 API Amazon Redshift 数据 API 消除了管理数据库驱动程序、连接、网络配置、数据缓冲、凭证等的需求，从而简化了对 Amazon Redshift 数据仓库的访问。您可以通过 AWS SDK，使用数据 API 操作来运行 SQL 语句。有关数据 API 操作的更多信息，请参阅 [Amazon Redshift 数据 API 参考](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)。 数据 API 不需要与数据库的持久连接。相反，它提供了安全 HTTP 端点以及与 AWS 开发工具包的集成。您可以使用终端节点运行 SQL 语句，而无需管理连接。对数据 API 的调用是异步的。数据 API 可以使用存储在 AWS Secrets Manager 中的凭证或临时数据库凭证。您无需使用任何一种授权方法在 API 调用中传递密码。有关 AWS Secrets Manager 的更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 您也可以使用 AWS IAM Identity Center 进行授权。 使用数据 API，您可以通过基于 Web 服务的应用程序（包括 AWS Lambda、Amazon SageMaker AI 笔记本和 AWS Cloud9），以编程方式访问 Amazon Redshift 数据。有关这些应用程序的更多信息，请参阅 [AWS Lambda](https://aws.amazon.com/lambda/)、[Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) 和 [AWS Cloud9](https://aws.amazon.com/cloud9/)。 要了解有关数据 API 的更多信息，请参阅 *AWS 大数据博客*中的 [Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/)。 ## 使用 Amazon Redshift 数据 API 在您使用 Amazon Redshift 数据 API 之前，请查看以下步骤： 1. 确定您作为数据 API 的调用者是否获得授权。有关授权的更多信息，请参阅[授予对 Amazon Redshift 数据 API 的访问权限](data-api-access.md)。 1. 确定是否计划使用来自 Secrets Manager 的身份验证凭证、临时凭证或使用 AWS IAM Identity Center 来调用数据 API。有关更多信息，请参阅 [在调用 Amazon Redshift 数据 API 时选择数据库身份验证凭证](#data-api-calling-considerations-authentication)。 1. 如果您将 Secrets Manager 用于身份验证凭证，请设置密码。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储数据库凭证](data-api-secrets.md)。 1. 查看调用数据 API 时的注意事项和限制。有关更多信息，请参阅 [调用 Amazon Redshift 数据 API 时的注意事项](#data-api-calling-considerations)。 1. 从 AWS Command Line Interface (AWS CLI)、您自己的代码中调用数据 API，或使用 Amazon Redshift 控制台中的查询编辑器。有关从 AWS CLI 进行调用的示例，请参阅[调用 Data API](data-api-calling.md)。 ## 调用 Amazon Redshift 数据 API 时的注意事项 调用数据 API 时，请注意以下事项： + Amazon Redshift 数据 API 可以访问 Amazon Redshift 预置集群和 Redshift Serverless 工作组中的数据库。有关可以使用数据 API 的 AWS 区域列表，请参阅《Amazon Web Services 一般参考》**中为 [Redshift 数据 API](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 列出的端点。 + 查询的最长持续时间为 24 小时。 + 每个 Amazon Redshift 集群的最大活动查询（`STARTED` 和 `SUBMITTED` 查询）数量为 500 个。 + 最大查询结果大小为 500 MB（gzip 压缩后）。如果调用返回的响应数据超过 500 MB，则调用将结束。 + 查询结果的最长保留时间为 24 小时。 + 最大查询语句大小为 100 KB。 + 数据 API 可用于查询以下节点类型的单节点和多节点集群： + dc2.large + dc2.8xlarge + ra3.large + ra3.xlplus + ra3.4xlarge + ra3.16xlarge + 集群必须在基于 Amazon VPC 服务的 Virtual Private Cloud (VPC) 中。 + 默认情况下，具有与 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作运行者相同的 IAM 角色的用户可以使用 `CancelStatement`、`DescribeStatement`、`GetStatementResult`、`GetStatementResultV2` 和 `ListStatements` API 操作对同一个语句进行操作。要从另一个用户对同一 SQL 语句执行操作，该用户必须能够代入运行 SQL 语句的用户的 IAM 角色。有关如何代入角色的更多信息，请参阅[授予对 Amazon Redshift 数据 API 的访问权限](data-api-access.md)。 + `BatchExecuteStatement` API 操作的 `Sqls` 参数中的 SQL 语句将作为单个事务运行。它们按数组的顺序连续运行。后续的 SQL 语句要等到数组中的前一条语句完成后才会开始。如果任何 SQL 语句失败，由于它们作为一个事务运行，所有工作都将回滚。 + 在 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作中使用的客户端令牌的最长保留时间为 8 小时。 + 如果使用客户自主管理型密钥对 Amazon Redshift 预调配集群和 Redshift Serverless 工作组进行加密，则 Redshift 将创建一项授权，允许 Redshift Data API 将该密钥用于其操作。有关更多信息，请参阅 [结合使用 AWS KMS 与 Amazon Redshift Data API](data-api-kms.md)。 + Redshift 数据 API 中的每个 API 都有每秒事务次数配额，超过该配额会对请求节流。有关配额，请参阅 [Amazon Redshift 数据 API 的配额](amazon-redshift-limits.md#data-api-quotas-account)。如果请求速率超过配额，则会返回 `ThrottlingException` 以及“HTTP 状态代码：400”。要应对节流的情况，请使用重试策略，如《AWS SDK 和工具参考指南》**中的[重试行为](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)所述。在某些 AWS SDK 中，会针对节流错误自动实施这一策略。 **注意** 在 AWS Step Functions 中，默认情况下未启用重试功能。如果您需要在 Step Functions 状态机中调用 Redshift 数据 API，请在 Redshift 数据 API 调用中包括 `ClientToken` 幂等性参数。`ClientToken` 的值需要在重试之间保持不变。在以下 `ExecuteStatement` API 请求的示例片段中，表达式 `States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)` 使用内置函数提取 `$$.Execution.Id` 的 UUID 部分，这一部分在状态机的每次执行中都是唯一的。有关更多信息，请参阅《AWS Step Functions 开发人员指南》**中的[内置函数](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html)。 ``` { "Database": "dev", "Sql": "select 1;", "ClusterIdentifier": "MyCluster", "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)" } ``` ## 在调用 Amazon Redshift 数据 API 时选择数据库身份验证凭证 当您调用数据 API 时，您对某些 API 操作使用以下身份验证方法之一。每种方法都需要不同的参数组合。 **AWS IAM Identity Center** 在 AWS IAM Identity Center 中注册的单点登录用户可以访问数据 API。有关设置 IAM Identity Center 的步骤的信息，请参阅[将数据 API 与可信身份传播结合使用](data-api-trusted-identity-propagation.md)。 **AWS Secrets Manager** 使用此方法，提供存储在 AWS Secrets Manager 中密钥的 `secret-arn`，其中包括了 `username` 和 `password`。指定的密钥包含用于连接到您指定的 `database` 的凭证。在连接到集群时，如果您提供了集群标识符（`dbClusterIdentifier`），则还可以提供数据库名称，该名称必须与密钥中存储的集群标识符相匹配。在连接到无服务器工作组时，也要提供数据库名称。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储数据库凭证](data-api-secrets.md)。 使用此方法，您还可以提供 `region` 值，该值指定您的数据所在的 AWS 区域。 **临时凭证** 使用此方法时，请选择以下选项之一： + 在连接到无服务器工作组时，需指定工作组名称和数据库名称。数据库用户名派生自 IAM 身份。例如，`arn:iam::123456789012:user:foo` 具有数据库用户名 `IAM:foo`。此外，需具有调用 `redshift-serverless:GetCredentials` 操作的权限。 + 以 IAM 身份连接到集群时，需要指定集群标识符和数据库名称。数据库用户名派生自 IAM 身份。例如，`arn:iam::123456789012:user:foo` 具有数据库用户名 `IAM:foo`。此外，需具有调用 `redshift:GetClusterCredentialsWithIAM` 操作的权限。 + 以数据库用户的身份连接到机群时，需要指定集群标识符、数据库名称和数据库用户名。此外，需具有调用 `redshift:GetClusterCredentials` 操作的权限。有关使用此方法进行连接时如何加入数据库组的信息，请参阅[连接到集群时加入数据库组](data-api-dbgroups.md)。 使用此方法，您还可以提供 `region` 值，该值指定您的数据所在的 AWS 区域。 ## 调用 Amazon Redshift 数据 API 时映射 JDBC 数据类型 下表将 Java 数据库连接 (JDBC) 数据类型映射到您在数据 API 调用中指定的数据类型。 **** | JDBC 数据类型 | Data API 数据类型 | | --- | --- | | `INTEGER, SMALLINT, BIGINT` | `LONG` | | `FLOAT, REAL, DOUBLE` | `DOUBLE` | | `DECIMAL` | `STRING` | | `BOOLEAN, BIT` | `BOOLEAN` | | `BLOB, BINARY, LONGVARBINARY` | `BLOB` | | `VARBINARY` | `STRING` | | `CLOB` | `STRING` | | 其他类型（包括与日期和时间有关的类型） | `STRING` | 字符串值将传递到 Amazon Redshift 数据库并隐式转换为数据库数据类型。 **注意** 目前，数据 API 不支持通用唯一标识符 (UUID) 的数组。 ## 在调用 Amazon Redshift 数据 API 时运行带有参数的 SQL 语句 您可以通过使用 SQL 语句部分的参数调用数据 API 操作来控制提交到数据库引擎的 SQL 文本。命名参数提供了一种灵活的方式来传入参数，而无需在 SQL 文本中对参数进行硬编码。它们可以帮助您重复使用 SQL 文本并避免 SQL 注入问题。 以下示例显示 `execute-statement` AWS CLI 命令的 `parameters` 字段的命名参数。 ``` --parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]" ``` 使用命名参数时，请注意以下事项： + 命名参数只能用于替换 SQL 语句中的值。 + 您可以替换 INSERT 语句中的值，例如 `INSERT INTO mytable VALUES(:val1)`。 命名参数可以按任意顺序排列，并且参数可以在 SQL 文本中多次使用。前面示例中显示的参数选项，值 `1` 和 `Seattle` 插入到表列 `id` 和 `address` 中。在 SQL 文本中，您可以按如下方式指定命名参数： ``` --sql "insert into mytable values (:id, :address)" ``` + 您可以替换条件子句中的值，例如 `WHERE attr >= :val1`、`WHERE attr BETWEEN :val1 AND :val2` 和 `HAVING COUNT(attr) > :val`。 + 您无法替换 SQL 语句中的列名，例如 `SELECT column-name`、`ORDER BY column-name` 或 `GROUP BY column-name`。 例如，以下 SELECT 语句将失败，出现语法无效错误。 ``` --sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]" ``` 如果您说明（`describe-statement` 操作）语句有语法错误，则返回的 `QueryString` 不会用列名代替参数（`"QueryString": "SELECT :colname, FROM event"`），并且会报告错误（错误：在 \$1"FROM\$1"\$1 处或附近出现语法错误 \$1n 位置：12）。 + 您无法替换聚合函数中的列名，例如 `COUNT(column-name)`、`AVG(column-name)` 或 `SUM(column-name)`。 + 您无法替换 JOIN 子句中的列名。 + SQL 运行时，数据将隐式转换为数据类型。有关数据类型转换的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据类型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)。 + 您不能将值设置为 NULL。数据 API 将其解释为文本字符串 `NULL`。以下示例将 `id` 替换为文本字符串 `null`。不是 SQL NULL 值。 ``` --parameters "[{\"name\": \"id\", \"value\": \"null\"}]" ``` + 无法设置零长度值。数据 API SQL 语句失败。下面的示例尝试设置 `id` 长度值为零，导致 SQL 语句失败。 ``` --parameters "[{\"name\": \"id\", \"value\": \"\"}]" ``` + 不能在带有参数的 SQL 语句中设置表名。数据 API 遵循 JDBC `PreparedStatement` 的规则。 + `describe-statement` 操作的输出返回 SQL 语句的查询参数。 + 仅 `execute-statement` 操作支持带有参数的 SQL 语句。 ## 在调用 Amazon Redshift 数据 API 时运行带有幂等性令牌的 SQL 语句 当您发出变更 API 请求时，该请求通常会在操作的异步工作流完成之前返回结果。即使请求已经返回结果，操作在完成之前也可能会超时或遇到其他服务器问题。这样就很难确定请求是否成功，并且会导致进行多次重试以确保操作成功完成。但是，如果原始请求和后续重试成功，则会多次完成操作。这意味着您可能会更新比预期更多的资源。 *幂等性*确保 API 请求完成不超过一次。对于幂等性请求，如果原始请求成功完成，则后续重试也会成功完成，而不会执行任何后续操作。数据 API `ExecuteStatement` 和 `BatchExecuteStatement` 操作具有可选的 `ClientToken` 幂等性参数。`ClientToken` 在 8 小时后过期。 **重要** 如果您从 AWS SDK 调用 `ExecuteStatement` 和 `BatchExecuteStatement` 操作，它会自动生成客户端令牌以供重试时使用。在这种情况下，我们不建议将 `client-token` 参数与 `ExecuteStatement` 和 `BatchExecuteStatement` 操作一起使用。查看 CloudTrail 日志以查看 `ClientToken`。有关 CloudTrail 日志示例，请参阅 [Amazon Redshift 数据 API 示例](logging-with-cloudtrail.md#data-api-cloudtrail)。 以下 `execute-statement` AWS CLI 命令说明了幂等性的可选 `client-token` 参数。 ``` aws redshift-data execute-statement --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "select * from stl_query limit 1" --database dev --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1 ``` 下表显示了幂等性 API 请求可能获得的一些常见响应，并提供了重试建议。 | 响应 | 建议 | 评论 | | --- | --- | --- | | 200（正常） | 不重试 | 原始请求成功完成。成功返回任何后续重试。 | | 400 系列响应代码 | 不重试 | 请求存在问题，原因如下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/data-api.html) 如果请求涉及正在改变状态的资源，则重试请求可能会成功。 | | 500 系列响应代码 | 重试 | 该错误是由 AWS 服务器端问题引起，通常是暂时性的。使用适当的退避策略重复发出请求。 | 有关 Amazon Redshift 响应代码的信息，请参阅《Amazon Redshift API 参考》**中的[常见错误](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html)。 ## 在调用 Amazon Redshift 数据 API 时运行带有会话重用的 SQL 语句 当您发出 API 请求来运行 SQL 语句时，在其中运行 SQL 的会话通常在 SQL 完成后终止。为了在指定的秒数内使会话保持活动状态，数据 API `ExecuteStatement` 和 `BatchExecuteStatement` 操作具有可选的 `SessionKeepAliveSeconds` 参数。`SessionId` 响应字段包含会话的身份，随后可以在后续 `ExecuteStatement` 和 `BatchExecuteStatement` 操作中使用该身份。在后续调用中，可以指定另一个 `SessionKeepAliveSeconds` 来更改空闲超时时间。如果未更改 `SessionKeepAliveSeconds`，则会保留初始空闲超时设置。使用会话重用时，请考虑以下事项： + `SessionKeepAliveSeconds` 的最大值为 24 小时。 + 会话最多可持续 24 小时。24 小时后，会话将被强制关闭，正在进行的查询将被终止。 + 每个 Amazon Redshift 集群或 Redshift Serverless 工作组的最大会话数为 500 个。 + 在会话中，一次只能运行一个查询。您需要等到查询完成后，才能在同一个会话中运行下一个查询。也就是说，不能在提供的会话中并行运行查询。 + 数据 API 无法对给定会话的查询进行排队。 要检索调用 `ExecuteStatement` 和 `BatchExecuteStatement` 操作时所使用的 `SessionId`，请调用 `DescribeStatement` 和 `ListStatements` 操作。 以下示例演示如何使用 `SessionKeepAliveSeconds` 和 `SessionId` 参数来使会话保持活动状态并重用。首先，在可选 `session-keep-alive-seconds` 参数设置为 `2` 的情况下调用 `execute-statement` AWS CLI 命令。 ``` aws redshift-data execute-statement --session-keep-alive-seconds 2 --sql "select 1" --database dev --workgroup-name mywg ``` 响应将包含会话标识符。 ``` { "WorkgroupName": "mywg", "CreatedAt": 1703022996.436, "Database": "dev", "DbUser": "awsuser", "Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680", "SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4" } ``` 然后，使用从第一个调用返回的 `SessionId` 来调用 `execute-statement` AWS CLI 命令。或者，指定将 `session-keep-alive-seconds` 参数设置为 `10` 以更改空闲超时值。 ``` aws redshift-data execute-statement --sql "select 1" --session-id 5a254dc6-4fc2-4203-87a8-551155432ee4 --session-keep-alive-seconds 10 ``` ## 获取 SQL 语句的结果 根据结果格式，您可以使用不同的数据 API 操作来获取 SQL 结果。在调用 `ExecuteStatement` 和 `BatchExecuteStatement` 操作时，可以指定结果的格式是 JSON 还是 CSV。如果未指定，则默认格式为 JSON。要检索 JSON 结果，请使用 `GetStatementResult` 操作。要检索 CSV 结果，请使用 `GetStatementResultV2` 操作。 以 JSON 格式返回的结果是包含有关每列的元数据的记录。每条记录都是 JSON 格式。例如，来自 `GetStatementResult` 的响应与以下内容相似： ``` { "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 } ], "NextToken": "", "Records": [ [ { "longValue": 1 } ] ], "TotalNumRows": } ``` 以 CSV 格式返回的结果是包含有关每列的元数据的记录。结果以 1 MB 的分块形式返回，其中每个分块能够以 CSV 格式存储任意数量的行。每个请求最多返回 15 MB 的结果。如果结果大于 15 MB，则返回下一页令牌以继续检索结果。例如，来自 `GetStatementResultV2` 的响应与以下内容相似： ``` { "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 } ], "NextToken": "", "Records": [ [ { "CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk }, { "CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk } ... ] ], "ResultFormat" : "CSV", "TotalNumRows": } ``` # 授予对 Amazon Redshift 数据 API 的访问权限 用户必须获得授权才能访问数据 API。您可以通过将托管式策略（预定义的 AWS Identity and Access Management (IAM) 策略）添加给用户，授予该用户访问数据 API 的权限。作为最佳实践，我们建议将权限策略附加到 IAM 角色，然后根据需要将其分配给用户和组。有关更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。要查看托管式策略允许和拒绝的权限，请参阅 IAM 控制台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))。 # 配置 IAM 权限 Amazon Redshift 提供 `AmazonRedshiftDataFullAccess` 托管式策略。此策略提供了对 Amazon Redshift 数据 API 操作的完全访问。此策略还允许将访问权限限定为特定 Amazon Redshift、AWS Secrets Manager 以及对 Amazon Redshift 集群或 Redshift Serverless 进行身份验证和访问所需的 IAM API 操作。 此外，您还可以创建自己的 IAM 策略，以允许对特定资源的访问。要创建策略，请使用 `AmazonRedshiftDataFullAccess` 策略作为起始模板。在创建策略后，将该策略添加到需要访问数据 API 的每个用户。 考虑与用户关联的 IAM 策略的以下要求： + 如果您使用 AWS Secrets Manager 进行身份验证，请确认策略允许使用 `secretsmanager:GetSecretValue` 操作来检索使用键 `RedshiftDataFullAccess` 标记的密钥。 + 如果您使用临时凭证对集群进行身份验证，请确认该策略允许将 `redshift:GetClusterCredentials` 操作用于集群中任何数据库的数据库用户名 `redshift_data_api_user`。此用户名必须已在数据库中创建。 + 如果您使用临时凭证对无服务器工作组进行身份验证，请确认该策略允许使用 `redshift-serverless:GetCredentials` 操作来检索使用键 `RedshiftDataFullAccess` 标记的工作组。数据库用户按 1:1 的比例映射到源 AWS Identity and Access Management (IAM) 身份。例如，用户 sample\$1user 映射到数据库用户 `IAM:sample_user`，而 IAM 角色 sample\$1role 映射到 `IAMR:sample_role`。有关 IAM 身份的更多信息，请参阅《IAM 用户指南》中的 [IAM 身份（用户、组和角色）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)。 + IAM 操作 `redshift-data:GetStatementResult` 同时支持访问 `GetStatementResult` 和 `GetStatementResultV2` API 操作。 以下链接提供了《IAM 用户指南》**中有关 AWS Identity and Access Management 的更多信息。 + 有关创建 IAM 角色的信息，请参阅[创建 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。 + 有关创建 IAM 策略的更多信息，请参阅[创建 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。 + 有关将 IAM 策略添加到用户的信息，请参阅[添加和删除 IAM 身份权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 ## 在其它账户拥有的集群上运行查询 要对其他账户拥有的集群运行查询，拥有账户必须提供一个 IAM 角色，数据 API 可以在调用账户时代入该角色。例如，假设账户 B 拥有账户 A 需要访问的集群。账户 B 可以将 AWS 托管式策略 `AmazonRedshiftDataFullAccess` 附加到账户 B 的 IAM 角色。然后，账户 B 使用信任策略信任账户 A，如下所示：`` ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/someRoleA" ] }, "Action": "sts:AssumeRole" } ] } ``` ------ 最后，账户 A 的 IAM 角色需要能够代入账户 B 的 IAM 角色。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::111122223333:role/someRoleB" } } ``` ------ ## 指定一个 IAM 角色，该角色将资源限制为 AWS 账户中的 Redshift Serverless 工作组和 Amazon Redshift 集群 可以在基于身份的策略中指定资源 ARN，以便控制对 AWS 账户中 Redshift Serverless 工作组和 Amazon Redshift 集群的访问权限。此示例显示如何创建一个策略，该策略只支持针对指定 AWS 账户中的工作组和集群访问数据 API。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift-data:CancelStatement", "redshift-data:DescribeStatement", "redshift-data:GetStatementResult", "redshift-data:ListStatements" ], "Resource": "*" }, { "Effect": "Allow", "Action": "redshift-data:*", "Resource": [ "arn:aws:redshift:us-east-1:111122223333:workgroup/*", "arn:aws:redshift:us-east-1:111122223333:cluster:*" ] } ] } ``` ------ ## 配置 IAM 策略，来限制只有语句所有者才能访问 SQL 语句信息 默认情况下，Amazon Redshift 数据 API 将调用 `ExecuteStatement` 和 `BatchExecuteStatement` 时使用的 IAM 角色视为 SQL 语句的所有者。任何获准代入该角色的人都可以访问有关 SQL 语句的信息，包括其结果。要将 SQL 语句信息访问权限限制为与特定所有者之间的 IAM 角色会话，请添加条件 `redshift-data:statement-owner-iam-userid: "${aws:userid}"`。以下 IAM 策略会限制访问权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift-data:CancelStatement", "redshift-data:DescribeStatement", "redshift-data:GetStatementResult", "redshift-data:ListStatements" ], "Resource": "*", "Condition": { "StringEquals": { "redshift-data:statement-owner-iam-userid": "${aws:userid}" } } } ] } ``` ------ 可以将条件 `statement-owner-iam-userid` 与 `CancelStatement`、`DescribeStatement`、`GetStatementResult` 和 `ListStatements` 结合使用。有关更多信息，请参阅 [Amazon Redshift Data API 定义的操作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)。 ## 配置 IAM 策略，来限制只有会话所有者才能访问 SQL 结果 默认情况下，Amazon Redshift 数据 API 将调用 `ExecuteStatement` 和 `BatchExecuteStatement` 时使用的 IAM 角色视为运行 SQL 语句的数据库会话的所有者。任何获准代入该角色的人都可以提交对数据库会话的查询。要将会话访问权限限制为与特定所有者之间的 IAM 角色会话，请添加条件 ` redshift-data:session-owner-iam-userid: "${aws:userid}"`。以下 IAM 策略会限制访问权限。 以下 IAM 策略仅支持会话所有者获取语句结果。条件 `session-owner-iam-userid` 用于将资源访问权限限制为指定的 `userid`。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift-data:ExecuteStatement", "redshift-data:BatchExecuteStatement" ], "Resource": "*", "Condition": { "StringEquals": { "redshift-data:session-owner-iam-userid": "${aws:userid}" } } } ] } ``` ------ 可以将条件 `session-owner-iam-userid` 与 `ExecuteStatement` 和 `BatchExecuteStatement` 结合使用。有关更多信息，请参阅 [Amazon Redshift Data API 定义的操作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)。 # 在 AWS Secrets Manager 中存储数据库凭证 在调用数据 API 时，您可以使用 AWS Secrets Manager 中的密钥传递集群或无服务器工作组的凭证。要通过此方式传递凭证，您需要指定密钥的名称或密钥的 Amazon 资源名称（ARN）。 要使用 Secrets Manager 存储凭证，您需要 `SecretManagerReadWrite` 托管式策略权限。有关最低权限的更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[使用 AWS Secrets Manager 创建和管理密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)。 **要将凭证存储在 Amazon Redshift 集群的密钥中** 1. 使用 AWS Secrets Manager 控制台创建包含集群凭证的密钥： + 当您选择**存储新密钥**时，选择**Redshift 集群的凭证**。 + 将**用户名**（数据库用户）、**密码**和 **数据库集群**（集群标识符）的值存储在您的密钥中。 + 使用键 `RedshiftDataFullAccess` 标记密钥。AWS 托管式策略 `AmazonRedshiftDataFullAccess` 只支持对使用键 `RedshiftDataFullAccess` 进行标记的密钥执行操作 `secretsmanager:GetSecretValue`。 有关说明，请参阅《AWS Secrets Manager 用户指南》**中的[创建基本密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。 1. 使用 AWS Secrets Manager 控制台查看您创建的密钥的详细信息，或运行 `aws secretsmanager describe-secret` AWS CLI 命令。 记下密钥的名称和 ARN。您可以将其用于对数据 API 的调用中。 **将凭证存储在无服务器工作组的密钥中** 1. 使用 AWS Secrets Manager AWS CLI 命令存储包含无服务器工作组凭证的密钥： + 在文件中创建密钥，例如名为 `mycreds.json` 的 JSON 文件。在文件中提供**用户名**（数据库用户）和**密码**的值。 ``` { "username": "myusername", "password": "mypassword" } ``` + 将值存储在密钥中，并使用键 `RedshiftDataFullAccess` 标记密钥。 ``` aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json ``` 下面显示了输出。 ``` { "ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf", "Name": "MyRedshiftSecret", "VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE" } ``` 有关更多信息，请参阅《AWS Secrets Manager User Guide》**中的 [Creating a Basic Secret with AWS CLI](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api)。 1. 使用 AWS Secrets Manager 控制台查看您创建的密钥的详细信息，或运行 `aws secretsmanager describe-secret` AWS CLI 命令。 记下密钥的名称和 ARN。您可以将其用于对数据 API 的调用中。 # 为数据 API 创建 Amazon VPC 终端节点 (AWS PrivateLink) 借助 Amazon Virtual Private Cloud (Amazon VPC)，您可以在 Virtual Private Cloud (VPC) 中启动 AWS 资源（例如 Amazon Redshift 集群和应用程序）。AWS PrivateLink 在亚马逊网络上提供了 Virtual Private Cloud (VPC) 和 AWS 服务之间的私有连接。通过使用 AWS PrivateLink，您可以创建 VPC 终端节点，这可让您根据 Amazon VPC 跨不同的账户和 VPC 连接到服务。有关 AWS PrivateLink 的更多信息，请参阅《Amazon Virtual Private Cloud 用户指南》**中的 [VPC 终端节点服务 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)。 您可以使用 Amazon VPC 终端节点调用数据 API。使用 Amazon VPC 终端节点可保留 Amazon VPC 中应用程序间的流量与AWS网络中的 Data API，而无需使用公有 IP 地址。Amazon VPC 终端节点可帮助您遵守与管理公共互联网连接有关的合规性和法规要求。例如，如果您使用 Amazon VPC 终端节点，则可保持 Amazon EC2 实例上运行的应用程序和包含终端节点的 VPC 中的 Data API 之间的流量。 创建 Amazon VPC 终端节点后，便能开始使用此终端节点，而无需在应用程序中进行任何代码或配置更改。 **为 Data API 创建 Amazon VPC 终端节点** 1. 登录到AWS 管理控制台并打开 Amazon VPC 控制台，网址：[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)。 1. 选择**端点**，然后选择**创建端点**。 1. 在**创建终端节点**页面上，为**服务类别**选择 **AWS 服务**。对于**服务名称**，选择 **redshift-data** (`com.amazonaws.region.redshift-data`)。 1. 对于 **VPC**，选择要在其中创建终端节点的 VPC。 选择包含用于进行 Data API 调用的应用程序的 VPC。 1. 对于**子网**，请为运行应用程序的 AWS 服务所使用的每个可用区 (AZ) 选择子网。 要创建 Amazon VPC 终端节点，请指定端点可在其中访问的私有 IP 地址范围。为此，请为每个可用区选择子网。执行此操作会将 VPC 端点限制为特定于每个可用区的私有 IP 地址范围，并且还会在每个可用区中创建一个 Amazon VPC 端点。 1. 对于**启用 DNS 名称**，选择**为此终端节点启用**。 私有 DNS 会将标准 Data API DNS 主机名 (`https://redshift-data.region.amazonaws.com`) 解析为与特定于 Amazon VPC 终端节点的 DNS 主机名关联的私有 IP 地址。因此，您可以使用 AWS CLI 或 AWS 开发工具包访问 Data API VPC 终端节点，而无需进行任何代码或配置更改来更新 Data API 终端节点 URL。 1. 对于**安全组**，选择要与 Amazon VPC 终端节点关联的安全组。 选择允许访问运行应用程序的 AWS 服务的安全组。例如，如果 Amazon EC2 实例正在运行您的应用程序，请选择允许访问 Amazon EC2 实例的安全组。利用安全组，您可以控制从 VPC 中的资源发送到 Amazon VPC 终端节点的流量。 1. 选择**Create endpoint**。 创建终端节点后，选择 AWS 管理控制台中的链接以查看终端节点详细信息。 终端节点**详细信息**选项卡将显示在创建 Amazon VPC 终端节点时生成的 DNS 主机名。 您可以使用标准终端节点 (`redshift-data.region.amazonaws.com`) 或特定于 VPC 的终端节点之一来调用 Amazon VPC 中的 Data API。标准 Data API 端点将自动路由到 Amazon VPC 端点。发生此路由的原因是，在创建 Amazon VPC 终端节点时启用了私有 DNS 主机名。 在 Data API 调用中使用 Amazon VPC 终端节点时，应用程序和 Data API 之间的所有流量将在包含它们的 Amazon VPC 中保留。可以将 Amazon VPC 终端节点用于任何类型的 Data API 调用。有关调用 Data API 的信息，请参阅[调用 Amazon Redshift 数据 API 时的注意事项](data-api.md#data-api-calling-considerations)。 # 连接到集群时加入数据库组 数据库组是数据库用户的集合。可以向组授予数据库权限。管理员可以配置 IAM 角色，以便在使用数据 API 运行您的 SQL 时，将这些数据库组考虑在内。有关数据库组的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[组](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html)。 您可以配置数据 API 调用者的 IAM 角色，以便在数据 API 连接到集群时，在调用中指定的数据库用户加入数据库组。只有在连接到预置集群时才支持此功能。连接到 Redshift Serverless 工作组时不支持此功能。数据 API 调用方的 IAM 角色还必须允许 `redshift:JoinGroup` 操作。 通过向 IAM 角色添加标签来对此进行配置。调用方 IAM 角色的管理员添加以 `RedshiftDbGroups` 为键、以数据库组列表为键值的标签。该值是以冒号 (:) 分隔的数据库组名称的列表，总长度不超过 256 个字符。必须事先在连接的数据库中定义数据库组。如果在数据库中找不到任何指定的组，则将其忽略。例如，对于数据库组 `accounting` 和 `retail`，键/值为 `accounting:retail`。标签键/值对 `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` 由数据 API 用于确定哪些数据库组与调用数据 API 时提供的数据库用户相关联。 **加入数据库组** 1. 登录AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。 1. 在控制台的导航窗格中，选择**角色**，然后选择要编辑的角色的名称。 1. 选择**标签**选项卡，然后选择**管理标签**。 1. 选择**添加标签**，然后添加键 **RedshiftDbGroups** 以及一个值，该值是 *database-groups-colon-separated* 的列表。 1. 选择**保存更改**。 现在，当 IAM 主体（附加了此 IAM 角色）调用数据 API 时，指定的数据库用户将加入在 IAM 角色中指定的数据库组。 有关如何将标签附加至主体（包括 IAM 角色和 IAM 用户）的更多信息，请参阅《IAM 用户指南》**中的[标记 IAM 资源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)部分。 # 将数据 API 与可信身份传播结合使用 作为 Amazon Redshift 账户管理员，您可以将 Amazon Redshift 集群或工作组与 AWS IAM Identity Center 集成，这有助于管理您的员工通过单点登录访问 Amazon Redshift 的权限。有关更多信息，请参阅 [设置 AWS IAM Identity Center 与 Amazon Redshift 的集成](redshift-iam-access-control-idp-connect-console.md)。Amazon Redshift 数据 API 支持将 IAM Identity Center 用户身份传播到 Amazon Redshift 集群或工作组以及链下游的其它服务，例如 AWS Lake Formation。您可以按照 [Access AWS services programmatically using trusted identity propagation](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/) 中的步骤操作，使用数据 API 进行设置和查询。 当您在身份增强型 IAM 角色会话中使用 IAM Identity Center 用户身份调用数据 API 时，您只能使用相同的 IAM Identity Center 用户访问生成的语句和语句结果。例如，以下 AWS CLI 命令调用 `execute-statement` 操作，以便使用可信身份传播来运行 SQL 命令。 ``` aws redshift-data execute-statement --sql "select current_user;" --cluster-id mycluster --database dev ``` 以下 AWS CLI 命令调用 `batch-execute-statement` 操作来运行两个 SQL 命令。 ``` aws redshift-data batch-execute-statement --sqls "select current_user;" "select current_date;" --cluster-id mycluster --database dev ``` 要访问由身份增强型 IAM 角色会话提交的具有 `cancel-statement`、`describe-statement`、`get-statement-result` 和 `get-statement-result-v2` 的语句，IAM Identity Center 用户和 IAM 角色必须与用于运行 `execute-statment` 或 `batch-execute-statement` 的凭证相匹配。例如，以下 AWS CLI 命令会获取 SQL 语句的结果。 ``` aws redshift-data get-statement-result --id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ``` 要列出语句，必须提供 `cluster-identifier` 或 `workgroup-name` 参数，以确保 IAM Identity Center 用户只能访问分配给他们的 Amazon Redshift IAM Identity Center 应用程序。例如，以下 AWS CLI 命令会列出特定集群的语句。 ``` aws redshift-data list-statements --cluster-identifier mycluster ``` 您还可以调用数据 API 操作，这些操作使用可信身份传播访问集群或工作组中的数据库对象。这包括 `list-databases`、`list-schemas`、`list-tables` 和 `describe-table` 操作。 可以在 AWS CloudTrail 中跟踪由 IAM Identity Center 用户发出的 API 调用。CloudTrail 事件的 `onBehalfOf` 部分显示了 IAM Identity Center 用户 ID 和身份存储 ARN。以下示例显示了 CloudTrail 事件的一个片段，其中显示了 `onBehalfOf` 部分，IAM Identity Center ID 为 `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`，身份存储 ARN 为 `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`。 ``` { "eventVersion":"1.10", "userIdentity":{ "type":"AssumedRole", ... }, "onBehalfOf":{ "userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2" } }, "eventTime":"2025-01-13T04:46:27Z", "eventSource":"redshift-data.amazonaws.com", "eventName":"ExecuteStatement", "awsRegion":"us-east-1" } ``` 您可以运行以下 SQL 命令来检查由 IAM Identity Center 用户提交的查询。在此示例中，在 Identity Center 中注册的电子邮件为 `username@example.com`。 ``` SELECT h.query_id, h.database_name, h.status, h.query_text, u.usename, h.start_time, h.end_time FROM sys_query_history h LEFT JOIN pg_user u ON h.user_id = u.usesysid where u.usename='awsidc:username@example.com' ORDER BY h.start_time DESC; ``` # 调用 Data API 您可以调用数据 API 或 AWS CLI 以在集群或无服务器工作组上运行 SQL 语句。运行 SQL 语句的主要操作是《Amazon Redshift Data API Reference》**中的 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) 和 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html)。数据 API 支持 AWS 开发工具包所支持的编程语言。有关它们的更多信息，请参阅[用于在 AWS 上构建的工具](https://aws.amazon.com/tools/)。 要查看调用 Data API 的代码示例，请参阅 *GitHub* 中的 [Redshift 数据 API入门](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api)。此存储库包含使用 AWS Lambda，从 Amazon EC2、AWS Glue Data Catalog 和 Amazon SageMaker Runtime 访问 Amazon Redshift 数据的示例。示例编程语言包括 Python、Go、Java 和 Javascript。 您可以使用 AWS CLI 调用 Data API。 以下示例使用 AWS CLI 调用数据 API。要运行示例，请编辑参数值以匹配您的环境。在许多示例中，会提供 `cluster-identifier` 以针对集群运行。在针对无服务器工作组运行时，需改为提供 `workgroup-name`。这些示例演示了一些数据 API 操作。有关更多信息，请参阅 *AWS CLI 命令参考*。 以下示例中的命令已被拆分和格式化以便于阅读。并非所有示例都显示了所有参数和响应。有关完整请求语法、请求参数、响应语法和响应元素的 API 定义，请参阅 [Amazon Redshift Data API Reference](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)。 # 将 SQL 语句传递到 Amazon Redshift 数据仓库 本页中的示例讲述了将 SQL 语句传递到数据仓库的不同方法 ## 运行 SQL 语句 要运行 SQL 语句，请使用 `aws redshift-data execute-statement` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用 AWS Secrets Manager 身份验证方法。 ``` aws redshift-data execute-statement --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "select * from stl_query limit 1" --database dev ``` 以下为响应示例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn" } ``` 以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用临时凭证身份验证方法。 ``` aws redshift-data execute-statement --db-user myuser --cluster-identifier mycluster-test --database dev --sql "select * from stl_query limit 1" ``` 以下为响应示例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Database": "dev", "DbUser": "myuser", "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766" } ``` 以下 AWS CLI 命令针对无服务器工作组运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用临时凭证身份验证方法。 ``` aws redshift-data execute-statement --database dev --workgroup-name myworkgroup --sql "select 1;" ``` 以下为响应示例。 ``` { "CreatedAt": "2022-02-11T06:25:28.748000+00:00", "Database": "dev", "DbUser": "IAMR:RoleName", "Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e", "WorkgroupName": "myworkgroup" } ``` 以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用 AWS Secrets Manager 身份验证方法和幂等性令牌。 ``` aws redshift-data execute-statement --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "select * from stl_query limit 1" --database dev --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1 ``` 以下为响应示例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn" } ``` ## 运行带有参数的 SQL 语句 要运行 SQL 语句，请使用 `aws redshift-data execute-statement` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用 AWS Secrets Manager 身份验证方法。SQL 文本具有命名参数 `distance`。在这种情况下，在谓词中使用的距离是 `5`。在 SELECT 语句中，列名的命名参数只能在谓词中使用。SQL 语句的命名参数值在 `parameters` 选项中指定。 ``` aws redshift-data execute-statement --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance" --parameters "[{\"name\": \"distance\", \"value\": \"5\"}]" --database dev ``` 以下为响应示例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn" } ``` 以下示例使用示例数据库中的 `EVENT` 表。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [EVENT 表](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html)。 如果您的数据库中没有 `EVENT` 表，则可以使用数据 API 创建一个，如下所示： ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "create table event( eventid integer not null distkey, venueid smallint not null, catid smallint not null, dateid smallint not null sortkey, eventname varchar(200), starttime timestamp)" ``` 以下命令将一个行插入 `EVENT` 表。 ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)" --parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"}, {\"name\": \"catid\", \"value\": \"1\"}, {\"name\": \"dateid\", \"value\": \"1\"}, {\"name\": \"eventname\", \"value\": \"event 1\"}, {\"name\": \"starttime\", \"value\": \"2022-02-22\"}]" ``` 以下命令将另一个行插入 `EVENT` 表。该示例演示以下内容： + 名为 `id` 参数在 SQL 文本中使用了四次。 + 插入参数 `starttime` 时自动应用隐式类型转换。 + `venueid` 列是转换为 SMALLINT 数据类型的类型。 + 表示 DATE 数据类型的字符串将隐式转换为 TIMESTAMP 数据类型。 + 注释可以在 SQL 文本中使用。 ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/" --parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"}, {\"name\": \"starttime\", \"value\": \"2022-02-22\"}, {\"name\": \"id\", \"value\": \"2\"}]" ``` 下面显示了两个插入的行： ``` eventid | venueid | catid | dateid | eventname | starttime ---------+---------+-------+--------+-----------+--------------------- 1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00 2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00 ``` 以下命令使用 WHERE 子句中的命名参数来检索 `eventid` 为 `1` 的行。 ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "select * from event where eventid=:id" --parameters "[{\"name\": \"id\", \"value\": \"1\"}]" ``` 运行以下命令以获取上一个 SQL 语句的 SQL 结果： ``` aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a ``` 提供以下结果： ``` { "Records": [ [ { "longValue": 1 }, { "longValue": 1 }, { "longValue": 1 }, { "longValue": 1 }, { "stringValue": "event 1" }, { "stringValue": "2022-02-22 00:00:00.0" } ] ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "eventid", "length": 0, "name": "eventid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "venueid", "length": 0, "name": "venueid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "catid", "length": 0, "name": "catid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "dateid", "length": 0, "name": "dateid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "eventname", "length": 0, "name": "eventname", "nullable": 1, "precision": 200, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "varchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "starttime", "length": 0, "name": "starttime", "nullable": 1, "precision": 29, "scale": 6, "schemaName": "public", "tableName": "event", "typeName": "timestamp" } ], "TotalNumRows": 1 } ``` ## 运行多条 SQL 语句 要使用一个命令运行多个 SQL 语句，请使用 `aws redshift-data batch-execute-statement` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行三个 SQL 语句，并返回一个标识符来获取结果。此示例使用临时凭证身份验证方法。 ``` aws redshift-data batch-execute-statement --db-user myuser --cluster-identifier mycluster-test --database dev --sqls "set timezone to BST" "select * from mytable" "select * from another_table" ``` 以下为响应示例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Database": "dev", "DbUser": "myuser", "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766" } ``` # 列出有关 SQL 语句的元数据 要列出有关 SQL 语句的元数据，请使用 `aws redshift-data list-statements` AWS CLI 命令。运行此命令的授权基于调用者的 IAM 权限。 以下 AWS CLI 命令列出了运行的 SQL 语句。 ``` aws redshift-data list-statements --status ALL ``` 以下为响应示例。 ``` { "Statements": [ { "CreatedAt": 1598306924.632, "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766", "QueryString": "select * from stl_query limit 1", "Status": "FINISHED", "UpdatedAt": 1598306926.667 }, { "CreatedAt": 1598311717.437, "Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa", "QueryString": "select * from stl_query limit 1", "Status": "FAILED", "UpdatedAt": 1598311719.008 }, { "CreatedAt": 1598313683.65, "Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c", "QueryString": "select * from stl_query limit 1", "Status": "ABORTED", "UpdatedAt": 1598313685.495 }, { "CreatedAt": 1598306653.333, "Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f", "QueryString": "select 1", "Status": "FINISHED", "UpdatedAt": 1598306653.992 } ] } ``` # 描述有关 SQL 语句的元数据 要获取 SQL 语句的元数据描述，请使用 `aws redshift-data describe-statement` AWS CLI 命令。运行此命令的授权基于调用者的 IAM 权限。 以下 AWS CLI 命令描述 SQL 语句。 ``` aws redshift-data describe-statement --id d9b6c0c9-0747-4bf4-b142-e8883122f766 ``` 以下为响应示例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Duration": 1095981511, "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766", "QueryString": "select * from stl_query limit 1", "RedshiftPid": 20859, "RedshiftQueryId": 48879, "ResultRows": 1, "ResultSize": 4489, "Status": "FINISHED", "UpdatedAt": 1598306926.667 } ``` 以下是使用多个 SQL 语句运行 `batch-execute-statement` 命令后的 `describe-statement` 响应示例。 ``` { "ClusterIdentifier": "mayo", "CreatedAt": 1623979777.126, "Duration": 6591877, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652", "RedshiftPid": 31459, "RedshiftQueryId": 0, "ResultRows": 2, "ResultSize": 22, "Status": "FINISHED", "SubStatements": [ { "CreatedAt": 1623979777.274, "Duration": 3396637, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1", "QueryString": "select 1;", "RedshiftQueryId": -1, "ResultRows": 1, "ResultSize": 11, "Status": "FINISHED", "UpdatedAt": 1623979777.903 }, { "CreatedAt": 1623979777.274, "Duration": 3195240, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2", "QueryString": "select 2;", "RedshiftQueryId": -1, "ResultRows": 1, "ResultSize": 11, "Status": "FINISHED", "UpdatedAt": 1623979778.076 } ], "UpdatedAt": 1623979778.183 } ``` # 获取 SQL 语句的结果 要从运行的 SQL 语句中获取结果，请使用 `redshift-data get-statement-result` 或 `redshift-data get-statement-result-v2` AWS CLI 命令。来自 `get-statement-result` 的结果采用 JSON 格式。来自 `get-statement-result-v2` 的结果采用 CSV 格式。您可以提供响应 `execute-statement` 或者 `batch-execute-statement` 而收到的 `Id`。可以在 `describe-statement` 的结果中检索 `batch-execute-statement` 运行的 SQL 语句的 `Id` 值，并以冒号和 `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2` 等序号为该值添加后缀。如果使用 `batch-execute-statement` 运行多个 SQL 语句，则每个 SQL 语句都有一个 `Id` 值，如 `describe-statement` 中所示。运行此命令的授权基于调用者的 IAM 权限。 以下语句返回 `execute-statement` 运行的 SQL 语句的结果，该语句让 `ResultFormat` 默认为 `JSON`。要检索结果，请调用 `get-statement-result` 操作。 ``` aws redshift-data get-statement-result --id d9b6c0c9-0747-4bf4-b142-e8883122f766 ``` 以下语句返回 `batch-execute-statement` 运行的第二个 SQL 语句的结果。 ``` aws redshift-data get-statement-result --id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2 ``` 以下是调用 `get-statement-result` 的响应示例，其中在响应的 `Records` 键中以 JSON 格式返回 SQL 结果。 ``` { "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "userid", "length": 0, "name": "userid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "query", "length": 0, "name": "query", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "label", "length": 0, "name": "label", "nullable": 0, "precision": 320, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "xid", "length": 0, "name": "xid", "nullable": 0, "precision": 19, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int8" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "pid", "length": 0, "name": "pid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "database", "length": 0, "name": "database", "nullable": 0, "precision": 32, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "querytxt", "length": 0, "name": "querytxt", "nullable": 0, "precision": 4000, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "starttime", "length": 0, "name": "starttime", "nullable": 0, "precision": 29, "scale": 6, "schemaName": "", "tableName": "stll_query", "typeName": "timestamp" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "endtime", "length": 0, "name": "endtime", "nullable": 0, "precision": 29, "scale": 6, "schemaName": "", "tableName": "stll_query", "type": 93, "typeName": "timestamp" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "aborted", "length": 0, "name": "aborted", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "insert_pristine", "length": 0, "name": "insert_pristine", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "concurrency_scaling_status", "length": 0, "name": "concurrency_scaling_status", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" } ], "Records": [ [ { "longValue": 1 }, { "longValue": 3 }, { "stringValue": "health" }, { "longValue": 1023 }, { "longValue": 15279 }, { "stringValue": "dev" }, { "stringValue": "select system_status from stv_gui_status;" }, { "stringValue": "2020-08-21 17:33:51.88712" }, { "stringValue": "2020-08-21 17:33:52.974306" }, { "longValue": 0 }, { "longValue": 0 }, { "longValue": 6 } ] ], "TotalNumRows": 1 } ``` 以下示例显示了 `execute-statement` 运行的一条 SQL 语句，该语句以 JSON 格式返回结果。表 `testingtable` 有三个整数列（col1、col2、col3），还有三行的值分别为（1、2、3）、（4、5、6）和（7、8、9）。 ``` aws redshift-data execute-statement --database dev --sql "SELECT col1, col2, col3 FROM testingtable" --cluster-id mycluster-test --result-format JSON ``` ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": "2024-04-02T16:45:25.144000+00:00", "Database": "dev", "DbUser": "IAMR:Administrator", "Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3" } ``` 以下是调用 `get-statement-result` 的响应示例，其中在响应的 `Records` 键中以 JSON 格式返回 SQL 结果。 ``` aws redshift-data get-statement-result --id d468d942-6df9-4f85-8ae3-bac01a61aec3 ``` ``` { "Records": [ [ { "longValue": 1 }, { "longValue": 2 }, { "longValue": 3 } ], [ { "longValue": 4 }, { "longValue": 5 }, { "longValue": 6 } ], [ { "longValue": 7 }, { "longValue": 8 }, { "longValue": 9 } ] ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col1", "name": "col1", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col2", "name": "col2", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col3", "name": "col3", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 } ], "TotalNumRows": 3 } ``` 以下示例显示了 `execute-statement` 运行的一条 SQL 语句，该语句以 CSV 格式返回结果。表 `testingtable` 有三个整数列（col1、col2、col3），还有三行的值分别为（1、2、3）、（4、5、6）和（7、8、9）。 ``` aws redshift-data execute-statement --database dev --sql "SELECT col1, col2, col3 FROM testingtable" --cluster-id mycluster-test --result-format CSV ``` ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": "2024-04-02T16:45:25.144000+00:00", "Database": "dev", "DbUser": "IAMR:Administrator", "Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3" } ``` 以下是调用 `get-statement-result-v2` 的响应示例，其中在响应的 `Records` 键中以 CSV 格式返回 SQL 结果。行由回车符和换行符（\$1r\$1n）分隔。`Records` 中返回的第一行是列标题。以 CSV 格式返回的结果以 1 MB 为单位返回，其中每个分块可以存储任意数量的行，最大为 1MB。 ``` aws redshift-data get-statement-result-v2 --id d468d942-6df9-4f85-8ae3-bac01a61aec3 ``` ``` { "Records": [ { "CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n" } ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col1", "name": "col1", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col2", "name": "col2", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col3", "name": "col3", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 } ], "TotalNumRows": 3, "ResultFormat": "csv" } ``` # 描述表 要获取描述表的元数据，请使用 `aws redshift-data describe-table` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回描述表的元数据。此示例使用 AWS Secrets Manager 身份验证方法。 ``` aws redshift-data describe-table --cluster-identifier mycluster-test --database dev --schema information_schema --table sql_features --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn ``` 以下为响应示例。 ``` { "ColumnList": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" } ] } ``` 以下 AWS CLI 命令针对集群运行一个 SQL 语句来描述表。此示例使用临时凭证身份验证方法。 ``` aws redshift-data describe-table --db-user myuser --cluster-identifier mycluster-test --database dev --schema information_schema --table sql_features ``` 以下为响应示例。 ``` { "ColumnList": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "sub_feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "sub_feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "is_supported", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "is_verified_by", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "comments", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" } ] } ``` # 列出集群中的数据库 要列出集群中的数据库，请使用 `aws redshift-data list-databases` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库。此示例使用 AWS Secrets Manager 身份验证方法。 ``` aws redshift-data list-databases --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev ``` 以下为响应示例。 ``` { "Databases": [ "dev" ] } ``` 以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库。此示例使用临时凭证身份验证方法。 ``` aws redshift-data list-databases --db-user myuser --cluster-identifier mycluster-test --database dev ``` 以下为响应示例。 ``` { "Databases": [ "dev" ] } ``` # 列出数据库中的架构 要列出数据库中的 schema，请使用 `aws redshift-data list-schemas` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的架构。此示例使用 AWS Secrets Manager 身份验证方法。 ``` aws redshift-data list-schemas --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev ``` 以下为响应示例。 ``` { "Schemas": [ "information_schema", "pg_catalog", "pg_internal", "public" ] } ``` 以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的架构。此示例使用临时凭证身份验证方法。 ``` aws redshift-data list-schemas --db-user mysuser --cluster-identifier mycluster-test --database dev ``` 以下为响应示例。 ``` { "Schemas": [ "information_schema", "pg_catalog", "pg_internal", "public" ] } ``` # 列出数据库中的表 要列出数据库中的表，请使用 `aws redshift-data list-tables` AWS CLI 命令。 以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的表。此示例使用 AWS Secrets Manager 身份验证方法。 ``` aws redshift-data list-tables --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev --schema information_schema ``` 以下为响应示例。 ``` { "Tables": [ { "name": "sql_features", "schema": "information_schema", "type": "SYSTEM TABLE" }, { "name": "sql_implementation_info", "schema": "information_schema", "type": "SYSTEM TABLE" } } ``` 以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的表。此示例使用临时凭证身份验证方法。 ``` aws redshift-data list-tables --db-user myuser --cluster-identifier mycluster-test --database dev --schema information_schema ``` 以下为响应示例。 ``` { "Tables": [ { "name": "sql_features", "schema": "information_schema", "type": "SYSTEM TABLE" }, { "name": "sql_implementation_info", "schema": "information_schema", "type": "SYSTEM TABLE" } ] } ``` # Amazon Redshift 数据 API 的问题排查 使用以下部分（标题为常见错误消息）帮助解决 Data API 问题。 **Topics** + [用于查询的包太大](#data-api-troubleshooting-packet-too-large) + [数据库响应超出大小限制](#data-api-troubleshooting-response-size-too-large) ## 用于查询的包太大 如果您看到一条错误，指示查询的数据包过大，则为行返回的结果集通常过大。数据库返回的结果集中的 Data API 大小限制为每行 64 KB。 要解决此问题，请确保结果集中的每一行都小于或等于 64 KB。 ## 数据库响应超出大小限制 如果您看到一条错误，指示数据库响应超出了大小限制，则数据库返回的结果集的大小通常太大。数据库返回的结果集中的数据 API 限制为 500 MB。 要解决此问题，请确保对数据 API 的调用返回 500 MB 或更少的数据。如果需要返回 500 MB 以上的数据，则可以在查询中将多个语句调用与 `LIMIT` 子句结合使用。 # 使用 Amazon EventBridge 计划 Amazon Redshift 数据 API 操作 您可以创建规则来匹配选定的事件，并将它们路由到目标以采取操作。此外，您还可以使用规则对预定的计划采取操作。有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。 要使用 EventBridge 计划数据 API 操作，关联的 IAM 角色必须信任 CloudWatch Events (events.amazonaws.com) 的委托人。此角色应附加相当于托管式策略 `AmazonEventBridgeFullAccess` 的策略。它还应具有 `AmazonRedshiftDataFullAccess` 策略权限，这些权限由数据 API 管理。您可以在 IAM 控制台上创建具有这些权限的 IAM 角色。在 IAM 控制台上创建角色时，为 CloudWatch Events 选择 AWS 服务可信任实体。在 EventBridge 目标的 `RoleArn` JSON 值中指定 IAM 角色。有关创建 IAM 角色的更多信息，请参阅《IAM 用户指南》**中的[为 AWS 服务创建角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)。 您在 Amazon EventBridge 中创建的规则的 `name` 必须与 `RedshiftDataParameters` 中的 `StatementName` 相匹配。 以下示例显示了使用单个或多个 SQL 语句创建 EventBridge 规则的变体，并将 Amazon Redshift 集群或 Amazon Redshift Serverless 工作组作为数据仓库。 ## 对集群执行包含单个 SQL 语句的调用 以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift 集群运行 SQL 语句。 ``` aws events put-rule --name test-redshift-cluster-data --schedule-expression "rate(1 minute)" ``` 然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。 ``` aws events put-targets --cli-input-json file://data.json ``` 输入 data.json 文件如下。`Sql` JSON 键表示只有一个 SQL 语句。`Arn` JSON 值包含集群标识符。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。 ``` { "Rule": "test-redshift-cluster-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "DbUser": "root", "Sql": "select 1;", "StatementName": "test-redshift-cluster-data", "WithEvent": true } } ] } ``` ## 使用单个 SQL 语句和工作组进行调用 以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift Serverless 工作组运行一个 SQL 语句。 ``` aws events put-rule --name test-redshift-serverless-workgroup-data --schedule-expression "rate(1 minute)" ``` 然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。 ``` aws events put-targets --cli-input-json file://data.json ``` 输入 data.json 文件如下。`Sql` JSON 键表示只有一个 SQL 语句。`Arn` JSON 值包含工作组名称。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。 ``` { "Rule": "test-redshift-serverless-workgroup-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "Sql": "select 1;", "StatementName": "test-redshift-serverless-workgroup-data", "WithEvent": true } } ] } ``` ## 对集群执行包含多个 SQL 语句的调用 以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift 集群运行多个 SQL 语句。 ``` aws events put-rule --name test-redshift-cluster-data --schedule-expression "rate(1 minute)" ``` 然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。 ``` aws events put-targets --cli-input-json file://data.json ``` 输入 data.json 文件如下。`Sqls` JSON 键表示有多个 SQL 语句。`Arn` JSON 值包含集群标识符。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。 ``` { "Rule": "test-redshift-cluster-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "Sqls": ["select 1;", "select 2;", "select 3;"], "StatementName": "test-redshift-cluster-data", "WithEvent": true } } ] } ``` ## 使用多个 SQL 语句和工作组进行调用 以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift Serverless 工作组运行多个 SQL 语句。 ``` aws events put-rule --name test-redshift-serverless-workgroup-data --schedule-expression "rate(1 minute)" ``` 然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。 ``` aws events put-targets --cli-input-json file://data.json ``` 输入 data.json 文件如下。`Sqls` JSON 键表示有多个 SQL 语句。`Arn` JSON 值包含工作组名称。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。 ``` { "Rule": "test-redshift-serverless-workgroup-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "Sqls": ["select 1;", "select 2;", "select 3;"], "StatementName": "test-redshift-serverless-workgroup-data", "WithEvent": true } } ] } ``` # 监控数据 API 监控是保持数据 API 和您的其他 AWS 解决方案的可靠性、可用性和性能的重要方面。AWS 提供了以下一些监控工具来监控数据 API、在出现错误时进行报告并适时自动采取措施： + 您可以使用 Amazon EventBridge 自动执行您的 AWS 服务并自动响应系统事件，例如应用程序可用性问题或资源更改。AWS 服务中的事件将近乎实时地传输到 EventBridge。您可以编写简单的规则来指示您关注的事件，并指示要在事件匹配规则时执行的自动化操作。有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。 + AWS CloudTrail 捕获由您的 AWS 账户或代表该账户发出的 API 调用和相关事件，并将日志文件传输到您指定的 Amazon S3 桶。您可以标识哪些用户和账户调用了 AWS、发出调用的源 IP 地址以及调用的发生时间。要了解有关 Amazon Redshift 如何与 AWS CloudTrail 集成的更多信息，请参阅[使用 Cloudtrail 进行日志记录](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html)。有关 CloudTrail 的更多信息，请参阅《AWS CloudTrail 用户指南》[https://docs.aws.amazon.com/awscloudtrail/latest/userguide/](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。 **Topics** + [在 Amazon EventBridge 中监控 Amazon Redshift 数据 API 的事件](data-api-monitoring-events.md) # 在 Amazon EventBridge 中监控 Amazon Redshift 数据 API 的事件 您可以在 EventBridge 中监控数据 API，这将从您自己的应用程序、软件即服务 (SaaS) 应用程序和 AWS 服务传输实时数据流。EventBridge 将该数据路由到诸如 AWS Lambda 和 Amazon SNS 之类的目标。这些事件与 CloudWatch Events 中出现的事件相同，可提供近乎实时的系统事件流，这些系统事件描述 AWS 资源的变化。事件将发送到包含 Amazon Redshift 数据库的账户。例如，如果您担任另一个账户中的角色，则事件将发送到该账户。有关更多信息，请参阅《Amazon EventBridge 用户指南》**中的 [Amazon EventBridge 事件](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)。 当 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作将 `WithEvent` 选项设置为 `true` 时，将发送数据 API 事件。事件的 `state` 字段包含以下值之一： + 中止 – 用户停止了查询运行。 + FAILED – 查询运行失败。 + FINISHED – 查询已完成运行。 事件会确保送达。有关更多信息，请参阅《Amazon EventBridge 用户指南》**中的 [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)。 ## 数据 API 完成事件示例 以下示例在 `ExecuteStatement` API 操作完成时显示数据 API 的一个事件。在以下示例中，名为 `test.testtable` 的语句运行完成。 ``` { "version": "0", "id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0", "detail-type": "Redshift Data Statement Status Change", "source": "aws.redshift-data", "account": "123456789012", "time": "2020-10-01T21:14:26Z", "region": "us-east-1", "resources": [ "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1" ], "detail": { "principal": "arn:aws:iam::123456789012:user/myuser", "statementName": "test.testtable", "statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a", "redshiftQueryId": -1, "state": "FINISHED", "rows": 1, "expireAt": 1601673265 } } ``` # 结合使用 AWS KMS 与 Amazon Redshift Data API 在使用客户自主管理型密钥对 Amazon Redshift 集群或 Redshift Serverless 工作组进行加密时，Amazon Redshift Data API 会使用相同的客户自主管理型密钥来存储和加密您的查询与结果。 默认情况下，Data API 会加密您的数据以保护敏感信息，例如查询文本和查询结果。它使用 AWS 拥有的 AWS KMS 加密密钥来实施此保护措施。 静态数据的默认加密可降低保护敏感数据时的运营开销和复杂性。此方法有助于构建符合严格加密合规性和监管要求的安全应用程序。 ## 使用 AWS KMS 中的授权 Data API 需要授权才能使用客户自主管理型密钥。 在对已使用客户自主管理型密钥加密的集群调用 `ExecuteStatement` 或 `BatchExecuteStatement` 时，Amazon Redshift 会通过向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) 请求来代表您创建授权。AWS KMS 通过授权向数据 API 授予对您账户中的 KMS 密钥的访问权限。 Data API 需要授权，才能将客户自主管理型密钥用于以下操作： + 向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) 请求，以使用客户自主管理型密钥对查询元数据进行加密。 + 向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) 请求，以生成由客户自主管理型密钥加密的数据密钥。 + 向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 请求，以对已加密的数据密钥进行解密，从而使用这些密钥对您的数据进行加密。 您可以随时撤销对授权的访问权限，或者删除 Amazon Redshift 对客户自主管理型密钥的访问权限。如果您这样做，Data API 将不再能访问由客户自主管理型密钥加密的数据，这会影响依赖于该数据的操作。例如，如果您在撤销授权后尝试检索查询结果或跟踪查询状态，则 Data API 会返回 `AccessDeniedException`。 ## 客户自主管理型密钥的密钥策略 密钥政策控制对客户托管密钥的访问。每个客户托管式密钥必须只有一个密钥策略，其中包含确定谁可以使用密钥以及如何使用密钥的声明。创建客户托管式密钥时，可以指定密钥策略。有关更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[客户托管密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key)。 要结合使用您的客户自主管理型密钥与 Data API，您必须先允许访问 Amazon Redshift。密钥策略中必须允许以下 API 操作： + `kms:CreateGrant`：向客户托管密钥添加授权。这些授权控制对指定 AWS KMS 密钥的访问权限，从而允许访问 Amazon Redshift 所需的授权操作。有关更多信息，请参阅[在 AWS KMS 中使用授权](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations)。 以下是示例密钥策略： ``` "Statement":[ { "Sid":"Allow access to principals authorized to use Amazon Redshift", "Effect":"Allow", "Principal":{ "AWS":"*" }, "Action":[ "kms:DescribeKey", "kms:CreateGrant" ], "Resource":"*", "Condition":{ "StringEquals":{ "kms:ViaService":"redshift.amazonaws.com", "kms:CallerAccount":"111122223333" } } }, { "Sid":"AllowKeyAdministratorsAccess", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole" }, "Action":"kms:*", "Resource":"*" }, { "Sid":"AllowKeyUseForExampleRole", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:role/ExampleUserRole" }, "Action":[ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource":"*" } ] ``` ## Data API 加密上下文 加密上下文是一组可选的键值对，包含有关数据的其他上下文信息。AWS KMS 会将加密上下文用作其他已经过验证的数据以支持经过身份验证的加密。在请求中包含加密上下文以加密数据时，AWS KMS 将加密上下文绑定到加密的数据。要解密数据，您必须在请求中包含相同的加密上下文。 Data API 在预调配集群的所有 AWS KMS 加密操作中使用相同的三个加密上下文键值对： + `aws:redshift:arn`：集群的 Amazon 资源名称（ARN） + `aws:redshift:createtime`：请求创建集群时的时间戳 + `serviceName` – `RedshiftDataAPI` ``` "EncryptionContextSubset": { "aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster", "aws:redshift:createtime": "20250815T0000Z", "serviceName": "RedshiftDataAPI", } ``` Data API 在无服务器工作组的所有 AWS KMS 加密操作中使用两个加密上下文键值对： + `aws:redshift-serverless:arn`：命名空间的 Amazon 资源名称（ARN） + `serviceName`：RedshiftDataAPI ``` "EncryptionContextSubset": { "aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012", "serviceName": "RedshiftDataAPI" } ``` 有关加密的更多信息，请参阅 [AWS KMS 的加密详细信息简介](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html)。有关 Amazon Redshift 和 AWS KMS 集成的更多信息，请参阅 [Amazon Redshift 使用 AWS KMS 的方式](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html)。 # 使用 Amazon SageMaker 融通式合作开发工作室在 Amazon Redshift 和 SageMaker 智能湖仓中查询您的数据库 Amazon SageMaker 融通式合作开发工作室提供一个非控制台开发环境，并支持对 SageMaker 智能湖仓、Amazon Redshift 和 Amazon Athena 中的数据进行 SQL 分析来实现 SQL 分析。使用管理员提供的 URL 导航至 Amazon SageMaker 融通式合作开发工作室，然后使用您的 SSO 或 AWS 凭证进行登录。有关设置第一个项目的更多信息，请参阅《Amazon SageMaker Unified Studio User Guide》**中的 [Getting started](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/getting-started.html)。 在 Amazon SageMaker 融通式合作开发工作室中，可以通过使用 [query editor](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/query-editor-navigate.html) 运行 Amazon Redshift 和 Amazon Athena 来执行 [SQL analytics](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/sql-query.html)。使用查询编辑器来编写和运行查询、查看结果以及与团队共享您的工作。在您的 AWS 账户中（在同一账户内和跨其它 AWS 账户）针对 Redshift 数据仓库运行查询，使用相同的界面为 Redshift 和 Athena 构建 SQL 查询，并使用 Amazon Managed Workflows for Apache Airflow 安排 SQL 查询。还可以使用 Amazon Q 生成式 SQL，根据自然语言生成 SQL。