postgres-js

Aurora DSQL with Postgres.js

Overview

This code example demonstrates how to use Postgres.js with Amazon Aurora DSQL. The example shows you how to connect to an Aurora DSQL cluster and perform basic database operations.

Aurora DSQL is a distributed SQL database service that provides high availability and scalability for your PostgreSQL-compatible applications. Postgres.js is a lightweight PostgreSQL client for Node.js that allows you to interact with PostgreSQL databases using JavaScript code.

About the code example

This example uses the Aurora DSQL Node.js Connector which automatically handles IAM token generation for authentication.

The example demonstrates a flexible connection approach that works for both admin and non-admin users:

• When connecting as an admin user, the example uses the public schema and generates an admin authentication token.
• When connecting as a non-admin user, the example uses a custom myschema schema and generates a standard authentication token.

The code automatically detects the user type and adjusts its behavior accordingly.

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

Run the example

Prerequisites

• You must have an AWS account, and have your default credentials and AWS Region configured as described in the Globally configuring AWS SDKs and tools guide.
• Node.js: Ensure you have Node.js 18+ installed.

node --version

It should output something similar to v18.x or higher.

• You must have an Aurora DSQL cluster. For information about creating an Aurora DSQL cluster, see the Getting started with Aurora DSQL guide.
• If connecting as a non-admin user, ensure the user is linked to an IAM role and is granted access to the myschema schema. See the Using database roles with IAM roles guide.

Run the code

The example demonstrates the following operations:

• Opening a connection to an Aurora DSQL cluster
• Creating a table
• Inserting and querying data

The example is designed to work with both admin and non-admin users:

• When run as an admin user, it uses the public schema
• When run as a non-admin user, it uses the myschema schema

Note: running the example will use actual resources in your AWS account and may incur charges.

Set environment variables for your cluster details:

# e.g. "admin"
export CLUSTER_USER="<your user>"
  
# e.g. "foo0bar1baz2quux3quuux4.dsql.us-east-1.on.aws"
export CLUSTER_ENDPOINT="<your endpoint>"

Run the example:

npm install
npm test

The example contains comments explaining the code and the operations being performed.

Connection pooling

Postgres.js uses connection pooling by default. The maximum pool size, and maximum lifespan of connections is configurable when the client is created using the options max and max_lifetime respectively. Note that connections are created lazily only when a database call occurs, not when the client is created. See Postgres.js documentation here for more information. There are no guarantees as to which connection will be used when executing a command, except within a single transaction. This means users cannot rely on commands like SET SESSION search_path=schema to be applied correctly across multiple database interactions.

Additional resources

• Amazon Aurora DSQL Documentation
• Aurora DSQL Node.js Connector for Postgres.js
• Postgres.js Documentation

Note: The connector automatically extracts the region from the cluster endpoint and defaults to the postgres database.

---

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

SPDX-License-Identifier: MIT-0