Registry / database / cassandra-migration

cassandra-migration

library3.0.0jsnpmunverified

Simple schema migration tool for Apache Cassandra, version 3.0.0. It migrates the Cassandra schema by executing CQL files with a naming convention in a specified directory. The tool requires Node.js >=0.10 and uses the cassandra-driver for connection. It supports configuration via JSON files, optional authentication, and WhiteListPolicy for single-node migration. Unlike other migration tools, it is lightweight and focuses on CQL file execution with version-based ordering. The project is looking for a new maintainer and has a low release cadence.

database

npm install cassandra-migration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CASSANDRA-MIGRATIO

cassandra-migration

databasejavascriptv3.0.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.

default

✓ import cassandraMigration from 'cassandra-migration';

✗ const cassandraMigration = require('cassandra-migration');

Version 3.0.0 ships ESM only; CommonJS require will not work.

CqlClient

✓ import { CqlClient } from 'cassandra-migration';

Named export for custom client usage.

MigrationConfig

✓ import type { MigrationConfig } from 'cassandra-migration';

This is a TypeScript type—only import as type to avoid runtime errors.

Migrates Cassandra schema using CQL files in migrationsDir. Uses cassandra-driver config and passes a JSON object.

// Configure a migration object const config = { migrationsDir: './migrations', quiet: false, cassandra: { contactPoints: ['127.0.0.1'], localDataCenter: 'datacenter1', keyspace: 'my_keyspace', protocolOptions: { port: 9042 }, socketOptions: { connectTimeout: 15000 }, }, }; import cassandraMigration from 'cassandra-migration'; cassandraMigration(config) .then(() => console.log('Migration completed successfully')) .catch((err) => console.error('Migration failed:', err)); // Ensure schema_version table exists in keyspace before running. // Create keyspace manually before migration.

Debug

Known issues

breakingVersion 3.0.0 changed to ESM-only; CommonJS require() will throw an error.

fix

Switch to import syntax or use dynamic import with await/import() in CommonJS.

affects: >=3.0.0

breakingThe `useSingleNode` option now requires `datacenterName` to be set for WhiteListPolicy. Without it, migration may fail.

fix

Add `datacenterName` to configuration when `useSingleNode: true`.

affects: >=2.0.0

deprecatedThe `quiet` config option is deprecated and will be removed in the next major version. Use the programmatic API's logger instead.

fix

Remove `quiet` from config; implement custom logging via event listeners.

affects: >=3.0.0

gotchaKeyspace must already exist before running migrations. The tool will not create it.

fix

Manually create your keyspace (e.g., via cqlsh) before applying migrations.

affects: >=1.0.0

gotchaCQL statements in migration files must be separated by exactly three hyphens (`---`). Inconsistent separators may cause parsing errors.

fix

Use `\n---\n` between statements. Avoid trailing spaces around the delimiter.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'cassandra-migration'

Package not installed or not in node_modules.

fix

Run `npm install cassandra-migration` and check package.json dependencies.

TypeError: cassandraMigration is not a function

Using CommonJS `require()` on ESM-only module.

fix

Use `import cassandraMigration from 'cassandra-migration'` or `const m = await import('cassandra-migration')`.

Error: Migration directory '/path/to/migrations' does not exist

The `migrationsDir` path in config is incorrect or directory missing.

fix

Verify the migrations directory exists and the path is absolute or relative to process.cwd().

Error: Keyspace 'my_keyspace' does not exist

The Cassandra keyspace has not been created before running migration.

fix

Connect to Cassandra and create the keyspace manually (e.g., `CREATE KEYSPACE my_keyspace WITH REPLICATION = ...`).

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

cassandra-driverrequiredRequired to connect to Cassandra and execute CQL statements

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ruettenm/node-cassandra-migration ↗

packagecassandra-migration ↗

homepagehttps://github.com/ruettenm/node-cassandra-migration#readme ↗