CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

3.0.0 - 2026-08-20

💥 Breaking Changes

• clusterId is no longer derived automatically, and applications that connect to more than one database cluster must now set it explicitly. Previously the wrapper generated a cluster id from the connection URL and, for AWS RDS clusters, converged connections made through instance endpoints, IP addresses or custom domains onto the cluster endpoint's id. That derivation, along with the suggested and primary cluster id caches, has been removed: clusterId is now taken only from the configuration parameter and defaults to 1 for every connection. An application that connects to several clusters without setting a distinct clusterId per cluster will have all of them share the same topology cache and monitor entries, which leads to incorrect topology and failover to the wrong cluster. Give every cluster its own value, and use the same value for every connection to a given cluster. See Cluster ID.
• Optional runtime dependencies are no longer installed for you. @opentelemetry/api, http-cookie-agent and tough-cookie moved from dependencies to optional peerDependencies, and the OpenTelemetry SDK packages (@opentelemetry/context-async-hooks, @opentelemetry/resources, @opentelemetry/sdk-trace-base, @opentelemetry/semantic-conventions) are no longer declared by the wrapper at all. Applications that use telemetry, or the Federated Authentication and Okta Authentication plugins, must add the packages they need to their own dependencies.
• Client constructors are typed. AwsPgClient, AwsPgPoolClient, AwsMySQLClient and AwsMySQLPoolClient now accept AwsPgClientConfig / AwsMySQLClientConfig in place of any, so TypeScript rejects unknown or misspelled connection properties at compile time. This is a compile-time change only; runtime behaviour is unchanged. Configurations that relied on the untyped parameter may need corrections.
• any has been removed from the external API. Most visibly, query() on the MySQL clients now resolves to [T, FieldPacket[]] rather than [T, any]. Code that consumed those results loosely may need type updates.

🪄 Added

• Support for Amazon Aurora Global Databases, including in-region and cross-region failover, global writer endpoint recognition and stale DNS handling.
• Global Database Failover Plugin, which adds the notion of a home region and lets failover behaviour be configured separately for the in-home and out-of-home cases.
• Global Database Read/Write Splitting Plugin, which can constrain new connections to a home region.
• Restricting Aurora Global Database access by region with the gdbAccessibleRegions parameter.
• Monitoring connection priority, which directs the topology monitor's connection to a preferred host type or region.
• Exported configuration types AwsClientConfig, AwsPgClientConfig and AwsMySQLClientConfig.

🦀 Changed

• Renamed the PostgreSQL client to AwsPgClient and its pooled connection type to AwsPgPooledConnection for consistent Pg casing across the pg module. This is a non-breaking change.
• PostgreSQL dialect queries are now schema-qualified, so they resolve correctly regardless of the session search_path.

⚠️ Deprecated

• AwsPGClient and AwsPGPooledConnection are now deprecated. They remain exported as backwards-compatible aliases of AwsPgClient and AwsPgPooledConnection and behave identically, so existing code continues to work without modification. Update imports to the new names; the deprecated aliases are scheduled for removal in the next major release.

🐛 Fixed

• IAM, Federated Authentication and Okta authentication now work against Aurora MySQL. Aurora asks a token-authenticated user for the mysql_clear_password authentication plugin, which the underlying driver refuses unless enableCleartextPlugin is set; the wrapper now enables it when a token-based authentication plugin is in use and the connection is encrypted. See MySQL requires an encrypted connection.
• Failover is now triggered by read-only connection errors when using strict-writer failover mode.

2.1.1 - 2026-05-28

🪄 Added

• Added Aurora Initial Connection Strategy Plugin as one of default plugins enabled. To learn more about the plugin, see the documentation here.

🐛 Fixed

• Prevent process crash during Aurora failover when using the PostgreSQL client, addresses issue #620 (PR #621).

2.1.0 - 2026-01-15

🪄 Added

• New connection properties for users to load custom Secrets using the AWS Secrets Manager Authentication Plugin.

🐛 Fixed

• Aurora Initial Connection Strategy Plugin incorrectly erroring out during initial connections when using instance endpoints (PR #601).
• Event listeners not properly removed resulting in unnecessary warning, addresses issue #598.
• Runtime dependency configuration causing import errors in certain environments (PR #592).

2.0.1 - 2025-10-17

🐛 Fixed

• Limitless Connection Plugin to properly round the load metric values for Limitless transaction routers (PR #557).

🦀 Changed

• Update documentation for Blue/Green Support (PR #564).
• Add qualifiers to PostgreSQL SQL statements (PR #574).

2.0.0 - 2025-09-11

🪄 Added

• Connection Pool.
• Exported additional API compatible with the community drivers.

1.3.0 - 2025-07-28

🪄 Added

• Blue/Green deployment support.
• More extensive integration tests for existing plugins.

🦀 Changed

• Improve the force connect pipeline (PR #480).

🐛 Fixed

• Incorrect caching in the plugin chain, reducing performance overhead (PR #464).
• Incorrect transaction level tracked in session states (PR #504).

1.2.0 - 2025-03-12

🪄 Added

• Enhanced Failover Monitoring 2 Plugin. See Using The Host Monitoring Plugin.
• Custom Endpoint Plugin. See Using the Custom Endpoint Plugin.
• Failover 2 Plugin. See Using the Failover 2 Plugin.
• Documentation on session state, driver dialects, fastest response strategy, and maintenance.

🦀 Changed

• More robust MySQL catalog usage detection (PR #366).
• Changed connection tracker to update after reader failover to new connection (PR #356).
• Improved documentation instructions for integration tests and running code samples (PR #370 & PR #374).

🐛 Fixed

• Usage of setQueryTimeout for MySQL2DriverDialect (PR #393).
• Retrieving keep alive settings (PR #395).
• Reader failover to wait for complete batch (PR #390).
• EFM2 abort and stop monitoring on dead connection (PR #415).
• Check if first connection after failover is stale (PR #416).

1.1.0 - 2024-12-12

🪄 Added

• Configuration Profiles provide an alternative way of loading plugins and providing configuration parameters (PR #338).
• New network related configuration parameters:
  • setKeepAlive method (PR #339)
  • set connect and query timeouts (PR #342)
• Fastest Response Strategy Plugin selects reader based on fastest response time (PR #345).
• Simple connection tutorial using Prisma ORM. See Using The NodeJS Wrapper with Prisma ORM.
• Added configuration parameter connectionProvider (PR #330).
  • This replaces the setConnectionProvider method. For an example, see: Using Internal Connection Pooling.

🦀 Changed

• Deprecated configuration parameter mysqlQueryTimeout.
• Updated documentation on host patterns, custom endpoints, and prerequisites for the Okta and ADFS Plugins (PR #319 & PR #327).
• Migrated to AWS JS SDK v3 (PR #331).
• Optimized getHostInfoByStrategy and acceptsStrategy calls for the Plugin Manager (PR #332).
• Updated AwsClient#releaseResources to be a static method called at the end of an application (PR #333 & PR #347).
• Updated Session State logging to display false values (PR #337).

1.0.0 - 2024-11-19

The Amazon Web Services (AWS) Advanced NodeJS Wrapper allows an application to take advantage of the features of clustered Aurora databases.