- Ensure Node 21.0.0+ is installed
- (Optional) To run integration tests, an AWS Account is required
Clone the AWS Advanced NodeJS Wrapper repository:
git clone https://github.com/awslabs/aws-advanced-nodejs-wrapper.gitYou can now make changes in the repository.
Navigate to project root:
cd aws-advanced-nodejs-wrapperInstall required packages:
npm installThe 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. |
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.
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.
See here for a more detailed performance breakdown.
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.
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.
See here for a more detailed performance breakdown.
After building the AWS Advanced NodeJS Wrapper you can now run the unit tests. This will also validate your environment is set up correctly.
npm testFor more information on how to run the integration tests, please visit Integration Tests.
Postgres Connection Test Sample Code
MySQL Connection Test Sample Code
For more information on how the AWS Advanced NodeJS Wrapper functions and how it is structured, please visit Architecture.