Apache Cassandra

Connect Apache Cassandra so CloudThinker can audit keyspaces, check ring health, read rows, and make approved single-row changes

Connect Cassandra to let CloudThinker list keyspaces and tables, audit replication, TTL, and compaction settings, report node state as the driver sees it, and read rows by primary key. CloudThinker signs in with a Cassandra login role over the CQL native transport.

Allow writes is on by default here. Changes come from a fixed set of single-row and single-setting operations, not arbitrary CQL, and every one goes through your approvals. Under the default Approval mode, AI can approve a change no Rule covers, so choose Manual or turn Allow writes off before you connect a production ring. An Ask first Rule adds to that once CloudThinker turns on Rule enforcement for your workspace.

---

Prerequisites

• A self-managed Apache Cassandra cluster reachable from CloudThinker on its CQL native transport port, 9042 by default. DataStax Astra isn’t supported: it needs a secure connect bundle, and there’s no field for one.
• Authentication and authorization turned on: authenticator: PasswordAuthenticator and authorizer: CassandraAuthorizer in cassandra.yaml, applied with a rolling restart. A stock cassandra.yaml allows everyone, so CREATE ROLE ... PASSWORD and GRANT fail. See the Apache Cassandra security docs.
• A superuser login to create a role, or a role someone created for you.
• The workspace Admin role in CloudThinker to add the connection. See How access works.
• Two or three node addresses from the same datacenter. The driver finds the rest of the ring from them.
• Plan for one Cassandra connection per workspace if agents will make changes (see the Write access warning).

This connection speaks CQL only. nodetool runs over JMX on a different port, so repair status, compaction backlog, and disk usage are out of reach.

---

Setup

1. Create a login role

   Connect as a superuser and run:

   CREATE ROLE cloudthinker WITH LOGIN = true AND PASSWORD = 'your-secure-password';
   

   Don’t reuse the default cassandra superuser.

2. Grant row reads

   A role that can log in already reads system and system_schema, so inventory, schema audits, and ring health work with no grant. Add row reads on only the keyspaces the agent should see:

   GRANT SELECT ON KEYSPACE your_keyspace TO cloudthinker;
   
3. Grant change access (optional)

   Skip this for a read-only connection. Otherwise grant per keyspace:

   GRANT MODIFY ON KEYSPACE your_keyspace TO cloudthinker;  -- single-row insert, update, delete
   GRANT ALTER  ON KEYSPACE your_keyspace TO cloudthinker;  -- table TTL, gc_grace, secondary indexes
   
4. Open network access

   The driver connects to every node it discovers, not only the contact points. Allow inbound 9042 from CloudThinker’s egress IPs to every node in the local datacenter, and check that each node’s broadcast_rpc_address is reachable from CloudThinker. These docs don’t publish CloudThinker’s egress IP list: ask your CloudThinker contact, or contact us.

   There’s no address translation. Nodes on private IPs behind NAT, or behind a single load balancer, aren’t supported: the driver dials the private addresses the ring reports and fails. Set each node’s broadcast_rpc_address to an address CloudThinker can reach.

5. Add the connection in CloudThinker

   Go to More → Workspace settings → Connections, select Cassandra, fill in the fields from Connection details, and click Connect. For a read-only connection, come back to the same screen afterwards and turn off the Allow writes switch on the detail panel. It takes effect at once, with no reconnect. If you skipped step 3, Cassandra refuses every change in the meantime anyway. Turning off Allow writes also stops CloudThinker from proposing changes.

   CloudThinker connects with the driver and reads system.local.

   Success state: Cassandra shows a Connected status, and the message names the ring, for example Connected to Prod Cluster (Cassandra 4.1.5), datacenter dc1.

---

Connection details

Field	Required	Description	Default
Contact points	Yes	Up to 10 node addresses, comma-separated, hostname or IPv4 only, no port. Example: 10.0.1.10,10.0.1.11
Native transport port	Yes	The CQL port. Not the JMX port (7199) or the internode port (7000)	9042
Role name	Yes	The login role, for example cloudthinker
Password	Yes	The password set on that role
Local datacenter	No	Keeps reads in one datacenter on a multi-DC ring. Blank uses the datacenter of the node that answers	Blank
Use TLS	No	Encrypts the session, including the role password	Yes (default)
Verify the TLS certificate	No	Set to No only for a self-signed or internal-CA certificate. Shown only when TLS is on	Yes (default)

There’s no field for a custom CA or a client certificate, so mutual TLS isn’t supported. For production, use a node certificate from a publicly trusted CA so verification can stay on.

A stock cassandra.yaml ships with client-to-node encryption off. Setting Use TLS to No to match it sends the role name and password in clear text to anything on the network path.

---

Required permissions

Agents can	Grant the role
List keyspaces and tables, audit schema settings, report ring state	Nothing beyond LOGIN = true
Read rows	SELECT ON KEYSPACE
Insert, update, or delete one row	MODIFY ON KEYSPACE
Change a table’s TTL or gc_grace_seconds, create or drop a secondary index	ALTER ON KEYSPACE

Grant on named keyspaces, never ON ALL KEYSPACES. The grant decides what Cassandra allows; approvals only decide whether CloudThinker asks.

---

Agent capabilities

Capability	Description
Inventory	List keyspaces and tables with replication strategy and primary key shape
Schema audit	Report replication factor, default_time_to_live, gc_grace_seconds, compaction, and secondary indexes
Ring health	Report datacenters, racks, release versions, and schema agreement as the driver sees them
Row reads	Read one partition by key, 100-row cap
Approved changes	Change one row, one table setting, or one secondary index, from a fixed set of operations

