Aurora DSQL Connector for node-postgres


The Aurora DSQL Connector for node-postgres is a Node.js connector built on node-postgres
that integrates IAM Authentication for connecting JavaScript/TypeScript applications to Amazon Aurora DSQL clusters.

The Aurora DSQL Connector is designed as an authentication plugin that extends the functionality of the
node-postgres' Client and Pool to enable applications to authenticate with Amazon Aurora DSQL using IAM credentials.

About the Connector

Amazon Aurora DSQL is a cloud-native distributed database with PostgreSQL compatibility. While it requires IAM authentication and time-bound tokens, traditional Node.js database drivers lack this built-in support.

The Aurora DSQL Connector for node-postgres bridges this gap by implementing an authentication middleware that works seamlessly with node-postgres. This approach allows developers to maintain their existing node-postgres code while gaining secure IAM-based access to Aurora DSQL clusters through automated token management.

$3

In Aurora DSQL, authentication involves:

- IAM Authentication: All connections use IAM-based authentication with time-limited tokens
- Token Generation: Authentication tokens are generated using AWS credentials and have configurable lifetimes

The Aurora DSQL Connector for node-postgres is designed to understand these requirements and automatically generate IAM authentication tokens when establishing connections.

$3

- Automatic IAM Authentication - Handles DSQL token generation and refresh
- Built on node-postgres - Leverages the popular PostgreSQL client for Node.js
- Seamless Integration - Works with existing node-postgres connection patterns
- Region Auto-Discovery - Extracts AWS region from DSQL cluster hostname
- Full TypeScript Support - Provides full type safety
- AWS Credentials Support - Supports various AWS credential providers (default, profile-based, custom)
- Connection Pooling Compatibility - Works seamlessly with built-in connection pooling

Example Application

There is an included sample application in example that shows how to use Aurora DSQL Connector for node-postgres. To run the included example please refer to the example README.

Quick start guide

$3

- Node.js 20+
- Access to an Aurora DSQL cluster
- Set up appropriate IAM permissions to allow your application to connect to Aurora DSQL.
- AWS credentials configured (via AWS CLI, environment variables, or IAM roles)

⚠️ Important

* Running this code might result in charges to your AWS account.
* We recommend that you grant your code least privilege. At most, grant only the
minimum permissions required to perform the task. For more information, see
Grant least privilege.
* This code is not tested in every AWS Region. For more information, see
AWS Regional Services.

Installation

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

Peer Dependencies

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

Usage

$3

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

$3

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

$3

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

Configuration Options

| Option | Type | Required | Description |
| --------------------------- | ------------------------------------------------------- | -------- | -------------------------------------------------------- |
| host | string | Yes | DSQL cluster hostname |
| username | string | Yes | DSQL username |
| database | string | No | Database name |
| region | string | No | AWS region (auto-detected from hostname if not provided) |
| port | number | No | Default to 5432 |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | No | Custom AWS credentials provider |
| profile | string | No | The IAM profile name. Default to "default" |
| tokenDurationSecs | number | No | Token expiration time in seconds |

All other parameters from Client / Pool are supported.

Authentication

The connector automatically handles DSQL authentication by generating tokens using the DSQL client token generator. If the AWS region is not provided, it will be automatically parsed from the hostname provided.

For more information on authentication in Aurora DSQL, see the user guide.

$3

- Users named "admin" automatically use admin authentication tokens
- All other users use regular authentication tokens
- Tokens are generated dynamically for each connection

Development

`


Install dependencies

``

License

This software is released under the Apache 2.0 license.

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0