CassandraStore

CassandraStore Reference documentation for the Apache Cassandra (CQL) store. Overview CassandraStore is the ORM's store for Apache Cassandra, queried with CQL (Cassandra Query Language). Cassandra is a wide-column, partition-key-based distributed store. Although CQL superficially resembles SQL, it deliberately omits joins, arbitrary WHERE-clause filtering, and subqueries — every query must be answerable from a single partition (or an explicitly designed secondary index / materialized view), and data is modelled query-first around partition and clustering keys. Because that model does not fit the SQL-shaped Dialect interface, CassandraStore instead implements the minimal NoSqlStore marker interface (src/nosql/store.ts) and exposes Cassandra's own CQL execution surface directly rather than pretending to be a relational dialect. Key facts: name = 'cassandra' library = 'cassandra-driver' (the DataStax Node.js driver) The cassandra-driver package is an optional peer dependency. It is lazy-loaded via require('cassandra-driver') inside connect(), so importing this module never forces the driver to be installed. An injected client (a CassandraClientLike Client) option is supported. When provided, connect() uses it directly and skips require('cassandra-driver') entirely — this is how tests inject a mock without the real driver installed. CassandraStore implements NoSqlStore: Connection Real driver Pass standard cassandra-driver Client options and call connect(). The driver is loaded lazily at that point. Additional options: clientOptions?: Record<string, unknown> — escape hatch for any other cassandra-driver Client option (pooling, SSL, policies, socketOptions, ...). Merged into the options passed to the Client constructor. If connecting fails, connect() throws a ConnectionError (with the failing error as parent, database: 'cassandra', and host set to the first contact point) and leaves the store disconnected. Injected client Provide a pre-built driver Client (or a compatible mock) via client. connect() then calls client.connect() directly and never requires the driver package: The injected client must satisfy CassandraClientLike: Constructor options type Methods Lifecycle connect(): Promise<void> Establishes the session. Idempotent: if already connected with a live client it returns immediately. Uses the injected client if present; otherwise lazy-loads cassandra-driver and constructs new cql.Client({ contactPoints, localDataCenter, keyspace, credentials, ...clientOptions }). Then awaits client.connect() and marks the store connected. On any failure it resets state and throws ConnectionError. disconnect(): Promise<void> If a client exists, calls client.shutdown() and clears the client and connected flag (in a finally, so state is reset even if shutdown throws). If no client exists, just clears the connected flag. isConnected(): boolean Returns true only when the store is connected and holds a non-null client. getClient(): CassandraClientLike Returns the underlying cassandra-driver Client for anything not wrapped here. Throws ConnectionError if called before a successful connect(). CQL execution execute<T = Record<string, unknown>>(query: string, params?: unknown[], opts?: CassandraQueryOptions): Promise<CassandraResult<T>> Executes a single CQL statement with optional bound params (defaults to [] when omitted). Statements are prepared by default — the driver is called with { prepare: true, ...opts }, so prepare: true is the effective default but any opts you pass are merged on top and can override it (e.g. prepare: false for a one-off, or fetchSize, consistency, pageState, timestamp, ...). Returns the full driver result, so .rows (and any other driver result metadata) is available on the return value. On failure, throws a DatabaseError whose message is Cassandra execute (<query>) failed: <original message>. batch(queries: CassandraBatchQuery[], opts?: CassandraQueryOptions): Promise<CassandraResult> Executes multiple statements as a single logged batch. Each entry is a { query, params } pair. Prepared by default (the driver is called with { prepare: true, ...opts }); forward or override batch options (e.g. logged: false, prepare: false) via opts. Cassandra batches are atomic across their statements but not isolated — they are not SQL transactions. On failure, throws a DatabaseError with message Cassandra batch failed: <original message>. Convenience helpers insert(table: string, obj: Record<string, unknown>, opts?: CassandraQueryOptions): Promise<CassandraResult> Builds a parameterized INSERT INTO <table> (<cols>) VALUES (?, ?, ...) from obj's keys and executes it (prepared, via execute()). Column order and parameter order follow Object.keys(obj). Throws a DatabaseError (insert() requires at least one column) if obj has no keys. For upserts with TTL, IF NOT EXISTS, or other clauses, write the CQL yourself and call execute(). For example, insert('users', { id: 1, name: 'alice', active: true }) calls the driver with: selectAll<T = Record<string, unknown>>(table: string, opts?: CassandraQueryOptions): Promise<CassandraResult<T>> Convenience SELECT FROM <table> (no params), executed via execute(). Returns the full driver result (with .rows). Example Verification status Unit / mock-verified only. The cassandra-driver package is not installed in this environment, so the test suite (tests/nosql/cassandra.test.ts) injects a mock Client (with connect / execute / batch / shutdown spies) via the store's client option. That option makes connect() skip require('cassandra-driver') entirely, so the tests exercise the real store code paths with no driver and no network. Behaviors covered by the mock-backed tests: Reports name = 'cassandra' and library = 'cassandra-driver'. Connection lifecycle: injected client.connect() is called; isConnected() reflects state; a second connect() is idempotent (no re-connect); disconnect() calls client.shutdown(). Not-connected guards: getClient() and execute() throw ConnectionError before connect(); a failing client.connect() is wrapped in ConnectionError. execute() passes prepare: true by default, defaults params to [], lets opts override prepare, returns driver rows, and wraps failures in DatabaseError. batch() forwards the query array with prepare: true by default and lets opts override. insert() builds the parameterized INSERT with matching columns/params and throws for an empty object. selectAll() builds SELECT FROM <table> and returns rows. No integration test against a live Cassandra cluster is run here. Related reading Running cassandra in Docker — get one going locally All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories