Using the AWS Advanced NodeJS Wrapper

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.

Using the AWS Advanced NodeJS Wrapper with plain RDS databases

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.

Getting a Connection

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();

The AwsMySQLClient and the AwsPgClient return a single connection. These clients follows the same promise-based API supported by MySQL2 and Node-Postgres. To learn more about the supported interfaces, see Using the AwsClients. Since version 2.0.0, this wrapper also supports connecting with a Connection Pool. To learn more about it, see Using the Connection Pool.

Logging

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.

AWS Advanced NodeJS Wrapper Parameters

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.com 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.	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

Host Pattern

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.

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

Connection Plugin Manager Parameters

Parameter	Value	Required	Description	Default Value
plugins	String	No	Comma separated list of connection plugin codes. Example: failover,efm	auroraConnectionTracker,failover,efm2
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"
});

:exclamation: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.

List of Available Plugins

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
Failover2 Connection Plugin	failover2	Aurora	Enables the failover functionality supported by Amazon Aurora clusters. Prevents opening a wrong connection to an old writer instance due to stale DNS after a failover event. This is the next version of the Failover Plugin.	None
Host Monitoring Plugin	efm	Aurora, RDS Multi-AZ DB Cluster	Enables enhanced host connection failure monitoring, allowing faster failure detection rates.	None
Host Monitoring 2 Plugin	efm2	Aurora, RDS Multi-AZ DB Cluster	Enables enhanced host connection failure monitoring, allowing faster failure detection rates. Split monitoring logic into two separate tasks and simlified monitoring logic to increase overall monitoring stability. 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. :warning:Note: Contrary to 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. :warning:Note: This logic is already included in 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. :warning: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
Custom Endpoint Plugin	customEndpoint	Aurora	This plugin will analyse custom endpoint information to ensure instances used in connections are part of the custom endpoint being used.	See the Custom Endpoint Plugin prerequisites

In addition to the built-in plugins, you can also create custom plugins more suitable for your needs. For more information, see Custom Plugins.

Configuration Profiles

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 error 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 AwsPGClient({
  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.