Required dependencies

npm install cassandra-driver
npm install adm-zip
npm install long

No native build steps are required. The adm-zip dependency is used only by datastax/cloud/index.js when reading Astra secure connect bundles. long is used by encoder.js for 64-bit integer support.

Project setup

1. Copy the source/ directory into your project, e.g. as src/cassandra-driver/.
2. The library uses CommonJS (require). If your project is ESM, use dynamic import() or set "type": "commonjs" in your package.json.
3. For TypeScript projects, add path aliases in tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "cassandra-driver/*": ["./src/cassandra-driver/*"]
       }
     }
   }
   

4. The source ships its own auth/index.d.ts, mapping/index.d.ts, etc. No @types/cassandra-driver package is needed.
5. No required environment variables. Optional: set DATASTAX_INSIGHTS_ENABLED=false to disable telemetry, and configure sslOptions for TLS clusters.
6. For Astra DB, place the secure connect bundle zip on disk and reference its path in cloud.secureConnectBundle.

Public API

Client

import { Client } from 'cassandra-driver';

const client = new Client(options: ClientOptions): Client;

// Core methods
client.connect(): Promise<void>;
client.execute(query: string, params?: any[], options?: QueryOptions): Promise<ResultSet>;
client.batch(queries: Array<{query: string, params?: any[]}>, options?: QueryOptions): Promise<ResultSet>;
client.eachRow(query: string, params: any[], options: QueryOptions, rowCallback: Function, callback?: Function): void;
client.stream(query: string, params?: any[], options?: QueryOptions): stream.Readable;
client.shutdown(): Promise<void>;

The primary class for all cluster interaction. Instantiate once per application and reuse. Call connect() explicitly or let the first query trigger lazy connection. Always call shutdown() on process exit.

PlainTextAuthProvider

import { auth } from 'cassandra-driver';
const provider = new auth.PlainTextAuthProvider(username: string, password: string);

Pass as authProvider in ClientOptions. Use for Cassandra clusters with PasswordAuthenticator or any username/password-secured cluster including Astra DB (prefer credentials shorthand for Astra).

executeConcurrent

import { concurrent } from 'cassandra-driver';

concurrent.executeConcurrent(
  client: Client,
  query: string | Array<{query: string, params: any[]}>,
  parameters: any[][] | stream.Readable,
  options?: {
    concurrencyLevel?: number;       // default 100
    raiseOnFirstError?: boolean;     // default true
    collectResults?: boolean;        // default false
    maxErrors?: number;              // default 100
    executionProfile?: string;
  }
): Promise<ResultSetGroup>;

Use for bulk INSERT/UPDATE operations where you have many parameter sets and want controlled parallelism without manually managing Promises. Works with arrays or Node.js readable streams for large datasets.

Mapper

import { mapping } from 'cassandra-driver';

const mapper = new mapping.Mapper(client: Client, mappingOptions: MappingOptions);
const modelMapper = mapper.forModel('ModelName');

modelMapper.find(doc: object, docInfo?: object, executionOptions?: string | object): Promise<Result>;
modelMapper.insert(doc: object, docInfo?: object, executionOptions?: string | object): Promise<Result>;
modelMapper.update(doc: object, docInfo?: object, executionOptions?: string | object): Promise<Result>;
modelMapper.remove(doc: object, docInfo?: object, executionOptions?: string | object): Promise<Result>;

High-level object mapper that translates between plain JS objects and CQL table rows. Use when you want ActiveRecord-style data access instead of raw CQL strings.

Working examples

Scenario - Basic query execution with prepared statements

Connect to a local Cassandra cluster and run a parameterized SELECT using prepared statement caching. The driver prepares once per node and caches automatically.

const { Client } = require('./src/cassandra-driver/client');
const { auth } = require('./src/cassandra-driver/auth');

const client = new Client({
  contactPoints: ['127.0.0.1'],
  localDataCenter: 'datacenter1',
  keyspace: 'my_keyspace',
  authProvider: new auth.PlainTextAuthProvider('cassandra', 'cassandra'),
});

async function run() {
  await client.connect();

  const query = 'SELECT id, name, email FROM users WHERE id = ?';
  const result = await client.execute(query, ['user-123'], { prepare: true });

  for (const row of result.rows) {
    console.log(row.id, row.name, row.email);
  }

  await client.shutdown();
}

run().catch(console.error);

