docs: document clusterId as a 3.0.0 breaking change

Author: karenc-bq

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### :boom: 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](https://github.com/aws/aws-advanced-nodejs-wrapper/blob/main/docs/using-the-nodejs-wrapper/ClusterId.md).
 - 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](https://github.com/aws/aws-advanced-nodejs-wrapper/blob/main/docs/using-the-nodejs-wrapper/using-plugins/UsingTheFederatedAuthPlugin.md) and [Okta Authentication](https://github.com/aws/aws-advanced-nodejs-wrapper/blob/main/docs/using-the-nodejs-wrapper/using-plugins/UsingTheOktaAuthPlugin.md) 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.

common/lib/wrapper_property.ts

@@ -102,7 +102,7 @@ export interface AwsClientConfig {
   clusterTopologyRefreshRateMs?: number;
   /** Cluster topology high refresh rate in millis. */
   clusterTopologyHighRefreshRateMs?: number;
-  /** A unique identifier for the cluster. Connections with the same cluster id share a cluster topology cache. If unspecified, a cluster id is automatically created for AWS RDS clusters. */
+  /** A unique identifier for the cluster. Connections with the same cluster id share a cluster topology cache. If unspecified, the cluster id is '1'. Applications connecting to more than one cluster must set a distinct value for each cluster. */
   clusterId?: string;
   /** 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 cluster instance names. This pattern is required to be specified for IP address or custom domain connections to AWS RDS clusters. Otherwise, if unspecified, the pattern will be automatically created for AWS RDS clusters. */
   clusterInstanceHostPattern?: string;