Aurora DSQL Connector for Postgres.js

The Aurora DSQL Connector for Postgres.js is a Node.js connector built on Postgres.js that integrates IAM Authentication for connecting JavaScript applications to Amazon Aurora DSQL clusters.

The Aurora DSQL Connector for Postgres.js is designed as an authentication plugin that extends the functionality of the Postgres.js client to enable applications to authenticate with Amazon Aurora DSQL using IAM credentials. The connector does not connect directly to the database, but provides seamless IAM authentication on top of the underlying Postgres.js driver.

About the Connector

Amazon Aurora DSQL is a distributed SQL database service that provides high availability and scalability for PostgreSQL-compatible applications. Aurora DSQL requires IAM-based authentication with time-limited tokens that existing Node.js drivers do not natively support.

The idea behind the Aurora DSQL Connector for Postgres.js is to add an authentication layer on top of the Postgres.js client that handles IAM token generation, allowing users to connect to Aurora DSQL without changing their existing Postgres.js workflows.

The Aurora DSQL Connector for Postgres.js works with most versions of Postgres.js. Users provide their own version by installing Postgres.js directly.

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 Postgres.js 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 Postgres.js - Leverages the fast PostgreSQL client for Node.js
• Seamless Integration - Works with existing Postgres.js 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 Postgres.js' built-in connection pooling
• OCC Retry - Automatic retry with exponential backoff on optimistic concurrency conflicts

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-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres

Basic Usage

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

Using cluster ID instead of host

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

Connection String

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

const result = await sql`SELECT current_timestamp`;

Advanced Configuration

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 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 can automatically retry begin() transactions on these conflicts with exponential backoff.

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

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

Per-call opt-in/out:

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

Note: The callback may be invoked multiple times on OCC conflicts. Keep it idempotent - avoid non-database side effects (HTTP calls, message publishes, external counters) inside the transaction body.

Configuration Options

All standard Postgres.js options are also supported.

Websocket Connector

The websocket connector provides an alternative connection method to Aurora DSQL using WebSockets instead of standard TCP sockets. This is designed for environments where TCP sockets are unavailable. For Node.js server applications, use the standard TCP socket connector shown above.

Use Case - Environments Without TCP Sockets

Some JavaScript runtimes don't provide TCP socket support. The WebSocket connector enables DSQL connections from these environments. If credentials remain server-controlled, the security model is similar to traditional server-side applications and credentials can be configured using your platform's secrets management (e.g., environment variables, secrets store).

Use Case - Browser Applications

Web browsers don't support TCP sockets. The WebSocket connector enables direct browser-to-database connections for use cases like internal tools, prototypes, or applications where users can safely have direct database access.

⚠️ Security Considerations for Browser Usage

When using the WebSocket connector from a browser, the database connection runs in an environment controlled by the end user. This has important security implications:

• Users can execute any query their database role permits. There is no server-side layer to validate, filter, or restrict queries. The browser's JavaScript can be inspected and modified.

• Database role permissions are your access control boundary. The IAM role grants connection ability, but the PostgreSQL database role determines what data the user can access. Configure database roles with minimal necessary permissions.

This approach is appropriate when users should have direct database access such as internal admin tools, single-user applications, or scenarios with properly scoped database roles. It is not a substitute for a backend API when you need to control what queries users can run.

For guidance on configuring IAM roles and database permissions, see:

• Authentication and authorization for Aurora DSQL
• Using database roles and IAM authentication

Basic Usage

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

Configuration Options

Other standard Postgres.js options are also supported, except for socket, port, and ssl, which have default values.

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

Sample usage

An JavaScript example using the Aurora DSQL Connector for Postgres.js is available here.

Development

# 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

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