# @aws/aurora-dsql-node-postgres-connector 中文文档 规范地址：https://npmcn.com/package/%40aws/aurora-dsql-node-postgres-connector/ 版本：0\.1\.9 npm 元数据更新时间：2026-05-19T17:42:39.406Z 中文译文更新时间：2026-11-07T11:22:02.665Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aws/aurora-dsql-node-postgres-connector 原文对照：https://npmcn.com/package/%40aws/aurora-dsql-node-postgres-connector/?lang=original 项目主页：https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres 源码仓库：https://github.com/awslabs/aurora-dsql-connectors ## 关键信息（来自 npm 元数据） - 包体积（解压后）：39.4 kB，6 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：pg ^8\.16\.3，pg-connection-string ^2\.7\.0 - 首次发布：2025-10-30T01:01:06.644Z - 最新版本发布：2026-05-19T17:42:38.863Z - 近 30 天下载量：150301（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：10（近 12 个月 9 个） ## 中文简介 AWS Aurora DSQL 连接器,用于节点投放的IAM认证 ## 安装 ```sh npm install @aws/aurora-dsql-node-postgres-connector ``` 也可以使用：`pnpm add @aws/aurora-dsql-node-postgres-connector`、`yarn add @aws/aurora-dsql-node-postgres-connector`、`bun add @aws/aurora-dsql-node-postgres-connector` ## README # 奥罗拉 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/node-postgres) [![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-node-postgres-connector)](https://www.npmjs.com/package/@aws/aurora-dsql-node-postgres-connector) [![Discord chat](https://img.shields.io/discord/1435027294837276802.svg?logo=discord)](https://discord.com/invite/nEF6ksFWru) Aurora DSQL 连接器用于节点-postgres是一个以节点为主的节点.js连接器 [节点后置](https://node-postgres.com/) 用于连接 JavaScript/TypeScript 应用程序到 Amazon Aurora DSQL 集群的 IAM 认证. Aurora DSQL 连接器被设计为一个认证插件,可以扩展该插件的功能 node-postgres的客户端和Pool,使应用程序能够使用IAM证书与Amazon Aurora DSQL认证. ## 关于连接器 Amazon Aurora DSQL是一个具有PostgreSQL相容性的云族分布式数据库. 虽然它需要IAM认证和有时间限制的符号,但传统的Node.js数据库驱动程序缺乏这种内置支持. 用于节点-postgres的Aurora DSQL Connector通过实施一个与节点-postgres无缝运行的认证中间软件来弥补这一缺口. 这种方法允许开发者在通过自动令牌管理获得基于IAM的安全访问Aurora DSQL集群的同时,维持其已存在的节点后置码. ### 什么是奥罗拉DSQL认证? 在Aurora DSQL中,认证涉及: - **IAM 认证 :** 所有连接都使用基于 IAM 的有时间限制的符号认证 - **脚本生成 :** 认证符使用 AWS 证书生成,并具有可配置的寿命 用于节点-postgres的Aurora DSQL连接器旨在理解这些要求,并在建立连接时自动生成IAM认证符. ### 特征 - **自动 IAM 认证** - 处理DSQL 令牌生成和刷新 - **建在节点上** - 为Node.js利用受欢迎的PostgreSQL客户端 - **无缝一体化** - 采用现有的节点后置连接模式 - **区域自动发现** - 从DSQL集群主机名中提取 AWS 区域 - **完整类型脚本支持** - 提供全套安全 - **AWS 证书支持** - 支持各种 AWS 证书提供者(默认、基于配置文件、自定义) - **连接集合兼容性** - 与内置连接集成无缝工作 - **OCC 重试** - 自动重试,对乐观的货币冲突进行指数反转 ## 示例应用程序 包含一个样本应用 [实例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example) 显示如何使用 Aurora DSQL 连接器进行节点连接。 要运行包含的例子,请参考示例 [读取](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)。 。 。 . ## 快速启动指南 ### 所需资源 - 节点.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-node-postgres-connector ``` ## 同伴依赖关系 ```bash npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx npm install --save-dev @types/pg ``` ## 使用量 ### 客户端连接 ```typescript // src/index.ts 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(); ``` ### 集合连接 ```typescript // src/index.ts 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()"); ``` ### 高级使用 ```typescript // index.ts 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(); ``` ### OCC 重试 奥罗拉DSQL使用乐观的货币控制(OCC). 拒绝冲突的交易 输入错误代码的时间 `OC000`, (中文(简体) ), `OC001`,或 `40001`。连接器提供 `transaction()` 自动重复这些冲突的方法. ```typescript import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector"; const pool = new AuroraDSQLPool({ host: "", user: "admin", retry: { maxRetries: 5 }, }); await pool.transaction(async (client) => { await client.query("INSERT INTO accounts(id, balance) VALUES($1, $2)", [1, 100]); }); ``` 重试配置接受部分对象——未设置字段使用默认: | 外地 | 默认 | 说明 | | --- | --- | --- | | `maxRetries` | 3个 | 初始尝试后的重试尝试次数( 0 = 无重试) | | `baseDelayMs` | 1个 | 初始后退延迟( ms) | | `maxDelayMs` | 100个 | 最大基数后退延迟 ms( 上方加了 jitter) | | `jitterFactor` | 0.25 (中文(简体) ) | 慢跑作为延迟的一小部分 | 逐个调用覆盖 : ```typescript await pool.transaction(callback, { maxRetries: 0 }); // no retry for this call ``` ## 配置选项 | 选项 | 类型 | 需求 | 说明 | | --- | --- | --- | --- | | `host` | `string` | 对 | DSQL 集群主机名 | | `user` | `string` | 对 | DSQL 用户名 | | `database` | `string` | 没有 | 数据库名称 | | `region` | `string` | 没有 | AWS 区域( 如未提供, 从主机名自动检测) | | `port` | `number` | 没有 | 默认为5432 | | `customCredentialsProvider` | `AwsCredentialIdentity / AwsCredentialIdentityProvider` | 没有 | 自定义 AWS 证书提供者 | | `profile` | `string` | 没有 | IAM简介名. 默认为“ 默认 ” | | `tokenDurationSecs` | `number` | 没有 | 秒计过期时间 | | `retry` | `Partial` | 没有 | OCC 重试配置(见上文) | | `logger` | `Logger` | 没有 | 锁定 `warn` 财务报告和审定财务报表 `error` 方法(例如:. `console`(中文(简体) ) | 所有其他参数来自 [客户端](https://node-postgres.com/apis/client) 编号 : [池头](https://node-postgres.com/apis/pool) 被支持. ## 认证 连接器通过使用DSQL客户端符号生成器生成符来自动处理DSQL认证. 如果不提供AWS区域,它将从所提供的主机名中自动解析. 有关Aurora DSQL认证的更多信息,请参见: [用户指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。 。 。 . ### 管理员对正则用户 - 名为“ admin” 的用户自动使用管理员认证符 - 所有其他用户使用常规认证符 - 每个连接都动态生成插件 ## 发展 ``` # Install dependencies npm install # Build the project npm run build # Set a cluster for use in the tests export CLUSTER_ENDPOINT=your-cluster.dsql.us-east-1.on.aws # Run tests npm run test ``` ## 许可证 本软件以Apache 2.0许可发布. 版权:Amazon.com公司或其附属公司。 所有权利保留. SPDX - License - 标识符: Apache-2.0 ## 常见问题 ### @aws/aurora-dsql-node-postgres-connector 是什么？ AWS Aurora DSQL 连接器,用于节点投放的IAM认证 ### 如何安装 @aws/aurora-dsql-node-postgres-connector？ 在项目目录运行 npm install @aws/aurora-dsql-node-postgres-connector，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：pg（^8\.16\.3）、pg-connection-string（^2\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @aws/aurora-dsql-node-postgres-connector 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @aws/aurora-dsql-node-postgres-connector 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @aws/aurora-dsql-node-postgres-connector 可以商用吗？ @aws/aurora-dsql-node-postgres-connector 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @aws/aurora-dsql-node-postgres-connector 的下载量有多少？ 根据 npm 官方下载统计，@aws/aurora-dsql-node-postgres-connector 在 2026/10/08 – 2026/11/06 这 30 天内被下载 150,301 次，日均约 5,010 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aws/aurora-dsql-node-postgres-connector 还在维护吗？ 最新版本 0\.1\.9 发布于 2026/05/20（5 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。