# 适用于 Node.js 的 Aurora DSQL 连接器
适用于 node-postgres 的 Aurora DSQL 连接器和适用于 Postgres.js 的 Aurora DSQL 连接器均为身份验证插件，扩展了 node-postgres 和 Postgres.js 客户端的功能，使应用程序能够使用 IAM 凭证与 Aurora DSQL 进行身份验证。
# 适用于 node-postgres 的 Aurora DSQL 连接器
[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 进行身份验证。
## 关于连接器
Amazon Aurora DSQL 是一款兼容 PostgreSQL 的云原生分布式数据库。该数据库要求使用 IAM 身份验证和有时限的令牌，而传统的 Node.js 数据库驱动程序缺少此内置支持。
适用于 node-postgres 的 Aurora DSQL 连接器通过实施可与 node-postgres 无缝协作的身份验证中间件，弥补了这一不足。此方法可让开发人员保留现有的 node-postgres 代码，并通过自动化令牌管理，获得对 Aurora DSQL 集群的基于 IAM 的安全访问权限。
### 什么是 Aurora DSQL 身份验证？
在 Aurora DSQL 中，身份验证包括：
+ **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌
+ **令牌生成：**使用 AWS 凭证生成身份验证令牌，其生命周期可配置
适用于 node-postgres 的 Aurora DSQL 连接器针对这些要求而设计，在建立连接时自动生成 IAM 身份验证令牌。
### 功能
+ **自动 IAM 身份验证**：处理 DSQL 令牌的生成与刷新
+ **基于 node-postgres 构建**：借助适用于 Node.js 的常用 PostgreSQL 客户端
+ **无缝集成**：适用于现有 node-postgres 连接模式
+ **区域自动发现**：从 DSQL 集群主机名中提取 AWS 区域
+ **完整 TypeScript 支持**：提供完全类型安全性
+ **AWS 凭证支持**：支持各种 AWS 凭证提供者（默认、基于配置文件、自定义）
+ **连接池兼容性**：与内置连接池无缝协作
## 示例应用程序
[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)。
## 快速入门指南
### 要求
+ 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 角色）。
## 安装
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## 对等依赖项
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## 用法
### 客户端连接
```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "",
user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
### 池连接
```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";
const pool = new AuroraDSQLPool({
host: "",
user: "admin",
max: 3,
idleTimeoutMillis: 60000,
});
const result = await pool.query("SELECT NOW()");
```
### 高级用法
```
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();
```
## 配置选项
| 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) 的所有其他参数。
## 身份验证
该连接器通过使用 DSQL 客户端令牌生成器生成令牌来自动处理 DSQL 身份验证。如果未提供 AWS 区域，系统会自动从提供的主机名中解析该区域。
有关 Aurora DSQL 中的身份验证的更多信息，请参阅[用户指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。
### 管理员用户与普通用户
+ 名为“admin”的用户会自动使用管理员身份验证令牌
+ 所有其他用户都使用普通身份验证令牌
+ 令牌将为每个连接动态生成
# 适用于 Postgres.js 的 Aurora DSQL 连接器
[Aurora DSQL Connector for Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) 是一款基于 [Postgres.js](https://github.com/porsager/postgres) 构建的 Node.js 连接器，它集成了 IAM 身份验证功能，可用于将 JavaScript 应用程序连接到 Amazon Aurora DSQL 集群。
经设计，适用于 Postgres.js 的 Aurora DSQL 连接器可作为身份验证插件，对 Postgres.js 客户端的功能进行扩展，使应用程序能够使用 IAM 凭证与 Amazon Aurora DSQL 进行身份验证。该连接器不直接连接到数据库，而是在底层 Postgres.js 驱动程序之上，提供无缝的 IAM 身份验证。
## 关于连接器
Amazon Aurora DSQL 是一种分布式 SQL 数据库服务，面向兼容 PostgreSQL 的应用程序提供高可用性和可扩展性。Aurora DSQL 要求使用基于 IAM 的身份验证以及限时令牌，而现有 Node.js 驱动程序本身不支持这种方法。
设计适用于 Postgres.js 的 Aurora DSQL 连接器的理念是，在 Postgres.js 客户端之上添加一个身份验证层来处理 IAM 令牌生成，使得用户无需更改现有 Postgres.js 工作流即可连接到 Aurora DSQL。
适用于 Postgres.js 的 Aurora DSQL 连接器可以用于大多数版本的 Postgres.js。用户可通过直接安装 Postgres.js 来提供自己的版本。
### 什么是 Aurora DSQL 身份验证？
在 Aurora DSQL 中，身份验证包括：
+ **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌
+ **令牌生成：**使用 AWS 凭证生成身份验证令牌，其生命周期可配置
适用于 Postgres.js 的 Aurora DSQL 连接器针对这些要求而设计，在建立连接时自动生成 IAM 身份验证令牌。
### 功能
+ **自动 IAM 身份验证**：处理 DSQL 令牌的生成与刷新
+ **基于 Postgres.js 构建**：借助适用于 Node.js 的高性能 PostgreSQL 客户端
+ **无缝集成**：适用于现有 Postgres.js 连接模式
+ **区域自动发现**：从 DSQL 集群主机名中提取 AWS 区域
+ **完整 TypeScript 支持**：提供完全类型安全性
+ **AWS 凭证支持**：支持各种 AWS 凭证提供者（默认、基于配置文件、自定义）
+ **连接池兼容性**：与 Postgres.js 内置连接池无缝协作
## 快速入门指南
### 要求
+ 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 角色）。
### 安装
```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```
### 基本用法
```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';
const sql = auroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
username: 'admin',
});
// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);
// Clean up
await sql.end();
```
#### 使用集群 ID 而非主机
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### 连接字符串
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### 高级配置
```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
const sql = AuroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
database: 'postgres',
username: 'admin',
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
tokenDurationSecs: 3600, // Token expiration (seconds)
// Standard Postgres.js options
max: 20, // Connection pool size
ssl: { rejectUnauthorized: false } // SSL configuration
});
```
## 配置选项
| Option | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| host | string | 是 | DSQL 集群主机名或集群 ID |
| database | string? | 否 | 数据库名称 |
| username | string? | 否 | 数据库用户名（如果未提供，则使用 admin） |
| region | string? | 否 | AWS 区域（如果未提供，则自动从主机名中检测） |
| customCredentialsProvider | AwsCredentialIdentityProvider? | 否 | 自定义 AWS 凭证提供者 |
| tokenDurationSecs | number? | 否 | 令牌过期时间（以秒为单位） |
还支持所有标准 [Postgres.js 选项](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details)。
## 身份验证
该连接器通过使用 DSQL 客户端令牌生成器生成令牌来自动处理 DSQL 身份验证。如果未提供 AWS 区域，系统会自动从提供的主机名中解析该区域。
有关 Aurora DSQL 中的身份验证的更多信息，请参阅[用户指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。
### 管理员用户与普通用户
+ 名为“admin”的用户会自动使用管理员身份验证令牌
+ 所有其他用户都使用普通身份验证令牌
+ 令牌将为每个连接动态生成
## 示例用法
GitHub 上提供了使用适用于 Postgres.js 的 Aurora DSQL 连接器的 JavaScript 示例。有关如何运行这些示例的说明，请参阅[示例目录](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example)。
| 说明 | 示例 |
| --- | --- |
| 使用并发查询实现连接池，包括跨多个工作线程创建表、插入和读取 | [连接池示例（首选）](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js) |
| 没有连接池的 CRUD 操作（创建表、插入、选择、删除） | [没有连接池的示例](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js) |