Cassandra

Cassandra's connector uses the DataStax cassandra-driver. Queries are plain CQL — SQL-like but with its own syntax for partition keys, allow filtering, and LIMIT.

Quick example

databases:
  - name: <database>          # used as --database <database> in queries
    type: cassandra
    host: localhost
    port: 9042
    database: <keyspace>      # default keyspace; queries can also address other keyspaces
    username: <username>
    password: <password>

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — SELECT, CALL, DESCRIBE
    # W    write only          — INSERT, UPDATE, DELETE (no SELECT)
    # RW   read + write
    # RA   read + append       — SELECT + INSERT
    # RWA  read + write, no DELETE
    # A    admin (incl. CREATE, ALTER, DROP, TRUNCATE)

See Permissions for the full model, per-table overrides, and the operation matrix.

faz query "SELECT * FROM <keyspace>.<table> LIMIT 5" --database <database> --table <table>

uv run faz query "SELECT * FROM <keyspace>.<table> LIMIT 5" --database <database> --table <table>

python -m faz query "SELECT * FROM <keyspace>.<table> LIMIT 5" --database <database> --table <table>

Configuration

Capabilities

• Reads: SELECT, CALL, DESCRIBE are included in the R access level.
• Writes: INSERT, UPDATE, DELETE are gated by RBAC.
• DDL: CREATE, ALTER, DROP, TRUNCATE require the A access level.
• Schema discovery enumerates user keyspaces and their tables. Tables surface as <keyspace>.<table> so the namespace is unambiguous.
• The Guardrails stage emits LIMIT n for row caps; CQL's LIMIT is functionally identical to SQL's.

Limitations

• System keyspaces are excluded from schema discovery: system, system_auth, system_distributed, system_traces, system_schema. You can still query them directly if your policy permits, but they don't appear in list_databases output.

• Allow filtering isn't auto-injected by Guardrails. If your query needs ALLOW FILTERING to run, include it explicitly. faz doesn't second-guess CQL semantics.

• Stacked statements and explicit BEGIN BATCH blocks are blocked at the connector level. Two CQL statements separated by ; are rejected before they reach Cassandra — defense-in-depth against stacked-query injection. CQL's explicit BEGIN BATCH ... APPLY BATCH syntax (which bundles multiple writes) is also rejected because it isn't a single statement. Even if RBAC would allow each statement individually, the connector refuses to send the combined string.

  Blocked — stacked statements or BEGIN BATCH blocks:

  -- Two top-level statements separated by `;`
  SELECT * FROM <keyspace>.<table-1>; DELETE FROM <keyspace>.<table-2>;
  
  -- Explicit batch — multiple writes in one block
  BEGIN BATCH
    INSERT INTO <keyspace>.<table-1> (...) VALUES (...);
    INSERT INTO <keyspace>.<table-2> (...) VALUES (...);
  APPLY BATCH;

  Allowed — single CQL statements. RBAC checks every table they touch:

  -- SELECT with IN clause across multiple partition keys
  SELECT * FROM <keyspace>.<table> WHERE <partition-key> IN (?, ?, ?);
  
  -- Lightweight transaction — one statement
  INSERT INTO <keyspace>.<table> (...) VALUES (...) IF NOT EXISTS;
  
  -- Conditional update — one statement
  UPDATE <keyspace>.<table> SET <col> = ? WHERE <partition-key> = ? IF <col> = ?;

  Submit batched writes as separate faz query calls — one statement per call.

Troubleshooting

NoHostAvailable — every contact point is down or unreachable. Verify with cqlsh host port.

Unauthorized: User X has no SELECT permission — Cassandra-level RBAC is denying the read. faz's permission check passed; Cassandra's didn't. Grant the role explicitly: GRANT SELECT ON KEYSPACE events_keyspace TO 'app';.

Keyspace 'X' does not exist — database value or the keyspace. prefix in your query is wrong. List with cqlsh -e "DESC KEYSPACES;".

SSL: CERTIFICATE_VERIFY_FAILED — your cluster uses TLS with a CA bundle faz doesn't trust. Configure the trust store at the OS level or use a TLS-terminating proxy in front.

For the broader troubleshooting flow, see Connection failed.

Related

• Databases overview — cross-connector basics.
• Permissions — how access codes map to CQL operations.
• faz.yaml — the full config schema.