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.

$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 Postgres.js 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 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

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.

$3

``bash
npm install @aws/aurora-dsql-postgresjs-connector


Postgres.js is a peer-dependency, so users must install it themselves


npm install postgres
`

$3

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

// Clean up
await sql.end();
`

#### Using cluster ID instead of host

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

});
`

$3

`typescript
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);

const result = await sqlSELECT current_timestamp;
`

$3

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

$3

| Option | Type | Required | Description |
|-----------------------------|----------------------------------|----------|----------------------------------------------------------|
| host | string | Yes | DSQL cluster hostname or cluster ID |
| database | string? | No | Database name |
| username | string? | No | Database username (uses admin if not provided) |
| region | string? | No | AWS region (auto-detected from hostname if not provided) |
| customCredentialsProvider | AwsCredentialIdentityProvider? | No | Custom AWS credentials provider |
| tokenDurationSecs | number? | No | Token expiration time in seconds |

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.

$3

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

$3

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

$3

`typescript
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 => {
// 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 sqlSELECT version();
console.log(result);
await sql.end();
`

$3

| Option | Type | Required | Description |
|-----------------------------|----------------------------------|----------|----------------------------------------------------------|
| host | string | Yes | DSQL cluster hostname or cluster ID |
| database | string? | No | Database name |
| username | string? | No | Database username (uses admin if not provided) |
| region | string? | No | AWS region (auto-detected from hostname if not provided) |
| customCredentialsProvider | AwsCredentialIdentityProvider? | No | Custom AWS credentials provider |
| tokenDurationSecs | number? | No | Token expiration time in seconds |
| connectionCheck | boolean? | No | Perform a heart beat connectivity check withSelect 1 before every query (Default: false)
| connectionId | string? | No | An optional connection identifier to be used in the onReservedConnectionClose callback
| onReservedConnectionClose | (connectionId?: string) => void? | No | A callback that is executed upon unexpected closure of a reserved connection, such as a heartbeat failure. The connectionId is passed to the callback when available.

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.

$3

- 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

`bash


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