Postgres.js 的 Aurora DSQL 连接器

Postgres.js的Aurora DSQL连接器是一个以 .js 连接器为主的节点连接器 邮编.js 将 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 集群
• 设置适当的 IAM 权限允许您的应用程序连接到 Aurora DSQL.
• 配置 AWS 证书(通过 AWS CLI、环境变量或 IAM 角色)

重要吗

• 运行此代码可能导致向您的 AWS 账户收费 .
• 我们建议你给予你的代码最少的特权 最多只给予 执行任务所需的最小权限。 更多信息见 给予最少的特权。 。 。 .
• 这个代码并不是在每个AWS区域进行测试. 更多信息见 AWS 区域服务。 。 。 .

安装

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

// Clean up
await sql.end();

使用分组ID而不是主机

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

连接字符串

const sql = AuroraDSQLPostgres(
  'postgres://[email protected]'
);

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

OCC 重试

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

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

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

按名选入/退出:

// 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呼叫,消息发布,外部计数器)在交易机构内部.

配置选项

所有标准 Postgres.js 选项 也得到支持.

网页连接器

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 的认证和授权
• 使用数据库角色和IAM认证

基本用途

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();

配置选项

其他标准 Postgres.js 选项 也得到支持,但 socket, (中文(简体) ), port,以及 ssl,有默认值.

认证

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

有关Aurora DSQL认证的更多信息,请参见: 用户指南。 。 。 .

管理员对正则用户

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

样本使用情况

使用 Postgres.js 的 Aurora DSQL 连接器的 JavaScript 示例 这里。 。 。 .

发展

# 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