# 使用兼容 PostgreSQL 的客户端访问 Aurora DSQL
<a name="accessing"></a>

Aurora DSQL 使用 [PostgreSQL 有线协议](https://www.postgresql.org/docs/current/protocol.html)。您可以通过各种工具和客户端（例如，AWS CloudShell、psql、DBeaver 和 DataGrip）连接到 PostgreSQL。下表汇总了 Aurora DSQL 与常见 PostgreSQL 连接参数的对应关系：


| PostgreSQL | Aurora DSQL | 备注 | 
| --- | --- | --- | 
| 角色（也称为用户或组） | 数据库角色 | Aurora DSQL 为您创建一个名为 admin 的角色。当您创建自定义数据库角色时，您必须使用 admin 角色将其与 IAM 角色关联，以便在连接到集群时进行身份验证。有关更多信息，请参阅 [使用数据库角色和 IAM 身份验证](using-database-and-iam-roles.md)。 | 
| 主机（也称为主机名或主机规格） | 集群端点 | Aurora DSQL 单区域集群提供单个托管式端点，当区域内出现不可用性问题时会自动重定向流量。 | 
| 端口 | 不适用：使用默认值 5432 | 这是 PostgreSQL 默认值。 | 
| 数据库（dbname） | 使用 postgres | Aurora DSQL 会在您创建集群时为您创建此数据库。 | 
| SSL 模式 | 始终在服务器端启用 SSL | 在 Aurora DSQL 中，Aurora DSQL 支持 require SSL 模式。Aurora DSQL 会拒绝没有 SSL 的连接。 | 
| 密码 | 身份验证令牌 | Aurora DSQL 需要临时身份验证令牌，而不是长期密码。要了解更多信息，请参阅[在 Amazon Aurora DSQL 中生成身份验证令牌](SECTION_authentication-token.md)。 | 

连接时，Aurora DSQL 要求使用签名的 IAM [身份验证令牌](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html)替代传统密码。这些临时令牌通过 AWS 签名版本 4 生成，并且仅在建立连接期间使用。建立连接后，会话将保持活动状态，直至会话结束或客户端断开连接。

如果您尝试使用过期的令牌打开新会话，连接请求将失败，并且必须生成新令牌。有关更多信息，请参阅 [在 Amazon Aurora DSQL 中生成身份验证令牌](SECTION_authentication-token.md)。

## 使用 SQL 客户端访问 Aurora DSQL
<a name="accessing-sql-clients"></a>

Aurora DSQL 支持通过多种兼容 PostgreSQL 的客户端来连接到您的集群。以下各部分介绍如何使用 AWS CloudShell 或本地命令行通过 PostgreSQL 进行连接，以及如何使用基于 GUI 的工具（例如 DBeaver 和 JetBrains DataGrip）进行连接。每个客户端均需要一个有效的身份验证令牌，如上一部分所述。

**Topics**
+ [使用 SQL 客户端访问 Aurora DSQL](#accessing-sql-clients)
+ [使用 DBeaver 访问 Aurora DSQL](accessing-dbeaver.md)
+ [使用 JetBrains DataGrip 访问 Aurora DSQL](accessing-datagrip.md)
+ [使用 PostgreSQL 交互式终端（psql）访问 Aurora DSQL](accessing-psql.md)
+ [使用适用于 SQLTools 的 Aurora DSQL 驱动程序](accessing-vscode.md)
+ [问题排查](#accessing-troubleshooting)

# 使用 DBeaver 访问 Aurora DSQL
<a name="accessing-dbeaver"></a>

DBeaver 是一款通用 SQL 客户端，可用于管理任何具有 JDBC 驱动程序的数据库。由于其强大的数据查看、编辑和管理功能，该工具被开发人员和数据库管理员广泛使用。使用 DBeaver 的云连接选项，可将 DBeaver 以原生方式连接到 Aurora DSQL。

## DBeaver Pro
<a name="dbeaver-pro"></a>

从版本 25.3 开始，DBeaver PRO 产品提供与 Aurora DSQL 的原生集成。按照 [DBeaver Documentation](https://dbeaver.com/docs/dbeaver/Database-driver-Aurora-DSQL/) 中的说明连接到 Aurora DSQL 集群。

## DBeaver 社区版
<a name="dbeaver-community"></a>

DBeaver 社区版是免费的开源版本。请访问[下载页面](https://dbeaver.io/download/)以查看安装说明。要从 DBeaver 社区版连接到 DSQL，您需要安装 [Aurora DSQL Plugin for DBeaver](https://github.com/awslabs/aurora-dsql-dbeaver-plugin)。

[Aurora DSQL Plugin for DBeaver](https://github.com/awslabs/aurora-dsql-dbeaver-plugin) 在 [Aurora DSQL Connector for JDBC](https://github.com/awslabs/aurora-dsql-jdbc-connector) 之上构建，支持对 Aurora DSQL 集群进行 IAM 身份验证。它可通过 DBeaver UI 方便地安装，无需编写令牌生成代码或手动提供有效的 IAM 令牌，从而简化了身份验证，同时消除了与传统用户生成的密码关联的安全风险。

### 功能
<a name="features"></a>
+  IAM 身份验证支持：使用 AWS IAM 凭证连接到 Aurora DSQL 集群，以实现安全、免密码的身份验证 
+  自动驱动程序管理：无缝地安装和配置适用于 JDBC 的 Aurora DSQL 连接器 
+  灵活的连接选项：在基于主机的连接配置或基于 JDBC URL 的连接配置之间选择 

### 适用于 DBeaver 的 Aurora DSQL 插件安装
<a name="installation"></a>

1.  打开 DBeaver 后，转至下拉菜单**帮助** → **安装新软件** 

1.  单击**添加**以添加新的存储库 

1.  输入：
   +  **名称**：`Aurora DSQL Plugin`
   +  **位置**：`https://awslabs.github.io/aurora-dsql-dbeaver-plugin/update-site/`

1.  选择**适用于 JDBC 的 Aurora DSQL 连接器** 

1.  单击**下一步**，接受许可证，然后完成安装 

1.  当系统提示时，重新启动 DBeaver 

### 创建 Aurora DSQL 连接
<a name="create-connection"></a>

1.  单击**新建数据库连接** 

1.  选择 **Aurora DSQL** 

1.  在**服务器**下，为**连接方式**设置选择以下选项之一 
   + **主机** 
     +  为以下字段启用用户界面文本输入：
       +  **端点：**DSQL 集群端点 
       +  **用户名：**DSQL 用户名（例如 admin） 
       +  **AWS 配置文件：**例如，默认配置文件，即未指定特定配置文件时使用的标准配置文件 
       +  **AWS 区域（可选）：**必须与您的 DSQL 集群所在的区域匹配，否则身份验证将失败 
   +  ** URL** 
     + 采用以下格式的 JDBC URL：

       ```
       jdbc:aws-dsql:postgresql://{cluster_endpoint}/{database}?user=admin&profile=default&region=us-east-1
       ```
     +  注意：在此模式下，仅启用 URL 输入。为了向 JDBC 连接字符串添加参数，请使用以 ? 开头的 URL 查询参数格式作为第一个参数，并为后续参数附加一个 &。

1.  单击**测试连接**以验证 Aurora DSQL 连接是否有效 

1.  单击**完成** 

## 问题排查
<a name="troubleshooting"></a>

### Windows Trust Store 问题
<a name="windows-trust-store"></a>

Windows 用户在从 Maven Central 下载适用于 JDBC 的 Aurora DSQL 连接器驱动程序时可能会遇到问题。

**原因：**Windows Trust Store 可能不包含访问 Maven Central 存储库所需的证书。

**解决方案：**

1. 以“管理员”身份运行 DBeaver

1. 取消选中此设置：Windows > 偏好设置 > 连接 >“使用 Windows Trust Store”

### 缺失驱动程序错误
<a name="missing-driver"></a>

如果您看到缺失驱动程序图标或连接错误，则说明您当前的 DBeaver 版本中可能未安装 Aurora DSQL（社区插件）。以下是一些错误示例及其修复方法：
+ 创建与缺失驱动程序的新连接：  
![\[DBeaver 中的缺失驱动程序图标\]](http://docs.aws.amazon.com/zh_cn/aurora-dsql/latest/userguide/images/dbeaver-missing-driver-icon.png)
+ 尝试在没有驱动程序的情况下进行连接：  
![\[缺失驱动程序时的错误对话框\]](http://docs.aws.amazon.com/zh_cn/aurora-dsql/latest/userguide/images/dbeaver-version-error-dialog.png)

**原因：**安装多个 DBeaver 版本时，连接设置是共享的，但驱动程序是按应用程序单独安装的。

**解决方案：**按照上述安装步骤重新安装 Aurora DSQL（社区插件）。



**重要**  
DBeaver 为 PostgreSQL 数据库提供的管理功能（如**会话管理器**和**锁定管理器**）由于其独特的架构而不适用于 Aurora DSQL 数据库。虽然这些屏幕可供访问，但它们不提供有关数据库运行状况或状态的可靠信息。

# 使用 JetBrains DataGrip 访问 Aurora DSQL
<a name="accessing-datagrip"></a>

JetBrains DataGrip 是一款跨平台 IDE，用于处理 SQL 和数据库，包括 PostgreSQL。DataGrip 包含一个强大的图形用户界面和一个智能 SQL 编辑器。要下载 DataGrip，请转至 *JetBrains* 网站上的[下载页面](https://www.jetbrains.com/datagrip/download)。

**在 JetBrains DataGrip 中设置新的 Aurora DSQL 连接**

1. 选择**新建数据来源**，然后选择 PostgreSQL。

1. 在**数据来源/常规**选项卡中，输入以下信息：

   1. **主机**：使用您的集群端点。

     **端口**：Aurora DSQL 使用 PostgreSQL 默认值：`5432`

     **数据库**：Aurora DSQL 使用 PostgreSQL 默认值 `postgres` 

     **身份验证**：选择 `User & Password `。

     **用户名**：输入 `admin`。

     **密码**：[生成令牌](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html)并将其粘贴到此字段中。

     **URL**：请勿修改此字段。它将根据其它字段自动填充。

1.  **密码**：通过生成身份验证令牌来提供密码。复制令牌生成器的结果输出，并将其粘贴到密码字段中。
**注意**  
您必须在客户端连接中设置 SSL 模式。Aurora DSQL 支持 `PGSSLMODE=require and PGSSLMODE=verify-full`。Aurora DSQL 在服务器端强制执行 SSL 通信，并拒绝非 SSL 连接。对于 `verify-full` 选项，您需要本地安装 SSL 证书。有关更多信息，请参阅 [SSL/TLS 证书](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/configure-root-certificates.html)。

1. 您应该已连接到集群，并可以开始运行 SQL 语句：

**重要**  
DataGrip 为 PostgreSQL 数据库提供的某些视图（例如会话）由于其独特的架构而不适用于 Aurora DSQL 数据库。虽然这些屏幕可供访问，但它们不提供有关连接到数据库的实际会话的可靠信息。

# 使用 PostgreSQL 交互式终端（psql）访问 Aurora DSQL
<a name="accessing-psql"></a>

## 使用 AWS CloudShell 通过 PostgreSQL 交互式终端（psql）访问 Aurora DSQL
<a name="accessing-sql-clients-psql"></a>

按照以下过程操作，使用 AWS CloudShell 通过 PostgreSQL 交互式终端访问 Aurora DSQL。有关更多信息，请参阅[什么是 AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html)。

**使用 AWS CloudShell 进行连接**

1. 登录 [Aurora DSQL 控制台](https://console.aws.amazon.com/dsql)。

1. 选择要在 CloudShell 中打开的集群。如果您尚未创建集群，请按照[步骤 1：创建 Aurora DSQL 单区域集群](getting-started.md#getting-started-create-cluster)或[创建多区域集群](getting-started.md#getting-started-multi-region)中的步骤操作。

1. 选择**使用查询编辑器进行连接**，然后选择**使用 CloudShell 进行连接**。

1. 选择是要以管理员身份还是要使用[自定义数据库角色](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html#authentication-authorization-iam-role-connect)进行连接。

1. 选择**在 CloudShell 中启动**，然后在以下 CloudShell 对话框中选择**运行**。

## 使用本地 CLI 通过 PostgreSQL 交互式终端（psql）访问 Aurora DSQL
<a name="accessing-sql-clients-psql-local"></a>

使用 `psql`（一款基于终端的 PostgreSQL 前端实用程序）可通过交互方式输入查询，将查询发送到 PostgreSQL，并查看查询结果。

**注意**  
要缩短查询响应时间，请使用 PostgreSQL 版本 17 客户端。如果您在不同的环境中使用 CLI，请务必手动设置 Python 版本 3.8\$1 和 psql 版本 14\$1。

从 [PostgreSQL Downloads](https://www.postgresql.org/download/) 页面下载操作系统的安装程序。有关 `psql` 的更多信息，请参阅 *PostgreSQL* 网站上的 [PostgreSQL 客户端应用程序](https://www.postgresql.org/docs/current/app-psql.htm)。

如果您已经安装了 AWS CLI，请使用以下示例连接到集群。

```
# Aurora DSQL requires a valid IAM token as the password when connecting.  
# Aurora DSQL provides tools for this and here we're using Python.  
export PGPASSWORD=$(aws dsql generate-db-connect-admin-auth-token \
  --region us-east-1 \
  --expires-in 3600 \
  --hostname your_cluster_endpoint)  
  
# Aurora DSQL requires SSL and will reject your connection without it.  
export PGSSLMODE=require  
  
# Connect with psql, which automatically uses the values set in PGPASSWORD and PGSSLMODE.  
# Quiet mode suppresses unnecessary warnings and chatty responses but still outputs errors.  
psql --quiet \
  --username admin \
  --dbname postgres \
  --host your_cluster_endpoint
```

# 使用适用于 SQLTools 的 Aurora DSQL 驱动程序
<a name="accessing-vscode"></a>

 适用于 SQLTools 的 Aurora DSQL 驱动程序是 Amazon Aurora DSQL 的 Visual Studio 代码扩展，与 SQLTools 相集成。它使开发人员能够直接从 VS Code 连接和查询 Aurora DSQL 数据库。该驱动程序可从 [Visual Studio Marketplace](https://marketplace.visualstudio.com) 和 [Open VSX Registry](https://open-vsx.org/) 安装。Kiro、Cursor 和其它基于 VSCode 的 IDE 可以使用 [Open VSX Registry](https://open-vsx.org/)，以便按照本页中描述的标准安装过程安装驱动程序。

## 功能
<a name="features"></a>
+  自动 IAM 身份验证 
+  标准数据库操作，例如浏览架构、表和执行 SQL 查询。

## 安装
<a name="installation"></a>

1.  打开“扩展”视图。

1.  搜索“适用于 SQLTools 的 Aurora DSQL 驱动程序”。

1.  单击“安装”。

 **注意。**

 如果 [SQLTools 扩展](https://vscode-sqltools.mteixeira.dev)尚不存在，则会自动安装该扩展。

## 身份验证
<a name="authentication"></a>

 在 Aurora DSQL 中，所有连接都使用**基于 IAM 的身份验证**以及限时令牌。该驱动程序使用 [Aurora DSQL Connector for node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) 来自动处理 Aurora DSQL 身份验证。

 有关 Aurora DSQL 中的身份验证的更多信息，请参阅[用户指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。

## 创建 Aurora DSQL 连接
<a name="create-an-aurora-dsql-connection"></a>

### 先决条件
<a name="prerequisites"></a>
+  已配置 AWS 凭证（通过 AWS CLI、环境变量或 IAM 角色）。

### Steps
<a name="steps"></a>

1.  在左侧边栏中单击 SQLTools 图标。

1.  在 SQLTools 窗格中，将鼠标悬停在“连接”上方，然后单击“添加新连接”图标。

1.  在 SQLTools 的“设置”选项卡中，从列表中选择“Aurora DSQL 驱动程序”。

1.  填入连接参数。
   +  AWS 区域 
     +  可选：将从 Aurora DSQL 集群端点解析区域。
     +  在 DSQL 集群字段中仅指定集群 ID 时为必填项。
   +  AWS 配置文件 
     +  用于生成令牌。
     +  如果未指定，则使用默认配置文件。

1.  单击“测试连接按钮”以测试连接。

1.  单击“保存连接”。

## 问题排查
<a name="accessing-troubleshooting"></a>

**SQL 客户端的身份验证凭证过期**

已建立的会话会在最多 1 小时内保持身份验证状态，或者直到出现显式断开连接或客户端超时。如果需要建立新连接，则必须在连接的**密码**字段中生成并提供新的身份验证令牌。尝试打开新会话（例如，列出新表或打开新的 SQL 控制台）会强制尝试新的身份验证。如果在**连接**设置中配置的身份验证令牌不再有效，则该新会话将失败，并且所有先前打开的会话将变为无效。在通过 `expires-in` 选项选择 IAM 身份验证令牌的持续时间时，请记住一点：该持续时间默认设置为 15 分钟，最大值可设置为 7 天。

此外，请参阅 Aurora DSQL 文档的[故障排除](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/troubleshooting.html)部分。