Scenario - Bulk inserts with executeConcurrent

Insert 10,000 rows from an in-memory array at a controlled concurrency level of 200, collecting any errors without stopping execution.

const { Client } = require('./src/cassandra-driver/client');
const { executeConcurrent } = require('./src/cassandra-driver/concurrent');

const client = new Client({
  contactPoints: ['127.0.0.1'],
  localDataCenter: 'datacenter1',
  keyspace: 'my_keyspace',
});

async function bulkInsert() {
  await client.connect();

  const query = 'INSERT INTO events (id, ts, payload) VALUES (?, ?, ?)';
  const parameters = Array.from({ length: 10000 }, (_, i) => [
    `id-${i}`,
    new Date(),
    `payload-${i}`,
  ]);

  const result = await executeConcurrent(client, query, parameters, {
    concurrencyLevel: 200,
    raiseOnFirstError: false,
    collectResults: false,
  });

  console.log(`Total: ${result.totalExecuted}, Errors: ${result.errors.length}`);
  await client.shutdown();
}

bulkInsert().catch(console.error);

Scenario - Astra DB connection with secure connect bundle

Connect to DataStax Astra DB using the downloaded secure connect bundle zip. The datastax/cloud module unpacks the bundle and configures SNI, TLS, and metadata service automatically.

const { Client } = require('./src/cassandra-driver/client');

const client = new Client({
  cloud: {
    secureConnectBundle: '/path/to/secure-connect-my-db.zip',
  },
  credentials: {
    username: 'token',
    password: 'AstraCS:your-token-here',
  },
  keyspace: 'my_keyspace',
});

async function astraQuery() {
  await client.connect();
  const result = await client.execute(
    'SELECT table_name FROM system_schema.tables WHERE keyspace_name = ?',
    ['my_keyspace'],
    { prepare: true }
  );
  result.rows.forEach(row => console.log(row.table_name));
  await client.shutdown();
}

astraQuery().catch(console.error);

Scenario - Object mapper for model-based access

Use the Mapper to insert and find documents without writing CQL, mapping a JS object to a products table.

const { Client } = require('./src/cassandra-driver/client');
const { Mapper } = require('./src/cassandra-driver/mapping');

const client = new Client({
  contactPoints: ['127.0.0.1'],
  localDataCenter: 'datacenter1',
  keyspace: 'my_keyspace',
});

async function mapperExample() {
  await client.connect();

  const mapper = new Mapper(client, {
    models: {
      Product: {
        tables: ['products'],
        mappings: new mapping.UnderscoreCqlToPascalCaseMapping(),
      },
    },
  });

  const productMapper = mapper.forModel('Product');

  await productMapper.insert({ id: 'abc', name: 'Widget', price: 9.99 });

  const result = await productMapper.find({ id: 'abc' });
  for await (const product of result) {
    console.log(product.name, product.price);
  }

  await client.shutdown();
}

mapperExample().catch(console.error);

File walkthrough

• client.js - Core Client class; owns the cluster state, executes queries, and manages connection lifecycle.
• client-options.js - Validates and normalizes the ClientOptions object passed to Client.
• connection.js - Single TCP/TLS socket to one Cassandra node; handles framing and stream multiplexing.
• control-connection.js - Maintains one dedicated connection for schema events and topology changes.
• encoder.js - Bidirectional serialization between JS types and CQL binary types.
• errors.js - Exports NoHostAvailableError, DriverError, ResponseError, OperationTimedOutError, and others.
• execution-options.js - Resolves final per-query options from profiles, defaults, and per-call overrides.
• execution-profile.js - Named profiles that bundle consistency, retry policy, load balancing policy, etc.
• host.js - Tracks a node's address, state (up/down), and distance.
• host-connection-pool.js - Maintains N connections per host; handles pool growth and shrinkage.
• request-handler.js - Selects a host via load balancing policy, retries on failure.
• request-execution.js - Manages a single in-flight CQL request including timeouts.
• prepare-handler.js - Coordinates prepared statement preparation across all hosts.
• readers.js - Binary frame parser for server responses.
• writers.js - Binary frame serializer for client requests.
• streams.js - ResultStream for client.stream() row-by-row streaming.
• token.js / tokenizer.js - Token ring computation for token-aware routing.
• utils.js - Shared internal helpers (arrays, buffers, async utilities).
• promise-utils.js - Bridges the callback-based internals to Promises.
• requests.js - Defines QueryRequest, ExecuteRequest, BatchRequest, etc.
• operation-state.js - Per-request timeout and cancellation state.
• stream-id-stack.js - Allocates and recycles CQL binary protocol stream IDs.
• insights-client.js - Sends driver telemetry to DataStax Insights service.
• auth/ - PlainTextAuthProvider, DsePlainTextAuthProvider, DseGssapiAuthProvider, NoAuthProvider, base AuthProvider/Authenticator classes.
• concurrent/ - executeConcurrent for bulk parallel query execution.
• datastax/ - datastax.graph (Graph traversal result types, type serializers) and datastax.search (date-range types); datastax/cloud handles Astra secure bundle initialization.
• geometry/ - Point, LineString, Polygon geospatial value types.
• mapping/ - Mapper, ModelMapper, ModelBatchMapper for ORM-style table access.
• metadata/ - Metadata class for keyspace, table, UDT, and function schema introspection.
• metrics/ - ClientMetrics interface for custom metrics instrumentation.
• policies/ - LoadBalancingPolicy, RetryPolicy, ReconnectionPolicy, AddressTranslator, and built-in implementations.
• tracker/ - RequestTracker interface for request lifecycle observability.
• types/ - ResultSet, Row, Uuid, TimeUuid, InetAddress, Duration, BigDecimal, Tuple, and CQL type constants.

