The purpose of this guide is to detail the changes made by the successive versions of the DataStax Node.js Driver that are relevant to for an upgrade from prior versions.
If you have any questions or comments, you can post them on the mailing list.
Version 4.9.0 of the driver is the first release since the driver's donation to the Apache Software Foundation (ASF).
The DRIVER_NAME property in STARTUP messages has been changed from DataStax Node.js Driver for Apache Cassandra to Apache Cassandra Node.js Driver in this release to allow administrators to clearly distinguish between uses of the previous DataStax Node.js drivers and this donated driver. Any monitoring/management applications which were monitoring driver usage based on this string should be aware of this change and update accordingly. Please consult CASSNODEJS-4 for additional details.
The driver uses the new DefaultLoadBalancingPolicy implementation as default load balancing policy. The new policy attempts to fairly distribute the load based on the amount of in-flight request per hosts. The local replicas are initially shuffled and between the first two nodes in the shuffled list, the one with fewer in-flight requests is selected as coordinator.
The DSE driver and the Apache Cassandra driver have been merged into a single package. There's a dedicated guide for DSE driver users that plan to migrate to the cassandra-driver.
The Tuple constructor had an undocumented behaviour when invoked with a single parameter which was an Array, the driver used the Array instance as Tuple elements. We removed this behaviour that was used internally. Tuple.fromArray() method should be used to build a Tuple from an Array of elements.
The following is a list of changes made in version 4.0 of the driver that are relevant when upgrading from version 3.x.
When using DCAwareRoundRobinPolicy, which is used by default, a local data center must now be provided to the Client options parameter as localDataCenter. This is necessary to prevent routing requests to nodes in remote data centers.
The list of contact points provided as a Client option is now shuffled before selecting a node to connect to as part of initialization. This change was made for instances where configuration is shared between many clients. In this case, it is better to distribute initial connections to different nodes in the cluster instead of choosing the same node each time as the initial connection makes a number of queries to discover cluster topology and schema.
ExecutionOptions is introduced as a wrapper around the QueryOptions. The ExecutionOptions contains getter methods to obtain the values of each option, defaulting to the execution profile options or the ones defined in the ClientOptions. Previously, a shallow copy of the provided QueryOptions was used, resulting in unnecessary allocations and evaluations.
The LoadBalancingPolicy and RetryPolicy base classes changed method signatures to take ExecutionOptions instances as argument instead of QueryOptions.
Note that no breaking change was introduced for execution methods such as Client#execute(), Client#batch(), Client#eachRow() and Client#stream(). This change only affects custom implementations of the policies.
The configured RetryPolicy is not engaged when a query errors with a WriteTimeoutException or request error and the query was not idempotent.
In order to control the possibility of retrying when an timeout/error is encountered, you must mark the query as idempotent. You can define it at QueryOptions level when calling the execution methods.
client.execute(query, params, { prepare: true, isIdempotent: true })
Additionally, you can define the default idempotence for all executions when creating the Client instance:
const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } });
Previously, a similar behaviour was available using IdempotenceAwareRetryPolicy, that is now marked as deprecated.
retryOnTimeout property of QueryOptionsretryOnTimeout, the property that controlled whether a request should be tried when a response wasn't obtained after a period of time is no longer available.
The behaviour should be now controlled using onRequestError() method on the RetryPolicy for idempotent queries.
OperationInfo of the retry moduleThe retry policy methods takes OperationInfo as a parameter. Some OperationInfo properties changes or were removed.
handler, request and retryOnTimeout were removed.options property was replaced by executionOptions which is an instance of ExecutionOptions.meta property from ResultSetOn earlier versions of the driver, the ResultSet exposed the property meta which contained the raw result metadata. This property was removed in the latest version.
DCAwareRoundRobinPolicy usedHostsPerRemoteDC constructor parameterDCAwareRoundRobinPolicy no longer supports routing queries to hosts in remote data centers. Because of this usedHostsPerRemoteDC has been removed as a constructor parameter. This change was made because handling data center outages is better suited at a service level rather than within an application client.
The initCondition property of Aggregate, the class that represents the metadata information of a CQL aggregate, changes from Object to String.
The following is a list of changes made in version 2.0 of the driver that are relevant when upgrading from version 1.x.
uuid and timeuuid values are decoded as Uuid and TimeUuid instances.
decimal values are decoded as BigDecimal instances.
varint values are decoded as Integer instances.
inet values are decoded as InetAddress instances.