ScyllaDB Node.js-RS Driver

This is a client-side driver for ScyllaDB written in Node.js and Rust. This driver is an overlay over the ScyllaDB Rust Driver, with the interface based on the DataStax Node.js Driver. Although optimized for ScyllaDB, the driver is also compatible with [Apache Cassandra®].

This driver is currently in the experimental state.

API documentation is available here.

Book is available here

Each of the driver endpoint is listed and documented int the API documentation, while more in-depth look into the driver usage can be found in the book.

Installation and build process

Install dependencies

You can install required packages with the following command:

npm install

You also need to install NAPI-RS cli:

npm install -g @napi-rs/cli

Building

For build process use this command:

npm run build

If you want to build in development mode use this command:

npm run build:debug

Testing the driver

Test dependencies

Before running any of the tests, ensure the driver is built correctly.

For the integration tests you need to do the following steps before running tests:

1. Install scylla-ccm package. You may also use ccm but not all tests are guaranteed to pass while using it.
2. Have java-8 installed and available in path /usr/lib/jvm/java-8 (scylla-ccm uses this hardcoded path)

Running the tests

You can run currently supported test with the following commands:

• Unit tests (npm run unit)
• Integration tests (npm run integration)

There are also some categories of unsupported tests. See package.json for a list of all possible commands.

Running examples

Before running examples, you need to build the driver and install packages for the examples by running:

npm install

in ./examples directory. You need also Cassandra or ScyllaDB running with at least three nodes (to ensure the replication_factor can be satisfied). By default, examples assume the entrypoint for the database is 172.17.0.2:9042 but you can change it by setting SCYLLA_URI env variable.

You can run all examples with the following command:

npm run examples

This will check if all examples finished successfully, but will hide any output generated by the examples.

Alternatively you can run just a specific example by providing the path to it:

node ./examples/basic.js

List of supported endpoints

The goal for this driver is to have the same interface as the DataStax Node.js driver. You can find the current status for the endpoint compatibility in this documentation.

File structure

File / Directory	Origin	Usage
.cargo	Generated by 'napi-rs'
.github	Generated by 'napi-rs'	CI-CD for GitHub
examples	Copied from Datastax	Example usage of the Datastax driver
lib	Copied from Datastax	Source code of the Datastax driver
npm	Generated by 'napi-rs'	Files for publishing to the NPM
src	Generated by 'napi-rs'	Source files of Rust code of our driver
test	Copied from Datastax	Tests from Datastax
.gitignore	Generated by 'napi-rs'	.gitignore modified (template for Node.js)
.npmignore	Generated by 'napi-rs'	Folders ignored when publishing to the NPM
.prettierignore	Manually created	Files to ignore when prettifying
.prettierrc	Manually created	File specifying rules for prettifying JS files
build.rs	Generated by 'napi-rs'	File needed for a build process
Cargo.toml	Generated by 'napi-rs'	Cargo file
index.d.ts	Generated by 'napi-rs' every build	Types of native JS functions (generated on build)
index.js	Generated by 'napi-rs' every build	File containing native JS functions (generated on build)
main.d.ts	Copied from Datastax and renamed	Types of the JS API
main.js	Copied from Datastax and renamed	Entry file for the JS API
package.json	Generated by 'napi-rs'	NPM package description
package-lock.json	npm install	NPM installed packages
rustfmt.toml	Generated by 'napi-rs'	Rust format file

Files in .gitignore (auto-generated)

• node_modules/
• target/
• Cargo.lock
• *.node

Not implemented functions

For functions not yet implemented:

function functionName()) {
    throw new Error(`TODO: Not implemented`);
}

And for entities that will not be implemented:

/**
 * @deprecated Not supported by the driver. Usage will throw an error.
 */
function entityName() {
  throw new ReferenceError(`entityName is not supported by our driver`);
}