docs: update docs for IAM authentication and rename driver (#319)

karenc-bq · web-flow · commit 0ab384b4ef87 · 2024-11-19T16:49:12.000Z
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Amazon Web Services (AWS) Advanced NodeJS Wrapper
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![NPM Version](https://badge.fury.io/js/aws-advanced-nodejs-wrapper.svg)](https://badge.fury.io/js/aws-advanced-nodejs-wrapper)
 
 The wrapper is complementary to an existing NodeJS driver and aims to extend the functionality of the driver to enable applications to take full advantage of the features of clustered databases such as Amazon Aurora. In other words, the AWS Advanced NodeJS Wrapper does not connect directly to any database, but enables support of AWS and Aurora functionalities on top of an underlying NodeJS driver of the user's choice.
 
diff --git a/common/lib/utils/locales/en.json b/common/lib/utils/locales/en.json
@@ -4,7 +4,7 @@
   "PluginManager.unableToRetrievePlugin": "Unable to retrieve plugin instance.",
   "ConnectionProvider.unsupportedHostSelectorStrategy": "Unsupported host selection strategy '%s' specified for this connection provider '%s'. Please visit the documentation for all supported strategies.",
   "ConnectionPluginChainBuilder.errorImportingPlugin": "The plugin could not be imported due to error '%s'. Please ensure the required dependencies have been installed. Plugin: '%s'",
-  "ClientUtils.queryTaskTimeout": "AwsWrapperError: Client query task timed out.",
+  "ClientUtils.queryTaskTimeout": "Client query task timed out, if a network error did not occur, please review the usage of the 'mysqlQueryTimeout' connection parameter.",
   "DialectManager.unknownDialectCode": "Unknown dialect code: '%s'.",
   "DialectManager.getDialectError": "Was not able to get a database dialect.",
   "DefaultPlugin.executingMethod": "Executing method: %s",
diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md
@@ -10,13 +10,13 @@ Before using the AWS Advanced NodeJS Wrapper, you must install:
   - To use the wrapper with Aurora with PostgreSQL compatibility, install the [PostgreSQL Client](https://github.com/brianc/node-postgres).
   - To use the wrapper with Aurora with MySQL compatibility, install the [MySQL2 Client](https://github.com/sidorares/node-mysql2).
 
-If you are using the AWS NodeJS Wrapper as part of a Node project, include the wrapper and underlying driver as dependencies.
+If you are using the AWS Advanced NodeJS Wrapper as part of a Node project, include the wrapper and underlying driver as dependencies.
 
-> **Note:** Depending on which features of the AWS NodeJS Wrapper you use, you may have additional package requirements. Please refer to this [table](https://github.com/awslabs/aws-advanced-nodejs-wrapper/blob/main/docs/using-the-nodejs-wrapper/UsingTheNodejsWrapper.md#list-of-available-plugins) for more information.
+> **Note:** Depending on which features of the AWS Advanced NodeJS Wrapper you use, you may have additional package requirements. Please refer to this [table](https://github.com/awslabs/aws-advanced-nodejs-wrapper/blob/main/docs/using-the-nodejs-wrapper/UsingTheNodejsWrapper.md#list-of-available-plugins) for more information.
 
-## Obtaining the AWS NodeJS Wrapper
+## Obtaining the AWS Advanced NodeJS Wrapper
 
-You can use [npm](https://www.npmjs.com/) to obtain the AWS NodeJS Wrapper by adding the following configuration to the application's `package.json` file:
+You can use [npm](https://www.npmjs.com/) to obtain the AWS Advanced NodeJS Wrapper by adding the following configuration to the application's `package.json` file:
 
 ```json
 {
@@ -26,6 +26,6 @@ You can use [npm](https://www.npmjs.com/) to obtain the AWS NodeJS Wrapper by ad
 }
 ```
 
-## Using the AWS NodeJS Wrapper
+## Using the AWS Advanced NodeJS Wrapper
 
-For more detailed information about how to use and configure the AWS NodeJS Wrapper, please visit [this page](./using-the-nodejs-wrapper/UsingTheNodejsWrapper.md).
+For more detailed information about how to use and configure the AWS Advanced NodeJS Wrapper, please visit [this page](./using-the-nodejs-wrapper/UsingTheNodejsWrapper.md).
diff --git a/docs/development-guide/DevelopmentGuide.md b/docs/development-guide/DevelopmentGuide.md
@@ -31,11 +31,11 @@ npm install
 
 ## Testing Overview
 
-The AWS NodeJS Wrapper uses the following tests to verify its correctness and performance:
+The AWS Advanced NodeJS Wrapper uses the following tests to verify its correctness and performance:
 
 | Tests                                         | Description                                                                                                           |
 | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Unit tests                                    | Tests for AWS NodeJS Wrapper correctness.                                                                             |
+| 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.              |
@@ -44,14 +44,14 @@ The AWS NodeJS Wrapper uses the following tests to verify its correctness and pe
 
 ### Performance Tests
 
-The AWS NodeJS Wrapper has 2 types of performance tests:
+The AWS Advanced NodeJS Wrapper has 2 types of performance tests:
 
 1. manually-triggered performance tests measuring the failover and enhanced failure monitoring plugins' performance under different configurations.
-2. benchmarks measuring the AWS NodeJS Wrapper's overhead when executing simple methods using the [benny benchmarking framework](https://www.npmjs.com/package/benny).
+2. benchmarks measuring the AWS Advanced NodeJS Wrapper's overhead when executing simple methods using the [benny benchmarking framework](https://www.npmjs.com/package/benny).
 
-#### AWS NodeJS Wrapper Benchmarks
+#### AWS Advanced NodeJS Wrapper Benchmarks
 
-There are specific benchmarks measuring the AWS NodeJS Wrapper's [pipelines](Pipelines.md). The goal of these benchmarks is to measure the overhead of using the AWS 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](../using-the-nodejs-wrapper/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md), [failover](../using-the-nodejs-wrapper/using-plugins/UsingTheFailoverPlugin.md), and [host monitoring](../using-the-nodejs-wrapper/using-plugins/UsingTheHostMonitoringPlugin.md). The images below represent the benchmarks for the `connect`, `execute` and `releaseResources` pipelines.
+There are specific benchmarks measuring the AWS Advanced NodeJS Wrapper's [pipelines](Pipelines.md). 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](../using-the-nodejs-wrapper/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md), [failover](../using-the-nodejs-wrapper/using-plugins/UsingTheFailoverPlugin.md), and [host monitoring](../using-the-nodejs-wrapper/using-plugins/UsingTheHostMonitoringPlugin.md). The images below represent the benchmarks for the `connect`, `execute` and `releaseResources` pipelines.
 
 ##### [Connect Pipeline](Pipelines.md#connect-pipeline)
 
@@ -69,17 +69,17 @@ See [here](PluginPipelinePerformanceResults.md#benchmarks) for a more detailed p
 
 #### Failover-specific Performance Tests
 
-The diagrams in this section show the AWS NodeJS Wrapper's failure detection performance with or without the Failover Connection Plugin under different settings.
+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:
 
-1. The AWS NodeJS Wrapper executes an SQL query with a long execution time.
+1. The AWS Advanced NodeJS Wrapper executes an SQL query with a long execution time.
 2. 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.
 3. Measures elapsed time between when the network outage and
-   - when the AWS NodeJS Wrapper detects the network failure if the Host Monitoring Plugin is used, or
-   - when the AWS NodeJS Wrapper finishes the failover process if the Failover Plugin is used.
+   - 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 NodeJS Wrapper performs under a more common failure detection setting versus a more aggressive setting.
+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
 
@@ -122,7 +122,7 @@ See [here](PluginPipelinePerformanceResults.md#enhanced-failure-monitoring-perfo
 
 #### Read-Write Splitting and Internal Connection Pooling Performance Tests
 
-The diagram in this section shows the AWS 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 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.
 
@@ -133,7 +133,7 @@ See [here]() for a more detailed performance breakdown.
 
 ### Running the Tests
 
-After building the AWS NodeJS Wrapper you can now run the unit tests.
+After building the AWS Advanced NodeJS Wrapper you can now run the unit tests.
 This will also validate your environment is set up correctly.
 
 ```bash
diff --git a/docs/using-the-nodejs-wrapper/UsingTheNodejsWrapper.md b/docs/using-the-nodejs-wrapper/UsingTheNodejsWrapper.md
@@ -52,6 +52,15 @@ These parameters are applicable to any instance of the AWS Advanced NodeJS Wrapp
 | `clusterInstanceHostPattern`   | `string`  | If connecting using an IP address or custom domain URL: Yes<br><br>Otherwise: No | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster. See [here](#host-pattern) for more information. <br/><br/>Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com`<br/><br/>Use case Example: If your cluster instance endpoints follow this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your client configuration should look like this: `{ host: "customHost", port: 1234, database: "test", clusterInstanceHostPattern: "?.customHost" }` | If the provided host is not an IP address or custom domain, the NodeJS Wrapper will automatically acquire the cluster instance host pattern from the customer-provided host. |
 | `mysqlQueryTimeout`            | `number`  | No                                                                               | Query timeout in milliseconds. This is only applicable when using the AwsMySQLClient. To set query timeout for the AwsPGClient, please use the built-in `query_timeout` parameter. See the `node-postgres` [documentation](https://node-postgres.com/apis/client) for more details..                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 20000                                                                                                                                                                        |
 
+## Host Pattern
+
+When connecting to Aurora clusters, the [`clusterInstanceHostPattern`](#aws-advanced-nodejs-wrapper-parameters) parameter is required if the host does not provide enough information about the database cluster domain name.
+If the Aurora cluster endpoint is used directly, the AWS Advanced NodeJS Wrapper will recognize the standard Aurora domain name and can re-build a proper Aurora instance name when needed.
+In cases where the host is an IP address, a custom domain name, or localhost, the wrapper won't know how to build a proper domain name for a database instance endpoint.
+For example, if a custom domain was being used and the cluster instance endpoints followed a pattern of `instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc., the wrapper would need to know how to construct the instance endpoints using the specified custom domain.
+Since there isn't enough information from the custom domain alone to create the instance endpoints, you should set the `clusterInstanceHostPattern` to `?.customHost`, making the client configuration `{ host: "customHost", port: 1234, database: "test", clusterInstanceHostPattern: "?.customHost" }`.
+Refer to [this diagram](../images/failover_behavior.png) about AWS Advanced NodeJS Wrapper behavior for different connection URLs and more details and examples.
+
 ## Plugins
 
 The AWS Advanced NodeJS Wrapper uses plugins to execute methods. You can think of a plugin as an extensible code module that adds extra logic around any database method calls. The AWS Advanced NodeJS Wrapper has a number of [built-in plugins](#list-of-available-plugins) available for use.
diff --git a/docs/using-the-nodejs-wrapper/using-plugins/UsingTheFailoverPlugin.md b/docs/using-the-nodejs-wrapper/using-plugins/UsingTheFailoverPlugin.md
diff --git a/docs/using-the-nodejs-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md b/docs/using-the-nodejs-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md
