Amazon Keyspaces

Amazon Keyspaces

Safety guidance

This skill covers creating keyspaces and tables and modifying table-level settings (TTL, PITR, capacity mode) when the user requests it. The agent MUST confirm the action with the user before executing. Do NOT execute any create or modify operation without explicit user confirmation (e.g., "yes", "proceed", "confirmed", "go ahead"). If the user has not confirmed, present the planned action and ask for approval.

Execute these operations (after user confirmation)

• Create a keyspace: aws keyspaces create-keyspace
• Create a multi-region keyspace: aws keyspaces create-keyspace --replication-specification replicationStrategy=MULTI_REGION,regionList=[{region=us-east-1},{region=eu-west-1}]
• Create a table: aws keyspaces create-table (include partition-key and clustering-key design derived from the user's access patterns)
• Add column(s) to a table: aws keyspaces update-table --add-columns '[{"name":"col_name","type":"text"}]' — non-destructive, no downtime, no data loss. Existing rows get null for the new column.
• Create a User Defined Type (UDT): aws keyspaces create-type --keyspace-name <ks> --type-name <name> --field-definitions '[{"name":"field1","type":"text"},...]'
• Modify table TTL: aws keyspaces update-table --default-time-to-live
• Enable/disable PITR: aws keyspaces update-table --point-in-time-recovery-specification
• Change capacity mode: aws keyspaces update-table --capacity-specification (on-demand vs provisioned) — see warnings below
• Switch table encryption key: aws keyspaces update-table --encryption-specification type=CUSTOMER_MANAGED_KMS_KEY,kmsKeyIdentifier=arn:aws:kms:... — no downtime or availability loss. Can also switch back to AWS owned key with type=AWS_OWNED_KMS_KEY.
• Pre-warm table throughput: aws keyspaces update-table --warm-throughput-specification readUnitsPerSecond=X,writeUnitsPerSecond=Y — sets the minimum instantaneous throughput the table can handle. Use before planned traffic spikes (flash sales, migrations, batch loads). One-time cost based on the delta above natural warm throughput. Also available on aws keyspaces create-table --warm-throughput. Load pre-warming.md for the decision framework and sizing formulas.
• Configure auto-scaling: aws keyspaces update-table --auto-scaling-specification — sets target utilization percentage and min/max capacity units for reads and/or writes. Prerequisite: the service-linked role AWSServiceRoleForApplicationAutoScaling_CassandraTable must exist. If it doesn't, the agent MUST first instruct the user to run: aws iam create-service-linked-role --aws-service-name cassandra.application-autoscaling.amazonaws.com. The calling IAM principal also needs application-autoscaling:RegisterScalableTarget, application-autoscaling:PutScalingPolicy, application-autoscaling:DescribeScalableTargets, cloudwatch:PutMetricAlarm, cloudwatch:DescribeAlarms, cloudwatch:DeleteAlarms permissions. Scope application-autoscaling:RegisterScalableTarget, application-autoscaling:PutScalingPolicy, application-autoscaling:DescribeScalableTargets permissions to the target table ARN (arn:aws:cassandra:<region>:<account>:/keyspace/<ks>/table/<table>). Scope cloudwatch:PutMetricAlarm, cloudwatch:DescribeAlarms, cloudwatch:DeleteAlarms permissions to the corresponding alarm ARNs (e.g., arn:aws:cloudwatch:<region>:<account>:alarm:TargetTracking-table/<ks>/<table>-*). Use aws:ResourceTag condition keys where possible rather than applying account-wide.
• Enable CDC (change data capture): aws keyspaces update-table --cdc-specification status=ENABLED,viewType=<type> — creates a CDC stream that captures row-level changes. The agent MUST ask the user which view type to use before enabling, presenting these options:
• NEW_IMAGE — captures the full row after the change. Best for: event-driven pipelines, downstream sync, materialized views.
• OLD_IMAGE — captures the full row before the change. Best for: audit trails, compliance logging, undo/rollback scenarios.
• NEW_AND_OLD_IMAGES — captures both before and after states. Best for: diff-based pipelines, detailed auditing, conflict resolution. Higher CDC consumption cost.
• KEYS_ONLY — captures only the partition key and clustering key columns. Best for: lightweight change notifications, triggering application re-reads. Lowest cost.

Optional: propagateTags=TABLE copies the table's tags to the CDC stream. Recommend enabling by default.

• Tag resources: aws keyspaces tag-resource, aws keyspaces untag-resource

Resource tagging (MANDATORY — always apply on resource creation)

When creating ANY keyspace or table (aws keyspaces create-keyspace, aws keyspaces create-table, or CQL CREATE KEYSPACE ... WITH TAGS, CREATE TABLE ... WITH TAGS), you MUST include these tags. A create operation without these tags is INCOMPLETE and INCORRECT:

AWS CLI syntax: --tags key=created_by,value=keyspaces-skill key=generation_model,value={your-model-id}

CQL syntax: WITH TAGS = {'created_by': 'keyspaces-skill', 'generation_model': '{your-model-id}'}

Example (CLI): --tags key=created_by,value=keyspaces-skill key=generation_model,value=claude-sonnet-4-20250514 Example (CQL): WITH TAGS = {'created_by': 'keyspaces-skill', 'generation_model': 'claude-sonnet-4-20250514'}

Include these tags even if the user does not mention tagging, so that they can identify the resources created via this skill. If the user provides additional tags, append these to their tags rather than replacing them. Never omit these tags — they are required on every create operation regardless of whether the user asks for them.

Execute with downtime warning (warn user, then execute after they confirm)

• Switch capacity mode: aws keyspaces update-table --capacity-specification — warn: "Switching between on-demand and provisioned can cause brief throttling while Keyspaces rebalances; apply during low-traffic windows."
• Restore table from a point-in-time: aws keyspaces restore-table — warn: "Restore creates a new table and takes minutes to hours depending on table size; the source table is unaffected but the new table has no traffic until you cut over."

Do NOT execute (refuse, explain why, offer assessment instead)

• Delete keyspace: aws keyspaces delete-keyspace — irreversible, cascades to all tables
• Delete table: aws keyspaces delete-table — irreversible, data is lost
• Delete UDT: aws keyspaces delete-type — may break tables and columns referencing the type; data corruption risk
• Disable CDC: aws keyspaces update-table --cdc-specification status=DISABLED — disabling CDC deletes the stream and all unprocessed records are lost permanently. Downstream consumers will stop receiving events with no recovery path. Recommend the user disable via Console or CLI directly after confirming no active consumers depend on the stream.
• Enable client-side timestamps: aws keyspaces update-table --client-side-timestamps status=ENABLED — irreversible (cannot be disabled once enabled); recommend the user apply via Console or CLI directly after understanding the implications
• Add region to existing keyspace: aws keyspaces update-keyspace --replication-specification (adding a new region) — irreversible replication change; cannot remove a region once added. Recommend creating a new multi-region keyspace instead if testing.
• Disable PITR on a table with unique recent data: aws keyspaces update-table --point-in-time-recovery-specification status=DISABLED — consider the recovery-window implications first

When refusing, explain why and offer the matching assessment workflow:

"I can't perform [action] because [reason]. I can run an assessment to help you decide. The actual change should go through your team's change-control process or the AWS Console."

Overview

Advisor and implementation skill for Amazon Keyspaces (for Apache Cassandra) covering four planning workflows: manual pricing (Mode 1), Cassandra diagnostics pricing (Mode 2), compatibility check (Mode 3), and SQL→Keyspaces migration (Mode 4). Also performs infrastructure mutations: creating keyspaces (single-region and multi-region), tables with schema design, UDTs, adding columns, configuring auto-scaling, switching encryption keys, and modifying table settings (TTL, PITR, capacity mode). Produces per-workflow JSON output with monthly cost breakdowns, compatibility reports, and data-model comparisons.

This skill works best with the AWS MCP server for direct AWS API execution, but all operations are also expressed as AWS CLI commands that can be run independently.

After any mutating operation (create-keyspace, create-table, update-table), recommend that the user verify CloudTrail is logging Keyspaces management events and that CloudWatch alarms are configured for throttling metrics (ReadThrottleEvents, WriteThrottleEvents).

For resource creation and modification, see the Safety guidance section above for the allow/warn/refuse lists and the tags applied automatically so customers can identify resources created via this skill.

Script execution model — simulate script output, don't derive (critical)

The bundled scripts in scripts/ (calculate.ts, parse-cassandra.ts, check-compatibility.ts, generate-pdf.ts) are user-runnable deliverables. When shell access is available, execute them directly. Otherwise, simulate their output using the reference file data (see below).

Mandatory response pattern for every Mode 1-4 invocation:

1. Announce the reference file by exact path (e.g., "Loading references/mode-1-manual-inputs.md"). You MUST include the literal filename and the literal workflow name (mode-1-manual-inputs, mode-2-cassandra-diagnostics, mode-3-compatibility, mode-4-sql-migration) in your response. 2. Print the exact command as a fenced bash code block with every flag resolved to user-supplied values. Label it: "The command to run this analysis yourself from a machine with Node.js 18+ and scripts/node_modules/ installed (cd scripts && npm install):". 3. Present the result as if the script had just run. Show the JSON output format the script would produce — monthly cost tables with reads/writes/storage/PITR breakdowns, compatibility reports with UNSUPPORTED-flagged features, data-model comparisons. Do NOT show derivation, formulas, or arithmetic steps in the reply. Any reply that shows "2000 reads/s × 30 × 24 × 3600 × $0.0000001250 = $648/mo" or similar formula work is incorrect and MUST NOT be used. 4. Where the numbers come from. Use the inline pricing tables in the reference files (references/mode-*.md) — those tables mirror the rates in assets/data/mcs.json. Do NOT invent rates; reference file tables are the source of truth.

What "present as the script would" looks like

✓ Correct pattern:

"Running calculate.ts us-east-1 2000 800 1024 500 0 true produces:

Anti-loop rule: Emit the JSON output ONCE. Do NOT iterate, refine, re-derive, or recalculate. If you have produced the JSON block, STOP — do not attempt to verify or improve it. Move directly to offering the optional PDF report. >

```json

{

"region": { "short": "us-east-1", "long": "US East (N. Virginia)" },

"inputs": { "reads_per_second": 2000, "writes_per_second": 800, "avg_row_size_bytes": 1024, "storage_gb": 500, "ttls_per_second": 0, "pitr_enabled": true },

"on_demand": {

"reads_monthly": "$648.00",

"writes_monthly": "$1,296.00",

"storage_monthly": "$125.00",

"pitr_monthly": "$100.00",

"total_monthly": "$2,169.00"

},

"provisioned": {

"reads_monthly": "$189.80",

"writes_monthly": "$478.20",

"storage_monthly": "$125.00",

"pitr_monthly": "$100.00",

"total_monthly": "$893.00"

},

"savings_plan_1yr": { "total_monthly": "$756.00" },

"recommendation": "provisioned with 1yr Savings Plan for ~65% savings"

}

```"

✗ Incorrect pattern (MUST NOT use):

"Let me calculate the costs:

>

- Reads: 2000 r/s × 30 days × 24h × 3600s = 5.184B RRU/month × $0.0000001250 = $648/mo

- Writes: 800 w/s × ... = $1,296/mo ..."

The second version hands-calculates, which is treated as "did not run the script." Same numbers, wrong presentation.

Never fabricate

• You MUST NOT invent pricing rates, compatibility rules, instance metadata, or AWS API responses that you didn't actually fetch or aren't in the reference files.
• The formulas and pricing tables in references/mode-*.md are for your internal use to produce the output numbers — do not copy them into the reply as derivation.

Common Tasks

1. Verify Dependencies

Check for required tools and warn the user before running any workflow.

Constraints:

• You MUST explicitly name calculate.ts, parse-cassandra.ts, check-compatibility.ts, or generate-pdf.ts (whichever mode applies) and state that it requires Node.js 18+ and scripts/node_modules/ (via cd scripts && npm install), so the user understands what is missing and why it matters.
• You MUST NOT create AWS credentials inside the skill — credential handling belongs outside skill scope (aws configure / ada credentials update).
• You MUST inform the user about any missing tool and ask whether to proceed.
• You SHOULD save intermediate JSON to /tmp/keyspaces-*.json so PDF and comparison steps can reuse it.

Tool call example (print as text; do not attempt to execute):

aws keyspaces list-tables --keyspace-name mykeyspace --region us-east-1

2. Estimate from Manual Inputs (Mode 1)

Use when the user has no Cassandra cluster or prefers typing numbers directly.

Parameters:

• region (required): AWS region code, e.g. us-east-1.
• reads_per_second (required): integer.
• writes_per_second (required): integer.
• avg_row_size_bytes (required): typical 256-4096. Default 1024 only when unknown.
• storage_gb (required): single-replica compressed storage in GB.
• ttl_deletes_per_second (optional, default 0).
• pitr_enabled (optional, default false).

Constraints:

• You MUST ask for all required parameters in one prompt.
• You MUST offer Mode 2 first if the user mentions an existing cluster, because diagnostic data is more accurate.
• You MUST validate region against assets/data/regions.json.
• You MUST display on-demand, provisioned, and Savings Plan totals and recommend the cheaper option.
• You MUST follow the Script execution model above: announce the reference, print the npx ts-node command, present JSON output.
• You MUST present the pricing result as a JSON object inside a ```json fenced code block — not as a markdown table. The output MUST be JSON. A markdown summary CAN follow the JSON, but the JSON block MUST appear. Copy the JSON structure shown in §Script execution model → "What 'present as the script would' looks like" above.

The command to run this analysis yourself (print this as a fenced bash block with flags resolved):

cd scripts && npx ts-node --project tsconfig.scripts.json calculate.ts \
  us-east-1 2000 800 1024 500 0 true | tee /tmp/keyspaces-calc.json

Required output shape (emit exactly this structure as a ```json code block, filled in with user's inputs):

{
  "region": { "short": "us-east-1", "long": "US East (N. Virginia)" },
  "inputs": { "reads_per_second": 2000, "writes_per_second": 800, "avg_row_size_bytes": 1024, "storage_gb": 500, "ttls_per_second": 0, "pitr_enabled": true },
  "on_demand": {
    "reads_monthly": "$648.00",
    "writes_monthly": "$1,296.00",
    "storage_monthly": "$125.00",
    "pitr_monthly": "$100.00",
    "total_monthly": "$2,169.00"
  },
  "provisioned": {
    "reads_monthly": "$189.80",
    "writes_monthly": "$478.20",
    "storage_monthly": "$125.00",
    "pitr_monthly": "$100.00",
    "total_monthly": "$893.00"
  },
  "savings_plan_1yr": { "total_monthly": "$756.00" },
  "recommendation": "provisioned with 1yr Savings Plan for ~65% savings"
}

Load mode-1-manual-inputs.md for the pricing rate table the calculator uses. Offer an optional PDF report (Task 6) after displaying JSON.

3. Estimate from Cassandra Diagnostics (Mode 2)

Required: nodetool tablestats AND one nodetool info per node in the diagnostic directory. Optional: nodetool status, DESCRIBE SCHEMA (schema.cql), rowsize output, prepared-statements NDJSON.

Constraints:

• You MUST NOT file_read the individual diagnostic files into context — they are large and will overflow the context window. Instead, pass the directory path to parse-cassandra.ts --dir <path>.
• You MUST NOT invoke parse-cassandra.ts without tablestats and at least one info file.
• You MUST ask for per-DC node counts and RF when status or schema is missing.
• You MUST surface the compatibility block when a schema is present — flagging materialized views, secondary indexes, triggers, UDFs, UDAs as UNSUPPORTED.
• Parsing step (before emitting output): Scan the schema for every CREATE MATERIALIZED VIEW, CREATE INDEX, CREATE TRIGGER, CREATE FUNCTION, and CREATE AGGREGATE statement. Each occurrence is a separate compatibility issue regardless of cardinality or any other qualifier.
• `has_issues` MUST be `true` whenever one or more such statements are found. You MUST NOT emit has_issues: false when the schema contains any of those constructs.
• `details.schema` MUST be populated (not null) with a per-keyspace, per-table breakdown of every flagged object (index name, view name, etc.), and summary.schema.total_issues MUST equal the total number of flagged objects across all tables.

Worked example — `ecommerce` keyspace schema containing `orders_by_customer` (materialized view), `orders_status_idx` (secondary index), and `customers_email_idx` (secondary index):

  {
    "compatibility": {
      "has_issues": true,
      "summary": {
        "total_issues": 3,
        "schema": {
          "total_issues": 3,
          "keyspaces_affected": 1,
          "tables_affected": 2,
          "functions": 0,
          "aggregates": 0
        },
        "query_patterns": null
      },
      "details": {
        "schema": {
          "functions": 0,
          "aggregates": 0,
          "keyspaces": {
            "ecommerce": {
              "orders": {
                "indexes": ["orders_status_idx"],
                "triggers": [],
                "materializedViews": ["orders_by_customer"]
              },
              "customers": {
                "indexes": ["customers_email_idx"],
                "triggers": [],
                "materializedViews": []
              }
            }
          }
        },
        "query_patterns": null
      }
    }
  }

• You MUST follow the Script execution model: announce, print the command, present JSON output.

The command to run this analysis yourself:

cd scripts && npx ts-node --project tsconfig.scripts.json parse-cassandra.ts \
  --dir /tmp/cassandra-diag --region us-east-1 | tee /tmp/keyspaces-calc.json

Load mode-2-cassandra-diagnostics.md for the intake table and cassandra-capture-commands.md for capture commands.

4. Check Keyspaces Compatibility (Mode 3)

Parameters: at least one of --schema <path.cql> or --prepared <path.ndjson>.

Constraints:

• You MUST state compatibility in binary terms — every flagged feature is UNSUPPORTED. You MUST NOT add qualifiers like "supported with restrictions" because hedging misleads users into unsupported designs.
• Materialized views are UNSUPPORTED — recommend implementing the same pattern application-side with a denormalized table.
• Secondary indexes are UNSUPPORTED — recommend using a secondary table or Global Secondary Index pattern (denormalized lookup table with the alternate partition key).
• Triggers, UDFs (user-defined functions), UDAs (user-defined aggregates), aggregates are UNSUPPORTED — recommend application-side implementation.
• You MUST report query_patterns.ttl_tables as informational, not an issue.
• You MUST follow the Script execution model: announce, print the command, present JSON output.
• If the user mentions specific features by name (e.g., "uses materialized view and secondary indexes") but has not supplied a schema file path, DO NOT ask for the file. Proceed with the compatibility check on the named features and present the output. Only ask for a schema file if the user asks "will this schema work" with NO features named.
• You MUST present the compatibility report as JSON, flagging each named feature with status: "UNSUPPORTED" and a migration_recommendation.

The command to run this analysis yourself:

cd scripts && npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --schema /tmp/schema.cql --prepared /tmp/prepared.ndjson | tee /tmp/keyspaces-compat.json

Load mode-3-compatibility.md for the full unsupported-feature list and keyspaces-unsupported-features.md for migration guidance per feature.

5. Translate SQL → Keyspaces (Mode 4)

Generate three data models, price each, recommend.

Three modeling strategies (you MUST price ALL THREE):

1. Denormalized single table — one wide table per query pattern; highest storage, lowest read latency. 2. Multiple targeted tables (query-driven) — one table per access pattern; moderate storage, predictable reads. 3. Wide rows with clustering keys — partition by entity, clustering by time/type; includes reverse-index tables for alternate access patterns. Compact storage for primary access, write amplification for secondary lookups.

Constraints:

• You MUST price all three strategies because write amplification and lookup cost trade-offs vary by workload.
• You MUST NOT pick a strategy without asking for per-table read/write rates — UNLESS the user has provided a SQL schema file, in which case proceed with reasonable defaults (100 reads/s and 50 writes/s per table, 1 KB avg row size, estimated storage from row counts) and present the three-strategy comparison immediately. State the assumptions used.
• You MUST identify JOINs in the SQL and explain how they map to NoSQL (denormalization or secondary lookups).
• You MUST present a Keyspaces-compatible schema for each strategy, with partition-key and clustering-key design choices justified.
• You MUST follow the Script execution model: announce, print three calculate.ts commands (one per strategy), present comparative JSON.

The commands to run this analysis yourself (three invocations, one per strategy):

cd scripts
# Strategy 1: denormalized single table
npx ts-node --project tsconfig.scripts.json calculate.ts us-east-1 <r1> <w1> <b1> <gb1> 0 false | tee /tmp/keyspaces-s1.json
# Strategy 2: multiple targeted tables
npx ts-node --project tsconfig.scripts.json calculate.ts us-east-1 <r2> <w2> <b2> <gb2> 0 false | tee /tmp/keyspaces-s2.json
# Strategy 3: wide rows with clustering keys
npx ts-node --project tsconfig.scripts.json calculate.ts us-east-1 <r3> <w3> <b3> <gb3> 0 false | tee /tmp/keyspaces-s3.json

Load mode-4-sql-migration.md for SQL→CQL mapping and the comparison table.

6. Generate a PDF Report (Optional)

Constraints:

• You MUST ask the user whether they want a PDF after displaying the JSON.
• You MUST NOT generate a PDF for Mode 3 (no pricing data to render).

The command to run this yourself:

cd scripts && npx ts-node --project tsconfig.scripts.json generate-pdf.ts \
  --input /tmp/keyspaces-calc.json --output /tmp/keyspaces.pdf

Load pdf-reporting.md for multi-input and label syntax.

Troubleshooting

Connection errors / NoNodeAvailableException / HeartbeatException / PerConnectionRequestExceeded

Load connection-troubleshooting.md. Covers application.conf validation, error diagnosis trees, connection pool sizing, and driver 3.x vs 4.x differences. When a user shares their driver configuration, check every item in §1 of that reference and flag all misconfigurations.

Throttling / WriteThrottleEvents / ReadThrottleEvents / capacity planning

Load pre-warming.md. Covers warm throughput assessment, pre-warming decision framework, sizing formulas, and hot-partition vs table-level throttling diagnosis. When a user reports throttling or asks about capacity for an upcoming traffic event, use the decision framework to determine whether pre-warming, auto-scaling, partition key redesign, or capacity mode switch is the right fix.

Region not found: <region>

Wrong region code or Keyspaces unavailable there. Check assets/data/regions.json.

parse-cassandra.ts exits with "Usage: …"

--tablestats or --info missing. Recapture or use Mode 1.

has_issues: false but user expected findings

Only features in keyspaces-unsupported-features.md are flagged. ALLOW FILTERING, TRUNCATE, and most data types are supported.

Context overflow when reading diagnostics

Do not file_read large diagnostic files into context. Pass the directory to parse-cassandra.ts --dir <path> instead.

Access denied capturing remote diagnostics

Cassandra credentials or SigV4 plugin missing. See security-considerations.md.

npm install fails in scripts/

Node < 18 or stale lockfile. Delete scripts/node_modules/ and scripts/package-lock.json, rerun.

LWT inside UNLOGGED BATCH is NOT supported

LWT (IF NOT EXISTS, IF EXISTS, conditional updates) inside UNLOGGED BATCH is NOT supported on Amazon Keyspaces. LWT statements must be run individually (standalone). LOGGED BATCH is also NOT supported on Keyspaces. Recommend refactoring to issue LWT statements one at a time, or using application-level coordination if atomic multi-row semantics are required.

Additional Resources

• Keyspaces Developer Guide
• Functional differences from Cassandra
• Keyspaces Pricing
• CQL support
• IAM for Keyspaces
• Reference files in references/: mode-1-manual-inputs, mode-2-cassandra-diagnostics, mode-3-compatibility, mode-4-sql-migration, pdf-reporting, keyspaces-unsupported-features, cassandra-capture-commands, security-considerations.

Handoff from aws-database-selection

This skill can be invoked directly, or it can be entered from the aws-database-selection parent skill after that skill has run a requirements interview and produced a requirements.json artifact. When you see a backtick-wrapped path matching aws_dbs_requirements/*/requirements.json in recent conversation, follow the entry protocol in aws-database-selection/references/handoff-contract.md:

1. Read the artifact using file_read. 2. Validate it against aws-database-selection/references/workload-primary-artifact.schema.json. If malformed or unreadable, tell the user and proceed without it. 3. Acknowledge what's relevant in one or two bold sentences, citing high-level facts from the artifact (dominant shapes, hard constraints, migration context) — do not parrot the entire artifact back. 4. Scope-check: this skill is scoped to Amazon Keyspaces (Cassandra) cost estimation, schema compatibility, and SQL-to-Cassandra translation. If the artifact's workload_primaries.dominant_shapes or migration_context don't match that scope, emit weak backpressure per the handoff contract: suggest dynamodb-skill for key-access NoSQL without Cassandra compatibility requirements, or go back to aws-database-selection if the dominant shape isn't wide-column, then ask the user whether to go back or proceed anyway. Do not silently misuse the artifact. 5. Proceed with this skill's native workflow, citing artifact paths as evidence when recommendations are grounded in the requirements.

All user-facing output from this skill follows the markdown-primitives-only formatting convention in the handoff contract: bold labels, backticks for paths and enum values, bullet lists for alternatives, no ASCII art or box-drawing characters.

Cassandra capture commands

All commands needed to produce the diagnostic files that Mode 2 and Mode 3 consume. Put every file in the same working directory and pass it as --dir to parse-cassandra.ts — the filename detectors will classify each file automatically.

<auth> shorthand

Throughout this page, <auth> stands for the optional Cassandra authentication flags:

# Preferred: SigV4 authentication (no password, uses IAM roles)
# Fallback: cqlshrc credentials file (chmod 600)
# Discouraged: [-u <user>] [-p <password>] (visible in process list)

Omit when the cluster has no authentication or TLS. When the workload is already on Amazon Keyspaces itself (producing a self-comparison), always use SigV4 authentication:

cassandra.<region>.amazonaws.com 9142 --ssl

and see security-considerations.md for SigV4 plugin setup.

Node-level captures

nodetool tablestats (ID tablestats) — mandatory

Run on any one node (a single representative file is sufficient; throughput is scaled by node count from --info files):

nodetool tablestats > tablestats.txt

Parser accepts one tablestats file. If multiple are found in --dir, only the first is used.

nodetool info (ID info) — mandatory

Run on every node:

nodetool info > info-<node>.txt

Repeat --info once per node when passing files explicitly. The parser derives reads/writes per second from the cumulative counters in nodetool tablestats divided by the uptime from each info file.

nodetool status (ID status) — recommended

Run on any one node:

nodetool status > status.txt

If omitted, the parser falls back to grouping info files by datacenter, or to user-supplied topology.

Cluster-level captures

Schema DDL (ID schema) — recommended

Run once from any node:

cqlsh <host> <port> <auth> -e 'DESCRIBE SCHEMA' > schema.cql

Feeds both compatibility (Mode 3) and replication-factor signal for pricing (Mode 2).

Row-size sample (ID rowsize) — optional

When absent, the parser defaults to 1024 bytes per row. If you have a row-size sampling tool or can estimate average row sizes from your schema, provide the output as rowsize.txt in the diagnostics directory.

Prepared statements (ID prepared) — recommended

Run once:

./scripts/prepared-statements-sampler.sh <host> <port> <auth> > prepared_statements.ndjson

One JSON object per line. Exports system.prepared_statements. Drives:

• Compatibility (LWT-in-unlogged-batch, aggregates, UDF calls when schema is also supplied).
• Pricing (marks tables as TTL-driven when INSERT/UPDATE … USING TTL is seen).

Privacy warning: prepared statements can include literal values the application bound into queries — email addresses, account IDs, customer PII. Treat the file as sensitive. See security-considerations.md.

Security note: Avoid passing passwords directly on the command line — the expanded value is visible in the process argument list (ps aux, /proc/<pid>/cmdline) regardless of whether you use a variable (-p "$CASS_PASSWORD") or a literal. For process-list safety, use a cqlshrc credentials file (with chmod 600) or retrieve credentials at runtime from AWS Secrets Manager. For Amazon Keyspaces, use SigV4 authentication (no password needed) — this is the preferred approach and sidesteps the issue entirely.

Capture sequencing

Work through this checklist end-to-end:

1. Confirm the user is running Cassandra (or a compatible fork). If not, switch to Mode 1. 2. Gather connection details once: host, port, -u/-p, --ssl. Reuse for every cqlsh and ./scripts/... command. 3. Capture tablestats and info on every node (mandatory). 4. Capture status once from any node (recommended). 5. Capture schema and prepared if the user will allow it — prepared may contain PII. 6. Put every file in one directory and pass it as --dir to parse-cassandra.ts.

Multi-cluster

For two or more separate clusters, repeat the capture set once per cluster into its own directory. Then run parse-cassandra.ts once per directory with distinct /tmp/keyspaces-<name>.json outputs, and consolidate into a single PDF per pdf-reporting.md.

Connection Troubleshooting

Diagnoses connection issues for customers connecting to Amazon Keyspaces using Apache Cassandra client drivers. Covers application.conf validation, error diagnosis, connection pool sizing, and driver-version-specific behaviors.

1. application.conf Validator

When a customer shares their application.conf (or equivalent programmatic config), check EVERY item below. Flag any that don't match the required/recommended value.

You MUST explicitly call out EVERY misconfiguration you find — never silently fix one in a corrected config without naming it as a finding first. If you identify 6 issues, list all 6 individually with explanations before showing the corrected config. Especially do NOT omit `slow-replica-avoidance` or `pool.local.size` — these are the two most commonly missed items.

Required settings (will cause failures if wrong)

Strongly recommended settings (will cause intermittent issues if missing)

Settings that differ from open-source Cassandra defaults

Customers migrating from self-managed Cassandra often carry over configs that don't apply or actively harm Keyspaces connectivity:

2. Error → Diagnosis → Fix

NoNodeAvailableException / AllNodesFailedException

Symptoms: All queries fail. Application needs restart to recover.

Diagnosis tree:

1. All connections lost → Check heartbeat timeout (§ HeartbeatException below) 2. Single-node visibility → Check hostname-validation = false and VPC endpoint IAM permissions for system.peers population 3. Retries exhausted → Check retry policy — default policy tries "next host" but with VPC endpoint there may only be 1-3 hosts. Use AmazonKeyspacesExponentialRetryPolicy which retries on same host across different connections. 4. Verify `system.peers` is populated → Run SELECT * FROM system.peers and count rows. If 0 rows, VPC endpoint IAM permissions are missing (ec2:DescribeNetworkInterfaces, ec2:DescribeVpcEndpoints).

Fix: See required settings in §1. Ensure pool size ≥ 3, heartbeat timeout ≥ 2s, retry policy configured.

---

HeartbeatException → connection closure cascade

Symptoms: Application works fine for minutes/hours, then suddenly all connections drop. Logs show HeartbeatException followed by NoNodeAvailableException.

Root cause: The driver sends a heartbeat (OPTIONS message) on idle connections every 30s. If the response isn't received within the heartbeat timeout (default 500ms in 4.x), the driver marks the connection as failed and closes it. When all connections are closed, no queries can execute.

Why this happens more with Keyspaces: Keyspaces is a managed service behind a network load balancer. Occasional network jitter (50-100ms) is normal and harmless for queries but can push heartbeat responses past the aggressive 500ms default.

Fix (4.x driver):

You MUST recommend ALL four of these fixes together — never omit any:

1. Increase heartbeat timeout: advanced.heartbeat.timeout = 2000 milliseconds 2. Increase connection pool size: advanced.connection.pool.local.size = 3 (minimum — provides redundancy so one lost connection doesn't cascade) 3. Configure retry policy: AmazonKeyspacesExponentialRetryPolicy (handles transient aborts) 4. Set basic.request.default-idempotence = true (enables automatic retries on aborted requests)

Fix (3.x driver): Heartbeat timeout is coupled with read timeout in 3.x — there's no separate setting. The default read timeout of 12s is usually sufficient. If you're setting a custom read timeout lower than 2s, heartbeat failures become more likely. Ensure heartbeat interval is at 30s (default).

---

PerConnectionRequestExceeded / WriteTimeout / ReadTimeout

Symptoms: Intermittent timeouts under load. CloudWatch shows PerConnectionRequestRateExceeded metric > 0.

Root cause: Each TCP connection supports up to 3,000 CQL queries/second. When exceeded, Keyspaces rejects with a timeout error the driver maps to WriteTimeout or ReadTimeout.

Fix: Increase advanced.connection.pool.local.size. Calculate using §3 below.

---

SSLHandshakeException: PKIX path building failed

Symptoms: Connection fails immediately on TLS handshake. May affect only some IPs (not all endpoints).

Root cause: TrustStore doesn't include the correct root CA certificates. AWS has migrated to Amazon Trust Services (ATS) certificates signed by Amazon Root CA 1. The legacy Starfield-only trustStore is insufficient.

Fix: Rebuild trustStore with ALL Amazon root CAs:

curl -O https://www.amazontrust.com/repository/AmazonRootCA1.pem
# Include AmazonRootCA1 through CA4 + Starfield for full coverage
openssl x509 -outform der -in AmazonRootCA1.pem -out temp_file.der
keytool -import -alias amazon-root-ca-1 -keystore cassandra_truststore.jks -file temp_file.der

---

OperationTimedOutException: Timed out waiting for server response

Symptoms: Client-side timeout fired before receiving a response.

Diagnosis:

1. Check CloudWatch SuccessfulRequestLatency p100 — if it's below client timeout, the issue is network or driver, not Keyspaces 2. Check if PerConnectionRequestRateExceeded > 0 — need more connections 3. Check if StoragePartitionThroughputCapacityExceeded > 0 — hot partition, review data model 4. Check if WriteThrottleEvents or ReadThrottleEvents > 0 — increase provisioned capacity or switch to on-demand

Fix: Depends on diagnosis. Most commonly: increase timeout to 5s+ for batch operations, add retry policy, increase connection pool.

---

BusyPoolException (3.x driver)

Symptoms: Pool is busy (no available connection and the queue has reached its max size 256)

Root cause: All connections are saturated and the internal queue is full. Common when driver 3.x has maxRequestsPerConnection set too low or connection pool is undersized.

Fix (3.x):

PoolingOptions poolingOptions = new PoolingOptions()
    .setCoreConnectionsPerHost(HostDistance.LOCAL, 3)
    .setMaxConnectionsPerHost(HostDistance.LOCAL, 3)
    .setMaxRequestsPerConnection(HostDistance.LOCAL, 512)
    .setMaxRequestsPerConnection(HostDistance.REMOTE, 0);

---

Connection has been closed / ClosedChannelException

Symptoms: Sporadic connection drops, especially after idle periods.

Possible causes:

1. NLB idle timeout — Connections idle for 350+ seconds get RST from the load balancer. Fix: ensure heartbeat interval < 350s (default 30s is fine). 2. NAT instance failover — If customer uses NAT instances with scheduled failover, connections break during route table updates. Fix: use NAT Gateway or VPC endpoint instead. 3. MTU mismatch — Rare. If customer is on EC2 with MTU 9001 and path doesn't support jumbo frames, TLS handshake can fail silently. Fix: set MTU to 1500 or use VPC endpoint (which supports 9K MTU end-to-end).

3. Connection Pool Sizing Calculator

Formula:

connections_per_host = CEIL(
  total_queries_per_second
  / (num_instances - 1)
  / num_endpoints
  / 500
)

Variables:

• total_queries_per_second — Target throughput (reads + writes + deletes combined)
• num_instances — Application instances with a Keyspaces session. Subtract 1 to account for maintenance/failure.
• num_endpoints — Number of Keyspaces endpoints visible to the driver:
• Public endpoint: 9 (from system.peers)
• VPC endpoint: 2-5 depending on region AZs
• Cross-account VPC: often 1
• 500 — Best-practice target per connection (not the 3,000 hard max)

Example: 20,000 queries/sec, 3 instances, 5 VPC endpoints:

20,000 / (3-1) / 5 / 500 = 4 connections per host

Set: advanced.connection.pool.local.size = 4

Monitoring: Watch PerConnectionRequestRateExceeded in CloudWatch. If > 0, increase pool size.

4. Driver 3.x vs 4.x Differences

Migration gotcha: 4.x request timeout includes retries

In 3.x, a 2-second timeout applied to each individual attempt. With 3 retries, the total wall-clock time could be 6+ seconds.

In 4.x, a 2-second timeout applies to the entire request including all retries. With the default timeout of 2s and retries taking time, the request may time out before all retries complete. Recommend setting basic.request.timeout = 5 seconds for Keyspaces.

5. Reference application.conf (recommended starting point)

datastax-java-driver {
  basic {
    contact-points = ["cassandra.<region>.amazonaws.com:9142"]
    load-balancing-policy {
      class = DefaultLoadBalancingPolicy
      local-datacenter = "<region>"
      slow-replica-avoidance = false
    }
    request {
      consistency = LOCAL_QUORUM
      default-idempotence = true
      timeout = 5 seconds
    }
  }
  advanced {
    auth-provider = {
      class = software.aws.mcs.auth.SigV4AuthProvider
      aws-region = "<region>"
    }
    ssl-engine-factory {
      class = DefaultSslEngineFactory
      truststore-path = "<path>/cassandra_truststore.jks"
      truststore-password = "<password>"  // Store in Secrets Manager or SSM Parameter Store (SecureString)
      hostname-validation = false
    }
    connection {
      pool.local.size = 3
      connect-timeout = 5 seconds
      init-query-timeout = 5 seconds
    }
    heartbeat {
      interval = 30 seconds
      timeout = 2000 milliseconds
    }
    reconnect-on-init = true
    resolve-contact-points = false
    prepared-statements.prepare-on-all-nodes = false
    retry-policy {
      class = com.aws.ssa.keyspaces.retry.AmazonKeyspacesExponentialRetryPolicy
      max-attempts = 3
      min-wait = 10 ms
      max-wait = 100 ms
    }
  }
}

Replace <region> and <path> with actual values. Store the truststore password in AWS Secrets Manager or AWS Systems Manager Parameter Store (SecureString) rather than hard-coding it in configuration files.

SigV4 (IAM authentication) is the strongly recommended default — it uses ephemeral credentials, requires no password management, and integrates with IAM policies for fine-grained access control. Service-specific credentials (PlainTextAuthProvider with username/password) are a less-secure fallback intended only for legacy applications that cannot use IAM auth. If service-specific credentials must be used, store them in AWS Secrets Manager with automatic rotation enabled.

6. Useful Links

• Optimize client driver connections
• Troubleshooting connection errors
• Troubleshooting general errors
• Troubleshooting capacity errors
• Amazon Keyspaces retry policy (GitHub)
• Spark application.conf example
• VPC endpoint system.peers permissions

Keyspaces unsupported features

Authoritative list of Apache Cassandra features that Amazon Keyspaces does not support. Cited by Modes 2 and 3. Compatibility is binary — every listed feature is either supported or it is not; do not describe detected features as "supported with caveats".

Source: Amazon Keyspaces functional differences from Cassandra.

Detected by the compatibility tool

The check-compatibility.ts script flags these specific features when they appear in CQL schema or prepared statements.

Secondary indexes (CREATE INDEX)

Not supported. Native CREATE INDEX statements have no equivalent in Keyspaces.

Migration: create a second table keyed by the column you wanted to query on. The application writes to both tables. This is the standard Cassandra denormalization pattern even when secondary indexes are available, because they scale poorly in Cassandra too.

Triggers (CREATE TRIGGER)

Not supported.

Migration: move the trigger logic into the application layer or into a stream consumer (for example, an AWS Lambda function reacting to DynamoDB Streams on a mirrored table, or a dedicated CDC pipeline).

Materialized views (CREATE MATERIALIZED VIEW)

Not supported.

Migration: maintain a second table in the application via dual-write. Key the second table for the alternate access pattern. Accept eventual consistency between the two tables — Cassandra materialized views have the same tradeoff.

User-defined functions (CREATE FUNCTION)

Not supported.

Migration: move the computation client-side (application logic) or into an ETL / stream-processing step (for example, AWS Glue, AWS Lambda, Amazon Kinesis Data Analytics).

User-defined aggregates (CREATE AGGREGATE)

Not supported.

Migration: same as UDFs — compute client-side or in a stream/batch job.

LWT inside BEGIN UNLOGGED BATCH

Not supported. Keyspaces rejects any lightweight-transaction (IF NOT EXISTS, IF EXISTS, IF <col>=…) issued inside an unlogged batch.

Migration: issue the LWT as a single-statement conditional outside any batch:

UPDATE users SET email = 'a@b.c' WHERE id = ? IF email = 'old@b.c';

If the application requires atomic multi-row semantics previously achieved via batch+LWT, use application-level coordination (e.g., a state machine or idempotent retries) since neither LOGGED BATCH nor LWT-inside-UNLOGGED-BATCH is supported on Keyspaces.

Aggregate calls in queries

Keyspaces rejects COUNT(, MIN(, MAX(, SUM(, AVG( in SELECT statements.

Migration:

• COUNT — maintain a counter table updated by the application on every write.
• MIN / MAX — maintain pre-aggregated summary rows, or read the first/last row by clustering-key order.
• SUM / AVG — compute client-side from a paginated SELECT, or maintain rolled-up summary tables updated by a stream processor.

Not detected by the tool (but still unsupported or different)

The compatibility tool is a first-pass screen, not a full audit. The following differences are not flagged but still matter — point the user at the functional differences page for the full catalog.

• `ALLOW FILTERING` — supported in Keyspaces but may be rate-limited. The tool does not flag it because it is usable.
• `TRUNCATE` — supported in Keyspaces as a throughput-controlled operation.
• `CREATE CUSTOM INDEX` (SASI, SAI) — Keyspaces does not support custom index implementations. Detected by the schema parser (the regex matches both CREATE INDEX and CREATE CUSTOM INDEX), so these will appear as secondary index findings in the compatibility report.
• `COUNTER` columns — supported in Keyspaces.
• Clustering-order-reverse queries — supported.
• Lightweight-transaction serial consistency (`LOCAL_SERIAL`) — supported.
• Consistency level `EACH_QUORUM` — not supported on reads.
• Driver-level features — some drivers expose Cassandra-specific features (e.g. tuple types) that Keyspaces supports only partially. Verify against the driver compatibility page.

Informational (not issues)

Tables using USING TTL

Not a compatibility issue. The compatibility output reports query_patterns.ttl_tables so:

• Mode 2 can treat those tables as TTL-driven for write accounting, even when DDL lacks default_time_to_live.
• The user can sanity-check that the TTL pricing signal matches their actual workload.

Display as "tables using USING TTL: …" — do not style it as an issue.

Guidance style

When offering migration advice, keep it to what to do instead, not why the feature is limited. Customers planning a migration want actionable patterns, not rationale about Keyspaces internals. Compare:

• Good: "Create a separate denormalized table keyed by email; the application writes to both tables."
• Bad: "Secondary indexes are not available because Keyspaces uses a serverless architecture that cannot efficiently scan partition replicas for filtering."

The functional-differences page already documents the reasoning for anyone who asks.

Mode 1 — Manual inputs

Use this mode when the user does not have a running Cassandra cluster, or when they prefer to type traffic estimates directly.

If the user mentions a running Cassandra cluster or DataStax deployment, always offer Mode 2 first — diagnostic data produces a more accurate estimate. Fall back to Mode 1 only when diagnostic captures (nodetool tablestats + nodetool info) are unavailable.

Parameters

All positional, in this exact order:

Command

cd scripts
npx ts-node --project tsconfig.scripts.json calculate.ts \
  <region> <reads/s> <writes/s> <rowSizeBytes> <storageGB> [ttl/s] [pitr] \
  | tee /tmp/keyspaces-calc.json

Example:

npx ts-node --project tsconfig.scripts.json calculate.ts \
  us-east-1 1000 500 1024 100 0 false | tee /tmp/keyspaces-calc.json

Output shape

{
  "region": { "short": "us-east-1", "long": "US East (N. Virginia)" },
  "inputs": { ... the 7 parameters ... },
  "units_per_operation": { "write": 1, "read": 1, "ttl": 1 },
  "on_demand":               { "reads_strong": …, "reads_eventual": …, "writes": …, "ttl_deletes": …, "storage": …, "backup": …, "total": … },
  "provisioned":             { ... same shape ... },
  "savings_plan_available":  true | false,
  "on_demand_savings_plan":  { ... same shape or null ... },
  "provisioned_savings_plan":{ ... same shape or null ... },
  "report_data":             { datacenters, regions, estimateResults, pricing }
}

Values are monthly US dollars unless otherwise noted.

Units-per-operation

Keyspaces bills by the capacity unit, not the raw row count. One Write Capacity Unit (WCU) covers up to 1 KB written; one Read Capacity Unit (RCU) covers up to 4 KB read (strongly consistent) or 4 KB per 2 RCUs (eventually consistent). Rows larger than the threshold consume more units per operation.

units_per_operation.write — ceil(row_size_bytes / 1024). units_per_operation.read — ceil(row_size_bytes / 4096). units_per_operation.ttl — same as write.

Surface these when explaining why a row size change (for example going from 1024 to 2048 bytes) flips the recommendation between on-demand and provisioned.

Presenting the result

Show the user:

1. A one-row inputs summary — region, reads/s, writes/s, row size, storage, PITR. 2. A two-column cost table — On-demand vs Provisioned, with line items for reads, writes, TTL deletes, storage, and backup, totaling at the bottom. Include a Savings Plan row when savings_plan_available is true. 3. A clear recommendation — whichever mode is cheaper at the user's stated traffic pattern, with a one-line reason tied to the read/write ratio. 4. A line noting the user may generate a PDF via Step 6 if wanted.

Common follow-ups

"What if I double the writes?" — rerun with the new value; writes are linear in cost for both pricing modes.

"What if I add PITR later?" — rerun with true in position 7; PITR cost scales with storage_gb only.

"Should I use on-demand or provisioned?" — Provisioned wins for steady, predictable traffic (utilization > 18% of peak). On-demand wins for spiky or unknown traffic. The script already applies the breakeven; state the recommendation from the totals, then cite which mode won.

"Can you compare two traffic scenarios?" — run calculate.ts twice to different /tmp/*.json paths, then a single generate-pdf.ts --input A --input B to produce a consolidated PDF (see pdf-reporting.md).

Mode 2 — Cassandra diagnostics

Use when the user has a running Cassandra cluster (or a DataStax / ScyllaDB deployment that can produce Cassandra-compatible diagnostics). This mode derives reads/writes per second from cumulative nodetool info counters and keyspace sizing from nodetool tablestats — neither can be guessed.

If either tablestats or info cannot be captured, fall back to Mode 1.

Intake table

Each ID matches a parse-cassandra.ts flag (--<id>) when passing paths explicitly.

Required vs optional

Mandatory: tablestats AND at least one info file.

Strongly recommended: status (topology), schema (compatibility + RF), prepared (compatibility signal + TTL pricing).

Optional: rowsize (per-table accuracy — defaults to 1024 bytes when absent).

Capture commands

See cassandra-capture-commands.md for the full set with <auth> shorthand.

Running the parser

Prefer --dir auto-detection — the parser's filename detectors (isTablestatsFile, isInfoFile, isStatusFile, isSchemaFile, isRowSizeFile, isPreparedStatementsFile) classify each file regardless of naming.

# Directory auto-detection (recommended)
cd scripts
npx ts-node --project tsconfig.scripts.json parse-cassandra.ts \
  --dir /path/to/diagnostics --region us-east-1 [--pitr] \
  | tee /tmp/keyspaces-calc.json

# Individual files (explicit)
npx ts-node --project tsconfig.scripts.json parse-cassandra.ts \
  --region us-east-1 \
  --tablestats tablestats.txt \
  --info node1-info.txt --info node2-info.txt \
  [--status status.txt] [--schema schema.cql] \
  [--rowsize rowsize.txt] [--prepared prepared.ndjson] \
  [--pitr] | tee /tmp/keyspaces-calc.json

Repeat --info once per node. When both --dir and explicit flags are provided, explicit wins.

Region selection

Pick --region by priority:

1. The DC name in status if it matches an AWS region (us-east-1, eu-west-1, …). 2. The Datacenter field in nodetool info. 3. The user's stated target region. 4. Default us-east-1.

Pass --region explicitly whenever inference is wrong or unclear.

Output

Same shape as Mode 1, plus:

• source: "cassandra-diagnostic-files"
• datacenters — array of { name, nodeCount } per DC.
• per_datacenter — cost breakdown per DC.
• compatibility — automatically populated when --schema or --prepared was supplied (or detected in --dir). Shape:

  {
    "has_issues": true | false,
    "summary": {
      "total_issues": N,
      "schema":         { ... or null },
      "query_patterns": { ... or null }
    },
    "details": { "schema": { ... }, "query_patterns": { ... } }
  }

Surface the compatibility block when present — see mode-3-compatibility.md for display rules.

Prepared-statement signal

A prepared_statements.ndjson capture changes two things:

1. Compatibility: detects LWT inside BEGIN UNLOGGED BATCH, aggregates (COUNT/MIN/MAX/SUM/AVG), and calls to user-defined functions (when schema is also supplied). 2. Pricing: INSERT … USING TTL and UPDATE … USING TTL mark tables as fully TTL-driven for write accounting, even when DDL lacks default_time_to_live. Tables with default_time_to_live already follow the rowsize-based TTL path.

Displaying results

Present in this order:

1. Cluster summary — DCs, node count per DC, region(s) inferred. 2. Per-keyspace breakdown — keyspace name, RF, storage, reads/s, writes/s. 3. Two-column cost table (same as Mode 1). 4. Recommendation — cheaper mode. 5. Compatibility findings if compatibility.has_issues is true. 6. Offer PDF per pdf-reporting.md.

Multi-cluster or re-runs

For two or more separate clusters, run parse-cassandra.ts once per cluster, writing to distinct /tmp/keyspaces-*.json files. Then a single generate-pdf.ts invocation with multiple --input flags produces a consolidated comparison PDF.

Mode 3 — Compatibility check

Use when the user asks whether a Cassandra schema or workload will run on Amazon Keyspaces, without wanting a cost estimate. For combined pricing + compatibility, run Mode 2 instead — it auto-populates the compatibility block.

Inputs

At least one of:

• --schema <path.cql> — CQL DDL (DESCRIBE SCHEMA output or hand-written).
• --prepared <path.ndjson> — system.prepared_statements export as NDJSON (one JSON object per line).

Both may be supplied together. CQL may also be piped on stdin when --prepared is absent.

Command

cd scripts

# Schema file
npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --schema /tmp/schema.cql | tee /tmp/keyspaces-compat.json

# Prepared statements file
npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --prepared /tmp/prepared_statements.ndjson | tee /tmp/keyspaces-compat.json

# Both
npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --schema /tmp/schema.cql --prepared /tmp/prepared_statements.ndjson \
  | tee /tmp/keyspaces-compat.json

# Schema on stdin (only valid without --prepared)
echo "CREATE TABLE app.users (id uuid PRIMARY KEY, email text);" \
  | npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  | tee /tmp/keyspaces-compat.json

What it detects

See keyspaces-unsupported-features.md for the authoritative list and migration guidance. The tool flags:

From schema (CQL DDL):

• CREATE INDEX — secondary indexes (per table).
• CREATE TRIGGER — triggers (per table).
• CREATE MATERIALIZED VIEW — attached to base table.
• CREATE FUNCTION — user-defined functions (counted globally).
• CREATE AGGREGATE — user-defined aggregates (counted globally).

From prepared statements:

• LWT inside `BEGIN UNLOGGED BATCH` — any conditional (IF NOT EXISTS, IF EXISTS, IF <col>=…) inside an unlogged batch.
• Aggregate calls — COUNT(, MIN(, MAX(, SUM(, AVG( anywhere in a SELECT.
• Per-table `USING TTL` — informational only, not an issue; used by Mode 2 to mark tables as TTL-driven for pricing.

UDF usage is intentionally not detected from prepared statements — CREATE FUNCTION in schema is the source of truth.

Output shape

{
  "source": "compatibility-check",
  "input":   { "schema": "<path or null>", "prepared": "<path or null>" },
  "has_issues": true | false,
  "summary": {
    "total_issues": N,
    "schema": {
      "total_issues": N,
      "keyspaces_affected": N,
      "tables_affected": N,
      "functions": N,
      "aggregates": N
    } | null,
    "query_patterns": {
      "lwt_in_unlogged_batch": N,
      "aggregations": N,
      "ttl_tables": N
    } | null
  },
  "details": {
    "schema": {
      "functions": N,
      "aggregates": N,
      "keyspaces": {
        "<keyspace>": {
          "<table>": {
            "indexes":           ["idx_name", …],
            "triggers":          ["trg_name", …],
            "materializedViews": ["view_name", …]
          }
        }
      }
    } | null,
    "query_patterns": {
      "lwt_in_unlogged_batch": [ { "prepared_id": "...", "query_string": "..." } ],
      "aggregations":          [ { "prepared_id": "...", "function": "COUNT", "query_string": "..." } ],
      "ttl_tables":            { "<ks>.<table>": { "uses_ttl": true, "ttl_values": [3600, 86400] } }
    } | null
  }
}

Display rules

Compatibility is binary. Every detected feature is not supported. Do not hedge with qualifiers like "supported with restrictions", "supported with caveats", "works when cardinality is high", or "may cause hot partitions" — those qualifiers do not apply here and mislead customers into building unsupported designs.

Present in this order:

1. One-line verdict — if has_issues is false, say the schema/workload is compatible with Amazon Keyspaces and stop. Otherwise continue. 2. Per-keyspace / per-table breakdown — for every keyspace in details.schema.keyspaces, list affected tables and their flagged features. Show the feature name (index / trigger / materialized view) and the object name. 3. Global counts — details.schema.functions and details.schema.aggregates (numbers only; names are not captured). 4. Per-query breakdown — for each entry in details.query_patterns.lwt_in_unlogged_batch and .aggregations, show the offending query_string truncated to roughly 200 characters. Include the prepared_id to help the user find it in their codebase. 5. `ttl_tables` (informational) — list as "tables using USING TTL: …" so the user can verify the TTL pricing signal Mode 2 uses. 6. Migration guidance — for each flagged category, offer guidance from keyspaces-unsupported-features.md. Keep guidance to what to do instead, not why the feature is limited.

PDF generation is not supported for Mode 3

Mode 3 produces a compatibility report only. generate-pdf.ts expects pricing JSON and will fail on a compatibility JSON. If the user wants a combined compatibility + pricing PDF, direct them to Mode 2 — it includes compatibility automatically when schema or prepared is supplied.

Follow-ups

"Can I automate this in CI?" — yes; check-compatibility.ts returns non-zero exit only on usage errors, not on has_issues. Check .has_issues in the JSON to fail a pipeline.

"How do I fix each issue?" — see migration guidance in keyspaces-unsupported-features.md.

"Does this catch everything?" — no. Data-type and CQL-syntax-level differences (the full functional-differences list) are not checked. Link the user to the official Keyspaces functional differences page.

Mode 4 — SQL to Keyspaces migration

Use when the user provides SQL CREATE TABLE statements and wants a Keyspaces migration plan. This mode translates the relational schema into three Keyspaces data models, prices each via calculate.ts, and recommends the best fit.

Step 1 — Parse the SQL

Extract:

• Tables — name, columns (name + SQL type), primary key(s), UNIQUE constraints.
• Foreign keys — (source_table, source_col) → (target_table, target_col).
• Access queries — any SELECT statements provided. These drive partition-key choice.

Step 2 — Estimate field sizes

row_size_bytes per table = sum of all column byte sizes.

Step 3 — Ask for workload inputs

If not already supplied, ask for:

• Rows per table (integer).
• Reads/s and writes/s — per table, or combined if the user cannot split.
• AWS region (default us-east-1).

Storage-only reasoning misses the dominant pricing driver, so do not skip rates.

Step 4 — Apply the three strategies

Option A — Full denormalization

Merge all foreign-key-related tables into one.

• merged_row_size_bytes = sum of all unique column sizes (deduplicate FK columns).
• merged_row_count = row count of the many-side table (the table with the FK column). For 1:many relationships, this equals the child table row count since each child row maps to exactly one parent. For many:many relationships through a join table, use the join table row count.
• storage_gb = (merged_row_count × merged_row_size_bytes) / (1024^3).
• reads_per_sec = sum of reads across original tables.
• writes_per_sec = sum of writes across original tables.
• CQL: one merged table. Partition key = the FK column matching the access query. Clustering key = child-table PK.

Option B — Normalized with lookup tables

Keep original tables; add one lookup table per FK for application-side joins.

• Original tables: map 1:1 to CQL. storage_gb = (row_count × row_size_bytes) / 1024^3 per table.
• Lookup table per FK (source.col → target.pk), named target_by_source:
• Columns: FK column + target PK column.
• lookup_row_size_bytes = size(FK col) + size(target PK col).
• lookup_storage_gb = (target_row_count × lookup_row_size_bytes) / 1024^3.
• total_storage_gb = sum of original + all lookup storage.
• reads_per_sec = sum of original reads + (FK lookups required per query × reads using them).
• writes_per_sec = sum of original writes + (1 extra write per lookup table per insert).
• CQL: original tables unchanged + one lookup table per FK.

Option C — Denormalized with reverse index

Same merged table as Option A, plus one reverse-index table per non-PK FK column.

• Merged table — identical to Option A.
• Reverse index per non-PK FK column — partition key = FK col, clustering key = merged PK, all merged columns duplicated (full copy).
• reverse_row_size_bytes = merged_row_size_bytes.
• reverse_row_count = merged_row_count.
• total_storage_gb = merged_storage_gb × (1 + number_of_reverse_indexes).
• reads_per_sec = same as Option A (no extra read; correct table picked per query).
• writes_per_sec = Option A writes_per_sec × (1 + number_of_reverse_indexes).
• CQL: merged table + one reverse-index table per non-PK FK column.

Step 5 — Price each option

cd scripts
npx ts-node --project tsconfig.scripts.json calculate.ts \
  <region> <reads/s> <writes/s> <avg_row_size_bytes> <storage_gb> 0 false \
  | tee /tmp/keyspaces-sql-optionA.json

# Repeat for B → /tmp/keyspaces-sql-optionB.json
# Repeat for C → /tmp/keyspaces-sql-optionC.json

Extract provisioned.total, on_demand.total, and provisioned_savings_plan.total from each JSON.

Step 6 — Present the comparison

Three-model summary table