“Read rows in shop.events where user_id = ‘u-42’” stays in one partition. A scan across partitions runs only when you ask for one, such as “scan shop.events”, with the same 100-row cap. It doesn’t use ALLOW FILTERING, but the coordinator walks token ranges until the 100-row cap fills. On a large or tombstone-heavy table, it loads the cluster far more than the row count suggests. Rules match only writes, so a Rule can’t block a scan. To avoid one, ask for rows by partition key.

Verify the connection

List the Cassandra keyspaces and the tables in each one

Success state: CloudThinker returns each keyspace with its replication settings and tables.

Example prompts

Audit replication factor, TTL, and gc_grace_seconds for every table in the shop keyspace
Show the row in shop.sessions where session_id = 'abc-123'
Set the default TTL on shop.events to one day

shop is an example keyspace. Use your own. The third prompt is a change. CloudThinker first reads the current TTL, tells you the new value and that it only applies to rows written afterwards, then sends the change through your approvals.

---

Write access

New Cassandra connections have Allow writes on. To change it, open More → Workspace settings → Connections, select Cassandra, and use the Allow writes switch on its detail panel. You need the workspace Admin role. The change takes effect at once. Turn it off and agents can only read.

Flipping the switch isn’t recorded in Admin Settings → Audit Logs. For an auditable boundary, rely on the role’s grants instead: without MODIFY and ALTER, Cassandra refuses every change whatever the switch says, and grant changes show up in Cassandra’s own audit log if you turn it on (Cassandra 4.0 and later).

Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself.

On a production ring, choose Manual so a person approves every row change. That is the control that holds today. Once CloudThinker turns on Rule enforcement for your workspace, an Ask first Rule can narrow the wait to the row changes you care about:

1. Ask for the Rule

   In a chat, type /create-policy Ask first for every write on the Cassandra connection.

2. Check the proposal

   Open Approvals in the sidebar, then Rules → Needs review, and open the Rule. Check that Effect is Ask first, the Rule carries the Every operation badge, and Connections names your Cassandra connection.

3. Accept it

   Select the Rule and click Accept.

   Success state: a toast confirms the accepted Rule, and it moves to the Active tab.

Changes are not arbitrary CQL. The connection carries a fixed set of operations:

Operation	Scope
insert, update, delete	Exactly one row. You must name every primary key column, so a partition-wide or range delete can’t be expressed
Table settings	default_time_to_live and gc_grace_seconds only
Secondary indexes	Create or drop one index

What to know before you approve one:

• Every change shows its evidence. The output has the value read before the change, the result, and an undo command. Running the undo is a separate change that goes through your approvals on its own.
• Some operations don’t exist. TRUNCATE, DROP TABLE, DROP KEYSPACE, ALTER KEYSPACE, GRANT, and ALTER ROLE are refused. Ask for one and CloudThinker tells you what an operator would run instead.
• Nothing rolls back. A delete writes a tombstone: the row reads as gone at once, and the space returns only after gc_grace_seconds and compaction. A new TTL applies only to rows written after the change.

Adding a second Cassandra connection to the same workspace turns writes off for both, because an approved change can’t name which ring it targets. Keep one Cassandra connection per workspace while you need changes.

---

Rotate the password

1. Set a new password on the role:
   ALTER ROLE cloudthinker WITH PASSWORD = 'new-secure-password';
   
   The old password stops working for new sessions, so finish step 2 right away.
2. Open More → Workspace settings → Connections, select Cassandra, click the pencil icon on the instance’s row, and in Edit Instance click Replace…. Enter the new Password and click Save and test.

Success state: the test passes and the connection stays Connected. If the test fails, CloudThinker keeps the previous credentials and shows the error. Fix the value and save again.

---

Troubleshooting

No contact point answered on the native transport port

• Contact points must have no port and no scheme. The port goes in its own field.
• Native transport port must be the CQL port. 7199 is JMX and 7000 is internode.
• Check the firewall between CloudThinker and the nodes. It must be open to every node in the local datacenter, not only the contact points.

Contact point is an IPv6 address

IPv6 addresses aren’t supported. Use a hostname that resolves to the node.

Cassandra rejected the role name or the password

Check the role exists with LIST ROLES;. A role created without LOGIN = true can’t sign in: run ALTER ROLE cloudthinker WITH LOGIN = true;.

The TLS handshake failed

Check whether the cluster expects TLS. For a self-signed or internal-CA certificate, keep Use TLS on Yes and set Verify the TLS certificate to No. The session stays encrypted but no longer proves which server answered.

Local datacenter is not in this cluster

The name in Local datacenter doesn’t match. The error lists the datacenters the cluster has. Copy one, or leave the field blank.

Connected, but queries time out or fail on some nodes

The contact points answered, but the driver can’t reach the other nodes the ring reports. Open 9042 to every node in the local datacenter, and set each node’s broadcast_rpc_address to an address CloudThinker can reach. See Setup step 4.

A change timed out

Cassandra returns a timeout both before and after a write commits, so the outcome is unknown and nothing is retried. Ask CloudThinker to read the row or setting again, then decide. Never re-run the change to find out.

An index was created but queries still fail

A new secondary index answers queries only after its build finishes on every node. Wait, then ask again.

---

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• TLS carries the password: the role name and password travel on the same socket as the queries. Keep Use TLS on outside a private network.
• Start with no grants: a login role with no grant already answers inventory, schema, and health questions. Add SELECT, MODIFY, and ALTER per keyspace only when you need them.

---

Related

Approvals

Decide which changes run on their own and which wait for you

ClickHouse Connection

Connect a ClickHouse cluster for analytical queries

Connections overview

How credentials and write controls work across connections