# @aws/aurora-dsql-postgresjs-connector 中文文档

规范地址：https://npmcn.com/package/%40aws/aurora-dsql-postgresjs-connector/

版本：0\.3\.1
npm 元数据更新时间：2026-09-21T18:13:29.598Z
中文译文更新时间：2026-11-07T15:10:21.365Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws/aurora-dsql-postgresjs-connector
原文对照：https://npmcn.com/package/%40aws/aurora-dsql-postgresjs-connector/?lang=original
项目主页：https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js
源码仓库：https://github.com/awslabs/aurora-dsql-connectors

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：96.7 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：postgres ^3\.4\.7
- 首次发布：2025-10-30T00:56:16.627Z
- 最新版本发布：2026-09-21T18:13:29.227Z
- 近 30 天下载量：11396（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 7 个）

## 中文简介

AWS Aurora DSQL 与 Postgres.js 的 IAM 认证连接器

## 安装

```sh
npm install @aws/aurora-dsql-postgresjs-connector
```

也可以使用：`pnpm add @aws/aurora-dsql-postgresjs-connector`、`yarn add @aws/aurora-dsql-postgresjs-connector`、`bun add @aws/aurora-dsql-postgresjs-connector`

## README

# Postgres.js 的 Aurora DSQL 连接器

[![GitHub](https://img.shields.io/badge/github-awslabs/aurora--dsql--connectors-blue?logo=github)](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) [![License](https://img.shields.io/badge/license-Apache--2.0-brightgreen)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/LICENSE) [![NPM Version](https://img.shields.io/npm/v/@aws/aurora-dsql-postgresjs-connector)](https://www.npmjs.com/package/@aws/aurora-dsql-postgresjs-connector) [![Discord chat](https://img.shields.io/discord/1435027294837276802.svg?logo=discord)](https://discord.com/invite/nEF6ksFWru)

Postgres.js的Aurora DSQL连接器是一个以 .js 连接器为主的节点连接器 [邮编.js](https://github.com/porsager/postgres) 将 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 的认证,并带有有时间限制的标志 已有的节点.js 驱动程序不本地支持 .

Postgres.js的Aurora DSQL连接器背后的构想是在Postgres.js上方添加一个认证层 处理 IAM 令牌生成的客户端,允许用户在不改变其现有的Postgres.js工作流程的情况下连接到Aurora DSQL.

Postgres.js的Aurora DSQL连接器与大多数版本的Postgres.js合作. 用户通过安装提供自己的版本 (原始内容存档于2017-03-21). Postgres.js direct.

### 什么是奥罗拉DSQL认证?

在Aurora DSQL中,认证涉及:

-   **IAM 认证 :** 所有连接都使用基于 IAM 的有时间限制的符号认证
-   **脚本生成 :** 认证符使用 AWS 证书生成,并具有可配置的寿命

Postgres.js的Aurora DSQL连接器旨在理解这些要求,并在建立连接时自动生成IAM认证符.

### 特征

-   **自动 IAM 认证** - 处理DSQL 令牌生成和刷新
-   **建于 Postgres.js 上** - 利用快速 PostgreSQL 客户端为节点.js
-   **无缝一体化** - 采用现有的Postgres.js连接模式
-   **区域自动发现** - 从DSQL集群主机名中提取 AWS 区域
-   **完整类型脚本支持** - 提供全套安全
-   **AWS 证书支持** - 支持各种 AWS 证书提供者(默认、基于配置文件、自定义)
-   **连接集合兼容性** - 与Postgres.js的内置连接集线器无缝工作
-   **OCC 重试** - 自动重试,对乐观的货币冲突进行指数反转

## 快速启动指南

### 所需资源

-   节点.js 20+
-   [访问 Aurora DSQL 集群](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
-   设置适当的 IAM 权限允许您的应用程序连接到 Aurora DSQL.
-   配置 AWS 证书(通过 AWS CLI、环境变量或 IAM 角色)

## 重要吗

-   运行此代码可能导致向您的 AWS 账户收费 .
-   我们建议你给予你的代码最少的特权 最多只给予 执行任务所需的最小权限。 更多信息见 [给予最少的特权](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)。 。 。 .
-   这个代码并不是在每个AWS区域进行测试. 更多信息见 [AWS 区域服务](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services)。 。 。 .

### 安装

```bash
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```

### 基本用途

```typescript
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 users = await sql`SELECT * FROM users WHERE age > ${25}`;
console.log(users);

// Clean up
await sql.end();
```

#### 使用分组ID而不是主机

```typescript
const sql = auroraDSQLPostgres({
  host: 'your-cluster-id',
  region: 'us-east-1',
  username: 'admin',
    
});
```

### 连接字符串

```typescript
const sql = AuroraDSQLPostgres(
  'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);

const result = await sql`SELECT current_timestamp`;
```

### 高级配置

```typescript
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
});
```

### OCC 重试

奥罗拉DSQL使用乐观的货币控制(OCC). 拒绝冲突的交易 输入错误代码的时间 `OC000`, (中文(简体) ), `OC001`,或 `40001`。连接器可以自动重试 `begin()` 这些冲突的交易有指数回放.

```typescript
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';

// Opt-in at connection level — all begin() calls will retry on OCC conflicts
const sql = auroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  username: 'admin',
  retry: true,
});

// No per-call config needed
await sql.begin(async (tx) => {
  await tx`INSERT INTO accounts(id, balance) VALUES(${1}, ${100})`;
});
```

重试配置接受部分对象——未设置字段使用默认:

| 外地 | 默认 | 说明 |
| --- | --- | --- |
| `maxRetries` | 3个 | 初始尝试后的重试尝试次数( 0 = 无重试) |
| `baseDelayMs` | 1个 | 初始后退延迟( ms) |
| `maxDelayMs` | 100个 | 最大基数后退延迟 ms( 上方加了 jitter) |
| `jitterFactor` | 0.25 (中文(简体) ) | 慢跑作为延迟的一小部分 |

按名选入/退出:

```typescript
// Per-call opt-in (no constructor config needed)
await sql.begin(async (tx) => { ... }, { retry: true });
await sql.begin(async (tx) => { ... }, { retry: { maxRetries: 10 } });

// Per-call opt-out (overrides constructor config)
await sql.begin(async (tx) => { ... }, { retry: false });
```

**说明:** 对OCC冲突可多次引用回调. 保持其同位素 - 避免非数据库副作用(HTTP呼叫,消息发布,外部计数器)在交易机构内部.

### 配置选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `host` | `string` | 对 | DSQL 集群主机名或集群ID |
| `database` | `string?` | 没有 | 数据库名称 |
| `username` | `string?` | 没有 | 数据库用户名( 未提供时使用管理员) |
| `region` | `string?` | 没有 | AWS 区域( 如未提供, 从主机名自动检测) |
| `customCredentialsProvider` | `AwsCredentialIdentityProvider?` | 没有 | 自定义 AWS 证书提供者 |
| `tokenDurationSecs` | `number?` | 没有 | 秒计过期时间 |
| `retry` | `Partial<OCCRetryConfig> | boolean` | 没有 | OCC 重试配置(见上文) |
| `logger` | `Logger` | 没有 | 锁定 `error` 方法和可选 `debug` (例如:. `console`(中文(简体) ) |

所有标准 [Postgres.js 选项](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) 也得到支持.

## 网页连接器

Websocket连接器提供了一种使用WebSockets而不是标准TCP套接字来连接Aurora DSQL的替代连接方法. 这是针对没有TCP套接字的环境设计的。 对于Node.js服务器应用程序,使用上面显示的标准TCP套接字连接器.

### 使用大小写 - 没有 TCP Sockets 的环境

一些JavaScript运行时间不提供TCP套接字支持. WebSocket连接器从这些环境中实现了DSQL连接. 如果证书仍由服务器控制,安全模式类似于传统的服务器侧应用,并且可以使用您平台的秘密管理(例如环境变量,秘密存储)来配置证书.

### 使用大小写 - 浏览器应用程序

Web浏览器不支持TCP套接字. WebSocket连接器可以直接连接浏览器到数据库,用于内部工具,原型,或用户可以安全直接访问数据库的应用程序等案例.

#### QQ 浏览器使用的安全考虑

在使用浏览器的WebSocket连接器时,数据库连接在由最终用户控制的环境中运行. 这对安全有重要影响:

-   **用户可以执行任何查询其数据库角色许可.** 没有用于验证、过滤或限制查询的服务器侧层。 浏览器的JavaScript可以检查并修改.
    
-   **数据库角色权限是您的访问控制边界 .** IAM角色赋予连接能力,但PostgreSQL数据库角色决定了用户可以访问哪些数据. 配置数据库角色, 并配备最低限度的必要权限 .
    

当用户应该有直接的数据库访问,例如内部管理员工具、单一用户应用程序或具有适当范围数据库作用的情景时,这种做法是适当的。 当您需要控制哪些查询用户可以运行时,它不能替代后端 API .

关于IAM角色配置和数据库权限的指导意见,见:

-   [Aurora DSQL 的认证和授权](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)
-   [使用数据库角色和IAM认证](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html)

### 基本用途

```typescript
import type { AwsCredentialIdentity } from '@aws-sdk/types';
import { auroraDSQLWsPostgres, AuroraDSQLWsConfig } from '@aws/aurora-dsql-postgresjs-connector';

// For testing only, DO NOT USE in a production environment
const simulateSecureGetCredentialsAPI = (): Promise<AwsCredentialIdentity> => {
  // Users must retrieve the AwsCredentialIdentity through a secure API
  // DO NOT store the IAM accessKeyId and secretAccessKey inside the JavaScript source code
  // for more details, refer to the example in the folder "example/src/alternative/websocket"
};

const config: AuroraDSQLWsConfig<{}> = {
  host: 'your-cluster.dsql.us-east-1.on.aws',
  database: "postgres",
  user: "admin",
  customCredentialsProvider: simulateSecureGetCredentialsAPI,
};

const sql = auroraDSQLWsPostgres(config);

const result = await sql`SELECT version()`;
console.log(result);
await sql.end();
```

### 配置选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `host` | `string` | 对 | DSQL 集群主机名或集群ID |
| `database` | `string?` | 没有 | 数据库名称 |
| `username` | `string?` | 没有 | 数据库用户名( 未提供时使用管理员) |
| `region` | `string?` | 没有 | AWS 区域( 如未提供, 从主机名自动检测) |
| `customCredentialsProvider` | `AwsCredentialIdentityProvider?` | 没有 | 自定义 AWS 证书提供者 |
| `tokenDurationSecs` | `number?` | 没有 | 秒计过期时间 |
| `connectionCheck` | `boolean?` | 没有 | 执行心脏跳动连接检查`Select 1` 在每个查询之前( 默认: 假) |
| `connectionId` | `string?` | 没有 | 用于 `onReservedConnectionClose` 回调 |
| `onReservedConnectionClose` | `(connectionId?: string) => void?` | 没有 | 在保留连接意外关闭时执行的回调, 如心跳失败 。 连接ID在可用时被传递到回调. |

其他标准 [Postgres.js 选项](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) 也得到支持,但 `socket`, (中文(简体) ), `port`,以及 `ssl`,有默认值.

## 认证

连接器通过使用DSQL客户端符号生成器生成符来自动处理DSQL认证. 如果 未提供 AWS 区域,它将自动从提供的主机名解析 .

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

### 管理员对正则用户

-   用户名 `"admin"` 自动使用管理员认证符
-   所有其他用户使用常规认证符
-   每个连接都动态生成插件

## 样本使用情况

使用 Postgres.js 的 Aurora DSQL 连接器的 JavaScript 示例 [这里](https://npmcn.com/package/%40aws/aurora-dsql-postgresjs-connector/example)。 。 。 .

## 发展

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Set a cluster for use in integration tests
export CLUSTER_ENDPOINT=your-cluster.dsql.us-east-1.on.aws

# Run tests
npm run test

# Alternatively, run only unit or integration tests
npm run test:unit
npm run test:integration
```

## 许可证

本软件以Apache 2.0许可发布.

版权:Amazon.com公司或其附属公司。 所有权利保留. SPDX - License - 标识符: Apache-2.0

## 常见问题

### @aws/aurora-dsql-postgresjs-connector 是什么？

AWS Aurora DSQL 与 Postgres\.js 的 IAM 认证连接器

### 如何安装 @aws/aurora-dsql-postgresjs-connector？

在项目目录运行 npm install @aws/aurora-dsql-postgresjs-connector，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：postgres（^3\.4\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws/aurora-dsql-postgresjs-connector 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws/aurora-dsql-postgresjs-connector 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @aws/aurora-dsql-postgresjs-connector 可以商用吗？

@aws/aurora-dsql-postgresjs-connector 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/aurora-dsql-postgresjs-connector 的下载量有多少？

根据 npm 官方下载统计，@aws/aurora-dsql-postgresjs-connector 在 2026/10/08 – 2026/11/06 这 30 天内被下载 11,396 次，日均约 380 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws/aurora-dsql-postgresjs-connector 还在维护吗？

最新版本 0\.3\.1 发布于 2026/09/22（1 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。