# 适用于 node-postgres 的 Aurora DSQL 连接器
<a name="SECTION_program-with-dsql-connector-for-node-postgres"></a>

 [Aurora DSQL Connector for node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) 是一款基于 [node-postgres](https://node-postgres.com/) 构建的 Node.js 连接器，它集成了 IAM 身份验证功能，可用于将 JavaScript/TypeScript 应用程序连接到 Amazon Aurora DSQL 集群。

 经设计，Aurora DSQL 连接器可作为身份验证插件，对 node-postgres 客户端和池的功能进行扩展，使应用程序能够使用 IAM 凭证与 Amazon Aurora DSQL 进行身份验证。

## 关于连接器
<a name="about-the-connector"></a>

 Amazon Aurora DSQL 是一款兼容 PostgreSQL 的云原生分布式数据库。该数据库要求使用 IAM 身份验证和有时限的令牌，而传统的 Node.js 数据库驱动程序缺少此内置支持。

 适用于 node-postgres 的 Aurora DSQL 连接器通过实施可与 node-postgres 无缝协作的身份验证中间件，弥补了这一不足。此方法可让开发人员保留现有的 node-postgres 代码，并通过自动化令牌管理，获得对 Aurora DSQL 集群的基于 IAM 的安全访问权限。

### 什么是 Aurora DSQL 身份验证？
<a name="what-is-aurora-dsql-authentication"></a>

 在 Aurora DSQL 中，身份验证包括：
+  **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌 
+  **令牌生成：**使用 AWS 凭证生成身份验证令牌，其生命周期可配置 

 适用于 node-postgres 的 Aurora DSQL 连接器针对这些要求而设计，在建立连接时自动生成 IAM 身份验证令牌。

### 功能
<a name="features"></a>
+  **自动 IAM 身份验证**：处理 DSQL 令牌的生成与刷新 
+  **基于 node-postgres 构建**：借助适用于 Node.js 的常用 PostgreSQL 客户端 
+  **无缝集成**：适用于现有 node-postgres 连接模式 
+  **区域自动发现**：从 DSQL 集群主机名中提取 AWS 区域 
+  **完整 TypeScript 支持**：提供完全类型安全性 
+  **AWS 凭证支持**：支持各种 AWS 凭证提供者（默认、基于配置文件、自定义） 
+  **连接池兼容性**：与内置连接池无缝协作 

## 示例应用程序
<a name="example-application"></a>

 [example](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example) 中包含一个示例应用程序，展示了如何使用适用于 node-postgres 的 Aurora DSQL 连接器。要运行包含的示例，请参阅示例 [README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)。

## 快速入门指南
<a name="quick-start-guide"></a>

### 要求
<a name="requirements"></a>
+  Node.js 20\$1 
+  [有权访问 Aurora DSQL 集群](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  设置适当的 IAM 权限，以允许应用程序连接到 Aurora DSQL。
+  已配置 AWS 凭证（通过 AWS CLI、环境变量或 IAM 角色）。

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

```
npm install @aws/aurora-dsql-node-postgres-connector
```

## 对等依赖项
<a name="peer-dependencies"></a>

```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```

## 用法
<a name="usage"></a>

### 客户端连接
<a name="client-connection"></a>

```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

### 池连接
<a name="pool-connection"></a>

```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";

const pool = new AuroraDSQLPool({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
  max: 3,
  idleTimeoutMillis: 60000,
});

const result = await pool.query("SELECT NOW()");
```

### 高级用法
<a name="advanced-usage"></a>

```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "example.dsql.us-east-1.on.aws",
  user: "admin",
  customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});

await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

## 配置选项
<a name="configuration-options"></a>


|  Option  |  类型  |  必需  |  描述  | 
| --- | --- | --- | --- | 
|  host  |  string  |  是  |  DSQL 集群主机名  | 
|  username  |  string  |  是  |  DSQL 用户名  | 
|  database  |  string  |  否  |  数据库名称  | 
|  region  |  string  |  否  |  AWS 区域（如果未提供，则自动从主机名中检测）  | 
|  port  |  number  |  否  |  默认值为 5432  | 
|  customCredentialsProvider  |  AwsCredentialIdentity / AwsCredentialIdentityProvider  |  否  |  自定义 AWS 凭证提供者  | 
|  profile  |  string  |  否  |  IAM 配置文件名称。默认值为“default”  | 
|  tokenDurationSecs  |  number  |  否  |  令牌过期时间（以秒为单位）  | 

 支持来自 [Client](https://node-postgres.com/apis/client)/[Pool](https://node-postgres.com/apis/pool) 的所有其他参数。

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

 该连接器通过使用 DSQL 客户端令牌生成器生成令牌来自动处理 DSQL 身份验证。如果未提供 AWS 区域，系统会自动从提供的主机名中解析该区域。

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

### 管理员用户与普通用户
<a name="admin-vs-regular-users"></a>
+  名为“admin”的用户会自动使用管理员身份验证令牌 
+  所有其他用户都使用普通身份验证令牌 
+  令牌将为每个连接动态生成