Running Cassandra in Docker with prorm

prorm reaches Cassandra through CassandraStore, a wide-column implementation
of the NoSqlStore interface. Queries are CQL, which looks like SQL but is
deliberately much more restricted.

Start the container

$ docker run -d --name orm-cassandra \
  -p 9042:9042 \
  -e CASSANDRA_CLUSTER_NAME=orm_test \
  cassandra:5

Cassandra is slow to start — a JVM plus gossip bootstrap, typically 40-90
seconds. Budget for it in CI.

With Compose

A standalone file, with the heap capped for small machines:

$ docker compose up -d --wait   # returns once the healthcheck passes
$ docker compose down -v        # tear down, volumes included

Waiting for readiness

$ until docker exec orm-cassandra cqlsh -e 'DESCRIBE KEYSPACES' >/dev/null 2>&1; do sleep 2; done

docker ps showing "healthy" is not sufficient — CQL accepts connections after
the port opens.

Create a keyspace

There is no environment variable for this; create it before connecting:

$ docker exec orm-cassandra cqlsh -e "
$   CREATE KEYSPACE IF NOT EXISTS app
$   WITH replication = {'class':'SimpleStrategy','replication_factor':1};"

SimpleStrategy with RF 1 is for local development only. Production uses
NetworkTopologyStrategy with a replication factor per data centre.

Dependencies

$ npm install ts-prorm-orm cassandra-driver

Connect and use the store

import { CassandraStore } from 'ts-prorm-orm/nosql/cassandra';

const store = new CassandraStore({
  contactPoints: ['127.0.0.1'],
  localDataCenter: 'datacenter1',   // required by the default load-balancing policy
  keyspace: 'app',
  credentials: { username: 'cassandra', password: 'cassandra' },
});

await store.connect();

try {
  await store.execute(`
    CREATE TABLE IF NOT EXISTS users (
      id uuid PRIMARY KEY,
      name text,
      age int
    )`);

  await store.execute(
    'INSERT INTO users (id, name, age) VALUES (?, ?, ?)',
    [crypto.randomUUID(), 'Ada', 30],
  );

  const rows = await store.execute('SELECT * FROM users');
  console.log(rows.length);
} finally {
  await store.disconnect();
}

DataStax Astra DB uses a secure connect bundle and an application token:

import { CassandraStore } from 'ts-prorm-orm/nosql/cassandra';

const store = new CassandraStore({
  keyspace: 'app',
  credentials: { username: 'token', password: process.env.ASTRA_DB_APPLICATION_TOKEN! },
  clientOptions: { cloud: { secureConnectBundle: './secure-connect-app.zip' } },
});
await store.connect();

For Amazon Keyspaces, see KeyspacesStore.

localDataCenter is not optional — the default load-balancing policy refuses
to start without it, and the single-node image names its DC datacenter1.

What CQL will not do

Cassandra's restrictions are design, not omissions:

No joins, no subqueries. Denormalise instead.

WHERE only on the partition key and clustering columns, unless you add
a secondary index or append ALLOW FILTERING — which scans the cluster and
should not reach production.

No ORDER BY on arbitrary columns — only clustering columns, in their
defined order.

Design the table around the query you need, not the entity you have.

[!WARNING] Known limitations
The container needs 1 GB or more of memory; cap the heap (MAX_HEAP_SIZE) on small CI runners or it is OOM-killed.
Reads should name the partition key: use the compiled findAll / selectPage, which refuses scans at build time, rather than hand-written SELECT *.
Schema changes (CREATE TABLE) propagate asynchronously across a real cluster; wait for schema agreement before writing.

Tear down

$ docker rm -f orm-cassandra

Troubleshooting

Symptom	Cause
`NoHostAvailableError` right after start	Still bootstrapping. Poll `cqlsh`, not the port.
`localDataCenter could not be determined`	Set it explicitly; the image uses `datacenter1`.
`Keyspace 'app' does not exist`	The image creates none — run the `CREATE KEYSPACE` above.
Container killed on start	Cassandra wants ~2 GB; raise the Docker memory limit.
`ALLOW FILTERING` demanded	The `WHERE` is not on the partition key — remodel the table.

Cassandra store

NoSQL stores overview

Running Cassandra in Docker with prorm

Start the container#

With Compose#

Waiting for readiness#

Create a keyspace#

Dependencies#

Connect and use the store#

What CQL will not do#

Tear down#

Troubleshooting#

Related reading#