Common pitfalls and fixes

• localDataCenter is required when using the default DCAwareRoundRobinPolicy; omitting it throws at connect time. Fix: always pass localDataCenter matching your cluster's DC name exactly.
• adm-zip not installed causes a runtime crash only when cloud.secureConnectBundle is used. Fix: ensure adm-zip is in dependencies, not just devDependencies.
• long version mismatch causes instanceof checks on Long values to fail silently, producing wrong types. Fix: pin a single version of long in your root package.json and dedupe with npm dedupe.
• CommonJS/ESM interop: the source uses module.exports and require. In an ESM project, use import cassandra from './src/cassandra-driver/client.js' with createRequire or set "type": "commonjs" for the source subtree via a local package.json.
• Connection not shut down on process exit leaves the Node.js event loop open indefinitely. Fix: register process.on('SIGTERM', () => client.shutdown()).
• Prepared statement on schema change: after a DROP TABLE or ALTER TABLE, cached prepared statements become invalid and the driver throws ResponseError with code 0x2500. Fix: catch this error and re-prepare, or set prepareOnAllHosts: true in ClientOptions.

Vibe-coding prompt template

I have the cassandra-driver core library (cassandra-driver@4.8.0) located in
`source/` in this project. I also have USAGE.md describing the full API,
exports, and working examples.

Please help me integrate cassandra-driver into my existing Node.js/TypeScript
project by doing the following step by step:

1. Read USAGE.md and the relevant files under source/ to understand the
   available exports (Client, auth, concurrent, mapping, types, policies, etc.).

2. Add the required npm dependencies listed in USAGE.md ## Required
   dependencies.

3. Create a `src/db/cassandra-client.ts` module that:
   - Instantiates a singleton `Client` with my cluster's contactPoints and
     localDataCenter (read from environment variables CASSANDRA_HOSTS and
     CASSANDRA_DC).
   - Exports `connect()` and `shutdown()` helpers.
   - Uses `PlainTextAuthProvider` when CASSANDRA_USER and CASSANDRA_PASS env
     vars are present.

4. Show me how to execute a prepared statement using `client.execute()` with
   the `prepare: true` option.

5. Show me how to perform a bulk insert using `executeConcurrent` from
   source/concurrent/index.js with a concurrencyLevel of 200.

6. Show me how to set up the Mapper from source/mapping/ for one of my
   existing table models.

7. Wire the `connect()` call into my application startup and `shutdown()` into
   graceful shutdown (SIGTERM/SIGINT handlers).

Use only real exports documented in USAGE.md. Do not install the public
`cassandra-driver` npm package - use the source/ directory directly.

License and credit

The source is licensed under the Apache License, Version 2.0. See source/LICENSE if present, or the Apache-2.0 license text.

Upstream package: user@example.com - maintained by the Apache Cassandra project, originally developed by DataStax. GitHub: apache/cassandra-nodejs-driver.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

ArangoDB Official JavaScript Driver for Node.js

Automation, Utilities & Developer Tools

Free