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

Request deadlines¶

The Apache cassandra-driver applies readTimeout separately to each coordinator attempt. This driver does not support that behavior. Custom readTimeout values in query options, execution profiles, or socketOptions raise an error directing you to requestTimeout. The legacy socketOptions.readTimeout default of 12000 is accepted but does not set a request deadline.

Use requestTimeout for one client-side deadline for each native statement or batch execution (one page of results). It can be set on the client, execution profile, or query; the query setting has highest precedence, followed by the execution profile, then the client setting. When omitted, the Rust driver’s default request timeout applies.

Coordinator attempts, retries, and speculative executions share that budget, and deadline expiry is not passed to the retry policy for another attempt. On expiry the client stops waiting and starts no further attempts, but work already sent to the database may still complete. Each page fetch receives a fresh deadline.

This deadline is not a wall-clock upper bound for the complete client call. Post-response work performed by the native driver—such as propagating USE to existing connections, waiting for schema agreement, or refreshing metadata—is outside it. Connection setup, metadata requests, and preparation requests performed before statement execution are outside it as well. Expiry rejects with an Error whose name is ExecutionError and whose message identifies the configured client timeout. A value of 0 disables the deadline. All three requestTimeout settings require an integer from 0 through 2147483647; other values throw a TypeError.

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

• protocolOptions.port: applied to every contact point that does not carry its own ipAddress:port suffix, and defaulting to 9042

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.

The following option is new, with no cassandra-driver equivalent:

• protocolOptions.autoAwaitSchemaAgreement: determines whether the driver automatically waits for schema agreement after a DDL statement before resolving the query, retrying for up to protocolOptions.maxSchemaAgreementWaitSeconds. See the Schema Agreement section for more information. Defaults to true.

• protocolOptions.metadataRequestServersideTimeoutSecs: a ScyllaDB-only server-side timeout applied to schema and topology metadata queries, decoupling them from whatever timeout applies to ordinary requests. Has no effect against a non-ScyllaDB cluster. Defaults to 30.

• protocolOptions.metadataRequestClientsideTimeoutSecs: a client-side timeout applied to each page fetch of a metadata query, guarding against a node that stops responding without closing the connection. Defaults to protocolOptions.metadataRequestServersideTimeoutSecs + 1, or 30 if that is not set either.

Client internal members¶

In the cassandra-driver, several Client members were accessible at runtime from JavaScript even though they were marked as private (internal) in the driver’s TypeScript type definitions. Because the two APIs disagreed, any change would break at least one of them at any given moment.

The ScyllaDB Node.js RS Driver unifies both APIs by treating these members as internal. They are no longer part of the public API and may change or be removed without notice. The following Client members are now internal:

• options

• connected

• connecting

• isShuttingDown

If your application read any of these members, you should stop relying on them.

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.

Subclassing driver base classes¶

Some base classes that were constructor functions in the cassandra-driver are now ES2015 classes:

• auth.AuthProvider

• auth.Authenticator

• policies.reconnection.ReconnectionPolicy

• policies.reconnection.ConstantReconnectionPolicy

• policies.reconnection.ExponentialReconnectionPolicy

An ES2015 class cannot be called without new, so the constructor-function inheritance pattern no longer works. Extending one of these with Base.call(this) throws TypeError: Class constructor Base cannot be invoked without 'new' as soon as your subclass is instantiated:

const AuthProvider = require("@scylladb/driver").auth.AuthProvider;

// Old version: throws TypeError when `new MyAuthProvider()` is called
function MyAuthProvider() {
    AuthProvider.call(this);
}
MyAuthProvider.prototype = Object.create(AuthProvider.prototype);
MyAuthProvider.prototype.newAuthenticator = function (endpoint, name) {
    return new MyAuthenticator();
};

// New version
class MyAuthProvider extends AuthProvider {
    newAuthenticator(endpoint, name) {
        return new MyAuthenticator();
    }
}

If you cannot convert your subclass to class syntax, Reflect.construct() can instantiate the base class from a constructor function. Keep the prototype chain in place: the driver validates the provider with authProvider instanceof AuthProvider, which fails without it.

