Migration Guide¶

Shutdown behavior¶

In the Apache cassandra-driver, you can explicitly close the connection to the database using client.shutdown(). The ScyllaDB Node.js RS Driver behaves differently: it is not possible to explicitly close the connection. The connection is closed when the Client object is garbage collected.

When client.shutdown() is called in the Node.js RS Driver:

• It prevents execution of any new statements with the given client.

• It does not close the connection to the database.

• It does not deallocate connection-related structures.

• It does not stop queries that are currently in flight.

See Shutdown for more details.

Query options¶

The following options’ remain unchanged:

• autoPage

• consistency

• fetchSize

• hints

• prepare

• serialConsistency

• timestamp

The following option is no longer supported:

• graphOptions: those options configure DSx specific features, that are not supported in this driver

Client options¶

The following options remain unchanged:

• contactPoints

• keyspace

• credentials

• credentials.username

• credentials.password

• applicationName

• applicationVersion

• encoding.map

• encoding.set

• encoding.copyBuffer

• encoding.useUndefinedAsUnset

• maxPrepared

The following option implementation has changed significantly, but the meaning of the option remains unchanged:

• id: Now accepts both Uuid and string types. When a Uuid is provided, it will be passed to the database in its standard string representation.

The following options’ default values have changed:

• encoding.useBigIntAsLong: New default - true (previously - false),

• encoding.useBigIntAsVarint: New default - true (previously - false)

With the update of encoding options, we encourage usage of the builtin types. The ability to use the driver with types is kept as a legacy option, and may be removed in the future.

Unprepared statements with bind markers¶

When an unprepared statement contains bind markers (?), the driver silently prepares the statement before execution. This is especially important in batches: for each statement with a non-empty list of values, the driver sends a prepare request sequentially, and results are not cached between client.batch() calls.

Avoid using unprepared batches unless all statements take no bind markers.

Load balancing policies¶

Unless you have specific requirements about load balancing policies, we recommend using the default load balancing policy. Below you can find a detailed list of changes made to the load balancing policies compared to the cassandra-driver.

const DefaultLoadBalancingPolicy = require("@scylladb/driver").policies.loadBalancing.DefaultLoadBalancingPolicy;

// Old version
let policy = new DefaultLoadBalancingPolicy({
    localDc: "my_dc",
    filter: filterAsFunction
});

// New version
let policy = new DefaultLoadBalancingPolicy({
    preferDatacenter: "my_dc",
    // The new policy no longer accepts the filter as a function
    // You must convert it to a list of hosts that are accepted (in the `ip:port` format)
    allowList: filterAsListOfAcceptedHosts
});

defaultLoadBalancingPolicy()¶

The policy returned from defaultLoadBalancingPolicy() is changed from legacy to new DefaultLoadBalancingPolicy. When localDc option is provided, the load balancing will be set to allow connection to the provided datacenter. When localDc is not provided connections to all nodes will be allowed.

WARNING: This is a change in behavior. In the cassandra-driver, when localDc would not be provided, localDataCenter from client options would be used.

Retry policies¶

A new version of the default retry policy was introduced. We recommend using it as a replacement for the legacy default policy.

Metadata¶

Logging¶

See the Logging page for the full documentation of the new logging system. Below are the key differences from the cassandra-driver.

ScyllaDB Node.js RS Driver introduces a concept of configurable logging levels. While logging levels were already present in cassandra-driver, you could only filter according to those levels after receiving the log information. To allow for better performance, ScyllaDB Node.js RS Driver allows you to configure received log levels before the logs are emitted, at the client settings level.

const { Client, types } = require('@scylladb/driver');

const client = new Client({
    contactPoints: ['127.0.0.1'],
    logLevel: types.logLevels.trace
});

client.on('log', (level, target, message, furtherInfo) => { ... });