Development Guide

January 15, 2026 · View on GitHub

Prerequisites

Ensure Node 21.0.0+ is installed
(Optional) To run integration tests, an AWS Account is required

Setup

Clone the AWS Advanced NodeJS Wrapper repository:

git clone https://github.com/aws/aws-advanced-nodejs-wrapper.git

You can now make changes in the repository.

Setting Up the AWS Advanced NodeJS Wrapper

Navigate to project root:

cd aws-advanced-nodejs-wrapper

Install required packages:

npm install

Testing Overview

The AWS Advanced NodeJS Wrapper uses the following tests to verify its correctness and performance:

Tests	Description
Unit tests	Tests for AWS Advanced NodeJS Wrapper correctness.
Failover integration tests	Wrapper-specific tests for different reader and writer failover workflows using the Failover Connection Plugin.
Enhanced failure monitoring integration tests	Wrapper-specific tests for the enhanced failure monitoring functionality using the Host Monitoring Connection Plugin.
Read Write Splitting integration tests	Wrapper-specific tests for the read write splitting functionality using the Read Write Splitting Plugin.
AWS authentication integration tests	Wrapper-specific tests for AWS authentication methods with the AWS IAM Authentication Plugin.
Connection plugin manager benchmarks	The benchmarks measure the overhead from executing method calls with multiple connection plugins enabled.

Performance Tests

The AWS Advanced NodeJS Wrapper has 2 types of performance tests:

manually-triggered performance tests measuring the failover and enhanced failure monitoring plugins' performance under different configurations.
benchmarks measuring the AWS Advanced NodeJS Wrapper's overhead when executing simple methods using the benny benchmarking framework.

AWS Advanced NodeJS Wrapper Benchmarks

There are specific benchmarks measuring the AWS Advanced NodeJS Wrapper's pipelines. The goal of these benchmarks is to measure the overhead of using the AWS Advanced NodeJS Wrapper with multiple plugins enabled. These benchmarks do not make actual connections to the databases, and they test connections with different numbers of simple test plugins and with the default plugin combination which consists of the aurora connection tracker, failover, and host monitoring. The images below represent the benchmarks for the connect, execute and releaseResources pipelines.

Connect Pipeline

Execute Pipeline

Release Resources Pipeline

See here for a more detailed performance breakdown.

Failover-specific Performance Tests

The diagrams in this section show the AWS Advanced NodeJS Wrapper's failure detection performance with or without the Failover Connection Plugin under different settings. The performance tests share the following workflow:

The AWS Advanced NodeJS Wrapper executes an SQL query with a long execution time.
After a network outage delay in milliseconds, the test triggers a network outage. Varying values for the network outage delay are tested, represented on the X axis of the diagrams below.
Measures elapsed time between when the network outage and
- when the AWS Advanced NodeJS Wrapper detects the network failure if the Host Monitoring Plugin is used, or
- when the AWS Advanced NodeJS Wrapper finishes the failover process if the Failover Plugin is used.

The following diagrams show how the AWS Advanced NodeJS Wrapper performs under a more common failure detection setting versus a more aggressive setting.

Common Failure Detection Setting

Parameter	Value
`failoverTimeoutMs`	`120000`
`failureDetectionTime`	`30000`
`failureDetectionInterval`	`5000`
`failureDetectionCount`	`3`

Aggressive Failure Detection Setting

Parameter	Value
`failoverTimeoutMs`	`120000`
`failureDetectionTime`	`6000`
`failureDetectionInterval`	`1000`
`failureDetectionCount`	`1`

For more details on failure detection settings, see here. For more details on failover settings, see here.

The two images below show the average failure detection time when failover and enhanced failure monitoring is enabled.

This graph uses a 30000 millisecond FailureDetectionGraceTime and 5000 millisecond NetworkOutageDelayMillis:

This graph uses a 6000 millisecond FailureDetectionGraceTime and 1000 millisecond NetworkOutageDelayMillis: See here for more details.

The two images below show the average failure detection time when enhanced failure monitoring is enabled.

This graph uses a 30000 millisecond FailureDetectionGraceTime and 5000 millisecond NetworkOutageDelayMillis:

This graph uses a 6000 millisecond FailureDetectionGraceTime and 1000 millisecond NetworkOutageDelayMillis: See here for more details.

Read-Write Splitting and Internal Connection Pooling Performance Tests

The diagram in this section shows the AWS Advanced NodeJS Wrapper's performance when using the read-write splitting plugin, with or without connection pooling enabled. This test sets up a large number of connections in parallel; the initial connection is to the writer but will be changed to a random reader instance. The test executes a long query many times to simulate heavy queries.

The average overhead time is measured as the average time difference between running the entire test with the read-write plugin and running the entire test without any plugins. The baseline overhead time is 0 because there are no plugins in this scenario and thus there is no plugin overhead.

Note that the given overhead values represent the total overhead of running the entire test workflow rather than the overhead of executing a single method. The test executes 1 writer query and 1 read-only query from 10 connections simultaneously.