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.

What is Aurora DSQL Authentication?

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.

Features

• 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

Requirements

• 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)

Installation

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

Peer Dependencies

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

Usage

Client Connection

// src/index.ts
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();

Pool Connection

// src/index.ts
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";

const pool = new AuroraDSQLPool({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
  max: 3,
  idleTimeoutMillis: 60000,
});

const result = await pool.query("SELECT NOW()");

Advanced Usage

// 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.

Admin vs Regular Users

• 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
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

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