function MyAuthProvider() {
    return Reflect.construct(AuthProvider, [], MyAuthProvider);
}
MyAuthProvider.prototype = Object.create(AuthProvider.prototype);
MyAuthProvider.prototype.newAuthenticator = function (endpoint, name) {
    return new MyAuthenticator();
};

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 policy uses the provided datacenter for coordinator selection and excludes remote datacenters from query plans.

Some earlier releases silently ignored the localDc argument and allowed coordinators from all datacenters. The argument is now enforced. Datacenter names are case-sensitive; an unknown or case-mismatched localDc leaves no eligible nodes and requests fail with an empty load-balancing plan.

When localDc is omitted, null, or "", the policy has no explicit datacenter preference. This preserves the previous meaning of these values. ClientOptions.localDataCenter can supply the preference in each case. For precedence, failover, validation, and coordinator selection rules, see Load Balancing.

For token-aware requests to SimpleStrategy keyspaces, a preferred datacenter with datacenter failover disabled emits a warning for every query plan. With the default logLevel, each warning is delivered as a client 'log' event.

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¶

// CREATE TABLE my_keyspace.my_table (
//   user_id text,
//   name text,
//   created_at timestamp,
//   PRIMARY KEY ((user_id, name), created_at)
// )
//
// The partition key is (user_id, name), so the components must be provided in that order:
// the encoded user_id, then the encoded name.
const uderId = Buffer.from("123", "utf8");
const name = Buffer.from("alice", "utf8");

const token = client.metadata.newToken(
  [userId, name],
  "my_keyspace",
  "my_table",
);

// cassandra-driver
const token = client.metadata.newToken(Buffer.from("key"));
const token = client.metadata.newToken("12345"); // parse a token's own string form

// ScyllaDB Node.js RS Driver
const token = client.metadata.newToken(Buffer.from("key"), "ks", "tbl");
const token = new (require("@scylladb/driver").token.Token)(12345n); // wrap a raw value directly

const replicas = client.metadata.getReplicas("my_keyspace", "my_table", token);

for (const replica of replicas) {
  console.log(replica.host.address, "shard", replica.shard);
}

// cassandra-driver
const table = await client.metadata.getTable("ks", "tbl");
client.metadata.getTable("ks", "tbl", (err, table) => { /* ... */ });

// ScyllaDB Node.js RS Driver
const table = client.metadata.getTable("ks", "tbl");

// cassandra-driver
const ks = client.metadata.keyspaces["ks"];
const all = Object.values(client.metadata.keyspaces);

// ScyllaDB Node.js RS Driver
const ks = client.metadata.getKeyspace("ks"); // null if absent
const all = client.metadata.getKeyspaces(); // Readonly<Record<string, KeyspaceMetadata>>

// cassandra-driver
ks.strategy; // "org.apache.cassandra.locator.NetworkTopologyStrategy"
ks.strategyOptions; // { dc1: "3" }

// ScyllaDB Node.js RS Driver
ks.strategy.kind; // StrategyKind.NetworkTopologyStrategy
ks.strategy.datacenterRepfactors; // { dc1: 3 }

// cassandra-driver
table.columns.forEach((column) => console.log(column.name, column.type.code));

// ScyllaDB Node.js RS Driver
for (const [name, column] of Object.entries(table.columns)) {
  console.log(name, column.type.code, column.kind);
}

// cassandra-driver
const pkTypes = table.partitionKeys.map((column) => column.type);

// ScyllaDB Node.js RS Driver
const pkTypes = table.partitionKey.map((name) => table.columns[name].type);

const keyspace = client.metadata.getKeyspace("ks");

keyspace.getTable("tbl") === keyspace.tables["tbl"]; // true
keyspace.tables === keyspace.tables; // true

const trace = await client.metadata.getTrace(traceId, types.consistencies.all);

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) => { ... });

const warnings = [];
client.on('log', (level, target, message) => {
    if (level === 'warning') warnings.push(message);
});
try {
    await client.connect();
} catch (err) {
    // The warnings logged during connect() are already here.
    console.log(warnings);
}