# Upgrade guide

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][mailing-list].

## 4.9

Version 4.9.0 of the driver is the first release since the driver's donation
to the Apache Software Foundation (ASF).

### Change to DRIVER_NAME in STARTUP Messages

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](https://issues.apache.org/jira/browse/CASSNODEJS-4) for additional details.

## 4.4

### New default load balancing policy

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](https://www.eecs.harvard.edu/~michaelm/postscripts/mythesis.pdf).

### Upgrade guide for DSE driver users

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`](upgrade-from-dse-driver).

---

## 4.2

### Tuple constructor with one parameter

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. 

## 4.0

The following is a list of changes made in version 4.0 of the driver that are relevant when upgrading from version 3.x.

### localDataCenter is now a required Client option

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.

### Selection of contact points is now evaluated in random order

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.

### Changes to the retry and load-balancing policies

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

### Query idempotency and retries

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.

```javascript
client.execute(query, params, { prepare: true, isIdempotent: true })
```

Additionally, you can define the default idempotence for all executions when creating the `Client` instance:

```javascript
const client = new Client({
  contactPoints,
  localDataCenter,
  queryOptions: { isIdempotent: true }
});
```

Previously, a similar behaviour was available using `IdempotenceAwareRetryPolicy`, that is now marked as deprecated.

### Removed `retryOnTimeout` property of `QueryOptions`

`retryOnTimeout`, 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.

### Changes on `OperationInfo` of the retry module 

The retry policy methods takes [`OperationInfo`][op-info] as a parameter. Some `OperationInfo` properties changes or 
were removed.

- Deprecated properties `handler`, `request` and `retryOnTimeout` were removed.
- `options` property was replaced by `executionOptions` which is an instance of `ExecutionOptions`.

### Removed `meta` property from `ResultSet`

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

### Removed `DCAwareRoundRobinPolicy` `usedHostsPerRemoteDC` constructor parameter

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

---

## 3.0

### Changes in CQL aggregates metadata

The `initCondition` property of `Aggregate`, the class that represents the metadata information of a CQL 
aggregate, changes from `Object` to `String`.

---

## 2.0

The following is a list of changes made in version 2.0 of the driver that are relevant when upgrading from version 1.x.

### API Changes

1. `uuid` and `timeuuid` values are decoded as [`Uuid`](../features/datatypes/uuids) and
[`TimeUuid`](../features/datatypes/uuids) instances.

1. `decimal` values are decoded as [`BigDecimal`](../features/datatypes/numerical) instances.

1. `varint` values are decoded as [`Integer`](../features/datatypes/numerical) instances.

1. `inet` values are decoded as `InetAddress` instances.


[mailing-list]: https://lists.apache.org/list.html?dev@cassandra.apache.org
[op-info]: https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.policies/module.retry/type.OperationInfo/