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
• OCC Retry - Automatic retry with exponential backoff on optimistic concurrency conflicts

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)

⚠️ 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

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

OCC Retry

Aurora DSQL uses optimistic concurrency control (OCC). Transactions that conflict are rejected at commit time with error codes OC000, OC001, or 40001. The connector provides a transaction() method that automatically retries on these conflicts with exponential backoff.

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

const pool = new AuroraDSQLPool({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
  retry: { maxRetries: 5 },
});

await pool.transaction(async (client) => {
  await client.query("INSERT INTO accounts(id, balance) VALUES($1, $2)", [1, 100]);
});

The retry config accepts a partial object — unset fields use defaults:

Per-call override:

await pool.transaction(callback, { maxRetries: 0 }); // no retry for this call

Configuration Options

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