The AWS Advanced NodeJS Wrapper leverages community database clients and enables support of AWS and Aurora functionalities. Currently, the node-postgres client and Node MySQL2 clients are supported.
It is possible to use the AWS Advanced NodeJS Wrapper with plain RDS databases, but individual features may or may not be compatible. For example, failover handling and enhanced failure monitoring are not compatible with plain RDS databases and the relevant plugins must be disabled. Plugins can be enabled or disabled as seen in the Connection Plugin Manager Parameters section. Please note that some plugins have been enabled by default. Plugin compatibility can be verified in the plugins table.
To get a connection from the AWS Advanced NodeJS Wrapper, the user application can create a client object and connect. Additional parameters can be specified within the client configuration. Configuration parameters defined by the supported clients can also be set here. For example, to connect to a MySQL database, an AwsMySQLClient is required:
const client = new AwsMySQLClient({
user: "user",
password: "password",
host: "host",
database: "database"
});
await client.connect();To connect to a PostgreSQL database an AwsPgClient is required:
const client = new AwsPgClient({
user: "user",
password: "password",
host: "host",
database: "database"
});
await client.connect();To enable logging when using the AWS Advanced NodeJS Wrapper, use the LOG_LEVEL environment variable. The log level can be set to one of the following values: silent, error, warn, notice, http, timing, info, verbose, or silly.
These parameters are applicable to any instance of the AWS Advanced NodeJS Wrapper.
| Parameter | Value | Required | Description | Default Value | Version Supported |
|---|---|---|---|---|---|
host |
string |
No | Database host. | null |
latest |
database |
string |
No | Database name. | null |
latest |
user |
string |
No | Database username. | null |
latest |
password |
string |
No | Database password. | null |
latest |
transferSessionStateOnSwitch |
boolean |
No | Enables transferring the session state to a new connection. | true |
latest |
resetSessionStateOnClose |
boolean |
No | Enables resetting the session state before closing connection. | true |
latest |
enableGreenHostReplacement |
boolean |
No | Enables replacing a green node host name with the original host name when the green host DNS doesn't exist anymore after a blue/green switchover. Refer to Overview of Amazon RDS Blue/Green Deployments for more details about green and blue nodes. | false |
latest |
clusterInstanceHostPattern |
string |
If connecting using an IP address or custom domain URL: Yes 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 for more information. Example: ?.my-domain.com, any-subdomain.?.my-domain.comUse 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. | latest |
mysqlQueryTimeout |
number |
No | This parameter has been deprecated since version 1.1.0, applications should use the wrapperQueryTimeout parameter instead. 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 for more details. |
20000 | 1.0.0 |
wrapperConnectTimeout |
number |
No | Connect timeout in milliseconds. This parameter will apply the provided timeout value to the underlying driver's built-in connect timeout parameter, if there is one available. | 20000 | latest |
wrapperQueryTimeout |
number |
No | Query timeout in milliseconds. This parameter will apply the provided timeout value to the underlying driver's built-in query timeout parameter, if there is one available. The wrapper will also use this value for its own query timeout implementation. | 20000 | latest |
wrapperKeepAliveProperties |
Map<string, any> |
No | If the underlying target driver has keepAlive properties available, properties within this map will be applied to the underlying target driver's client configuration. For example, the node-postgres driver's keepAlive and keepAliveInitialDelayMillis properties can be configured by setting this property in the client configuration: { wrapperKeepAliveProperties: new Map<string, any>([["keepAlive", true], ["keepAliveInitialDelayMillis", 1234]]) }. Currently supported drivers: node-postgres |
null |
|
awsProfile |
string |
No | Allows users to specify a profile name for AWS credentials. This parameter is used by plugins that require AWS credentials, like the AWS IAM Authentication Plugin and the AWS Secrets Manager Plugin. | null |
|
connectionProvider |
object |
No | Allows users to specify a connection provider used to create connections. Provided value should be an object that implements ConnectionProvider interface. |
null |
|
customDatabaseDialect |
object |
No | Allows users to specify a custom database dialect. Provided value should be an object that implements DatabaseDialect interface. |
null |
|
customAwsCredentialProviderHandler |
object |
No | Allows users to specify a custom AWS credentials provider. This parameter is used by plugins that require AWS credentials, like the AWS IAM Authentication Plugin and the AWS Secrets Manager Plugin. For more information see AWS Credentials Provider Configuration. | null |
When connecting to Aurora clusters, the clusterInstanceHostPattern 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 about AWS Advanced NodeJS Wrapper behavior for different connection URLs and more details and examples.
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 available for use.
Plugins are loaded and managed through the Connection Plugin Manager and may be identified by a String name in the form of plugin code.
| Parameter | Value | Required | Description | Default Value |
|---|---|---|---|---|
plugins |
String |
No | Comma separated list of connection plugin codes. Example: failover,efm |
auroraConnectionTracker,failover,efm |
autoSortWrapperPluginOrder |
Boolean |
No | Allows the AWS Advanced NodeJS Wrapper to sort connection plugins to prevent plugin misconfiguration. Allows a user to provide a custom plugin order if needed. | true |
profileName |
String |
No | Driver configuration profile name. Instead of listing plugin codes with plugins, the driver profile can be set with this parameter. Example: See below. |
null |
To use a built-in plugin, specify its relevant plugin code for the plugins .
The default value for plugins is failover. These plugins are enabled by default. To read more about these plugins, see the List of Available Plugins section.
To override the default plugins, simply provide a new value for plugins.
For instance, to use the IAM Authentication Connection Plugin and the Failover Connection Plugin:
const client = new AwsMySQLClient({
user: "user",
password: "password",
host: "host",
database: "database",
plugins: "iam,failover"
});❗NOTE: The plugins will be initialized and executed in the order they have been specified.
Provide an empty string to disable all plugins:
const client = new AwsMySQLClient({
user: "user",
password: "password",
host: "host",
database: "database",
plugins: ""
});The Wrapper behaves like the target driver when no plugins are used.
The AWS Advanced NodeJS Wrapper has several built-in plugins that are available to use. Please visit the individual plugin page for more details.
| Plugin name | Plugin Code | Database Compatibility | Description | Additional Required Dependencies |
|---|---|---|---|---|
| Failover Connection Plugin | failover |
Aurora, RDS Multi-AZ DB Cluster | Enables the failover functionality supported by Amazon Aurora clusters and RDS Multi-AZ DB clusters. Prevents opening a wrong connection to an old writer instance due to stale DNS after a failover event. This plugin is enabled by default. | None |
| Host Monitoring Plugin | efm |
Aurora, RDS Multi-AZ DB Cluster | Enables enhanced host connection failure monitoring, allowing faster failure detection rates. This plugin is enabled by default. | None |
| Execution Time Connection Plugin | executeTime |
Any database | Logs the time taken to execute any client method. | None |
| IAM Authentication Connection Plugin | iam |
Aurora | Enables users to connect to their Amazon Aurora clusters using AWS Identity and Access Management (IAM). | See the IAM Authentication Connection Plugin prerequisites |
| AWS Secrets Manager Connection Plugin | secretsManager |
Any database | Enables fetching database credentials from the AWS Secrets Manager service. | See the IAM Authentication Connection Plugin prerequisites |
| Federated Authentication Plugin | federatedAuth |
Aurora | Enables users to authenticate using Federated Identity and then connect to their Amazon Aurora Cluster using AWS Identity and Access Management (IAM). | See the Federated Authentication Plugin prerequisites |
| Okta Authentication Plugin | okta |
Aurora | Enables users to authenticate using Federated Identity and then connect to their Amazon Aurora Cluster using AWS Identity and Access Management (IAM). | See the Okta Authentication Plugin prerequisites |
| Aurora Stale DNS Plugin | staleDns |
Aurora | Prevents incorrectly opening a new connection to an old writer node when DNS records have not yet updated after a recent failover event. failover plugin, auroraStaleDns plugin doesn't implement failover support itself. It helps to eliminate opening wrong connections to an old writer node after cluster failover is completed. failover plugin so you can omit using both plugins at the same time. |
None |
| Aurora Connection Tracker Plugin | auroraConnectionTracker |
Aurora, RDS Multi-AZ DB Cluster | Tracks all the opened connections. In the event of a cluster failover, the plugin will close all the impacted connections to the host. This plugin is enabled by default. | None |
| Read Write Splitting Plugin | readWriteSplitting |
Aurora | Enables read write splitting functionality where users can switch between database reader and writer instances. | None |
| Aurora Initial Connection Strategy Plugin | initialConnection |
Aurora | Allows users to configure their initial connection strategy to reader cluster endpoints. | None |
| Aurora Limitless Connection Plugin | limitless |
Aurora | Allows users to use Aurora Limitless Database and effectively load-balance load between available transaction routers. | None |
| Fastest Response Strategy Plugin | fastestResponseStrategy |
Aurora | When read-write splitting is enabled, this plugin selects the reader to switch to based on the host with the fastest response time. The plugin achieves this by periodically monitoring the hosts' response times and storing the fastest host in a cache. Note: the readerHostSelector strategy must be set to fastestResponse in the user-defined connection properties in order to enable this plugin. See reader selection strategies |
None |
In addition to the built-in plugins, you can also create custom plugins more suitable for your needs. For more information, see Custom Plugins.
An alternative way of loading plugins and providing configuration parameters is to use a configuration profile. You can create custom configuration profiles that specify which plugins the AWS Advanced NodeJS Wrapper should load. After creating the profile, set the profileName parameter to the name of the created profile.
This method of loading plugins will most often be used by those who require custom plugins that cannot be loaded with the plugins parameter, or by those who are using preset configurations.
Besides a list of plugins to load and configuration properties, configuration profiles may also include the following items:
- Database Dialect
- Driver Dialect
- a custom exception handler
- a custom connection provider
The following example creates and sets a configuration profile:
// Create a new configuration profile with name "testProfile"
ConfigurationProfileBuilder.get()
.withName("testProfile")
.withPluginsFactories([FailoverPluginFactory, HostMonitoringPluginFactory, CustomConnectionPluginFactory])
.buildAndSet();
// Use the configuration profile "testProfile"
const client = new AwsMySQLClient({
user: "user",
password: "password",
host: "host",
database: "database",
profileName: "testProfile"
});Configuration profiles can be created based on other existing configuration profiles. Profile names are case sensitive and should be unique.
// Create a new configuration profile with name "newProfile" based on "existingProfileName"
ConfigurationProfileBuilder.get()
.from("existingProfileName")
.withName("newProfileName")
.withDatabaseDialect(new CustomDatabaseDialect())
.buildAndSet();
// Delete configuration profile "testProfile"
DriverConfigurationProfiles.remove("testProfile");The AWS Advanced NodeJS Wrapper team has gathered and analyzed various user scenarios to create commonly used configuration profiles, or presets, for users. These preset configuration profiles are optimized, profiled, verified and can be used right away. Users can create their own configuration profiles based on the built-in presets as shown above. More details could be found at the Configuration Presets page.