cassandra-guard

library2.2.0jsnpmunverified

A schema registry, validated CQL builder, DDL generator, and migration differ for Apache Cassandra. Version 2.2.0 (stable, released 2024). Define your schema in JSON; all CQL statements are validated against it at build time, catching errors like missing columns or invalid primary key updates before deployment. Differentiators: build-time validation (not runtime), CQL builder that enforces schema correctness, and migration diffing for safe schema evolution. Requires Node.js >=18.0.0.

database devops

npm install cassandra-guard

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CASSANDRA-GUARD

cassandra-guard

databasejavascriptv2.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SchemaRegistry

✓ import { SchemaRegistry } from 'cassandra-guard'

✗ const SchemaRegistry = require('cassandra-guard').SchemaRegistry

ESM import is preferred. CJS require works but destructure to get the class.

CQLBuilder

✓ import { CQLBuilder } from 'cassandra-guard'

✗ const { CQLBuilder } = require('cassandra-guard');

CQLBuilder is exported as a named export. Ensure correct casing.

Schema

✓ import type { Schema } from 'cassandra-guard'

✗ import { Schema } from 'cassandra-guard'

Schema is a type interface, not a runtime value. Use type-only import to avoid bundling issues.

Load a schema from JSON, build a validated SELECT query, and demonstrate build-time column validation.

const { SchemaRegistry, CQLBuilder } = require('cassandra-guard'); const registry = new SchemaRegistry(); registry.loadFromFile('./schemas/ecommerce.json'); const cql = new CQLBuilder(registry); const query = cql.select('ecommerce', 'users') .columns('user_id', 'email', 'name') .where('user_id', 'some-uuid') .build(); console.log(query.cql); // → SELECT user_id, email, name FROM ecommerce.users WHERE user_id = ? console.log(query.params); // → ['some-uuid'] // This throws CQLBuildError: cql.select('ecommerce', 'users').columns('nonexistent'); // → CQLBuildError: Column "nonexistent" does not exist in ecommerce.users

Debug

Known issues

deprecatedv2.0.0: The synchronous `loadFromFile` has been deprecated; use async `loadFromFileAsync` for non-blocking I/O in Node.js 18+

fix

Replace `registry.loadFromFile('./schema.json')` with `await registry.loadFromFileAsync('./schema.json')`

affects: >=2.0.0

breakingv2.0.0: All CQL builder methods return `this` for chaining, not a new builder instance. Breaking change if you were storing intermediate objects.

fix

Update code to chain methods directly: `cql.select('ks', 't').columns('a').where('b', 'v').build()`

affects: >=2.0.0

gotchav1.x: The `.if_()` method (lightweight transactions) uses an underscore suffix to avoid reserved word conflicts in JavaScript. This is intentional and not a typo.

fix

Use `.if_()` not `.if()` in your CQL builder chains.

affects: *

Errors

Common errors & fixes

CQLBuildError: Column "email" does not exist in myapp.users

The column name is misspelled or not defined in the schema JSON.

fix

Check the 'columns' definition in your schema JSON file for the correct column name.

TypeError: (intermediate value).columns is not a function

Forgot to call `.select()` or called `cql.select()` without chaining correctly.

fix

Ensure `cql.select('keyspace', 'table')` returns a builder object. Chain `.columns()` on the result.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

cassandra-driveroptionalRequired for executing CQL against a live Cassandra cluster (CLI mode)

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Yejneshwar/cassandra-guard ↗

packagecassandra-guard ↗

homepagehttps://github.com/Yejneshwar/cassandra-guard#readme ↗