Migration Guide

Move from Apache Cassandra to Ferrosa with the same CQL protocol, the same drivers, and the same LWT semantics. Most core application paths migrate without code changes; a small set of features — GROUP BY, PER PARTITION LIMIT, Java UDFs, and server-push schema events — require changes described below.

Migration Overview

Ferrosa is designed for Cassandra-compatible protocol access where supported, with migrations validated incrementally against your schema, drivers, and workload. The migration strategy is incremental:

1. Start a Ferrosa node alongside your existing Cassandra cluster
2. Point a test workload at Ferrosa to validate compatibility
3. Import existing SSTables directly (Ferrosa reads Cassandra BTI format)
4. For migration evaluations, move keyspaces one at a time with dual-read verification
5. Decommission Cassandra nodes as Ferrosa proves stable

What's Compatible

Step-by-Step Migration

# Export schema from Cassandra
cqlsh -e "DESCRIBE SCHEMA" > schema.cql

# Check for unsupported features
grep -iE "MATERIALIZED VIEW|GROUP BY|PER PARTITION LIMIT|LANGUAGE (java|javascript)" schema.cql

# Build and start
cargo build --release
FERROSA_CQL_BIND=0.0.0.0:9042 \
FERROSA_AUTH_DISABLED=true \
./target/release/ferrosa

# Apply schema to Ferrosa
cqlsh ferrosa-host 9042 -f schema.cql

# Option A: CQL COPY (simple, works for moderate datasets)
# Export from Cassandra
cqlsh cassandra-host -e "COPY social.users TO '/tmp/users.csv'"

# Import to Ferrosa
cqlsh ferrosa-host -e "COPY social.users FROM '/tmp/users.csv'"

# Option B: SSTable import (see SSTable Import section below)

# Your application code — just change the host
# Before:
# cluster = Cluster(['cassandra-node-1.prod'])

# After:
cluster = Cluster(['ferrosa-node-1.prod'])

SSTable Import

Ferrosa's ferrosa-sstable crate reads Cassandra BTI (Big Trie-Indexed) SSTables natively — the default format in Cassandra 5.x. This means you can import existing SSTable files directly without an intermediate conversion step.

What Ferrosa reads

A BTI SSTable consists of 7 component files:

• *-Data.db — row data
• *-Partitions.db — partition index (on-disk trie)
• *-Rows.db — row-level index
• *-Filter.db — Bloom filter
• *-CompressionInfo.db — compression metadata
• *-Statistics.db — SSTable statistics
• *-TOC.txt — table of contents

Copy these files from your Cassandra data directory to Ferrosa's data directory, organized by keyspace and table. Ferrosa will pick them up on next read.

Compression support

Ferrosa supports LZ4 and Zstd compressed SSTables. No decompression step needed — compressed SSTables are read directly.

Dual-Read Verification

Before considering any production cutover, run dual reads against both databases and compare results:

from cassandra.cluster import Cluster

# Connect to both
cass = Cluster(['cassandra-host']).connect('social')
ferro = Cluster(['ferrosa-host']).connect('social')

# Compare results
query = "SELECT * FROM users WHERE user_id = ?"
stmt_c = cass.prepare(query)
stmt_f = ferro.prepare(query)

for uid in sample_user_ids:
    row_c = cass.execute(stmt_c, [uid]).one()
    row_f = ferro.execute(stmt_f, [uid]).one()
    assert row_c == row_f, f"Mismatch for {uid}"

Run this against a representative sample of your real queries. Cover:

• Point reads by partition key
• Range scans on clustering columns
• Collection types (list, set, map)
• Prepared statements with bind variables
• Batch operations
• Lightweight transactions (INSERT IF NOT EXISTS, UPDATE IF)

S3 Storage Setup

For production-style evaluations, configure S3 or an S3-compatible service as the durable storage backend. Local disk acts as a hot cache.

# AWS S3 with IAM instance profile (no explicit keys needed)
FERROSA_S3_ENDPOINT=https://s3.amazonaws.com \
FERROSA_S3_BUCKET=my-ferrosa-data \
FERROSA_S3_REGION=us-east-1 \
FERROSA_DATA_DIR=/var/lib/ferrosa \
./target/release/ferrosa

# MinIO for local development
FERROSA_S3_ENDPOINT=http://localhost:9000 \
FERROSA_S3_BUCKET=ferrosa \
FERROSA_S3_ACCESS_KEY_ID=minioadmin \
FERROSA_S3_SECRET_ACCESS_KEY=minioadmin \
FERROSA_S3_ALLOW_HTTP=true \
./target/release/ferrosa

S3-compatible providers

Ferrosa works with any S3-compatible object store. Set FERROSA_S3_ENDPOINT for non-AWS providers:

Storage cost comparison

With S3-backed storage, you trade some local disk and snapshot costs for object storage, request costs, lifecycle policy, and restore behavior. The table below is illustrative only; benchmark and price your own workload before making migration decisions:

S3 request costs (GET/PUT), restore latency, and cache misses matter for high-throughput workloads. The local NVMe cache is intended to absorb hot reads, and write-behind uploads batch SSTables to amortize PUT costs, but the preview docs should be treated as a model to validate rather than a guaranteed cost outcome.

Key Differences from Cassandra

LWT & Transaction Migration

Lightweight transactions

Ferrosa fully supports Cassandra's lightweight transaction (LWT) syntax. Your existing LWT queries work without modification:

• INSERT ... IF NOT EXISTS — conditional inserts
• UPDATE ... IF condition — compare-and-set updates
• DELETE ... IF EXISTS / DELETE ... IF condition — conditional deletes
• Batch CAS — BEGIN BATCH with IF conditions across statements
• SERIAL and LOCAL_SERIAL consistency levels

Under the hood, Ferrosa uses the Accord consensus protocol instead of Paxos. This is transparent to your application — the CQL syntax and semantics are identical. Accord provides strict serializability with better performance characteristics: 1-RTT fast path via leaseholder, compared to Paxos's minimum 2-RTT.

Beyond LWT: multi-statement transactions

Ferrosa also supports explicit multi-statement transactions for operations that go beyond what LWT can express:

-- Atomic multi-partition operation
BEGIN TRANSACTION
  UPDATE accounts SET balance = balance - 100
    WHERE id = 'acct-1' IF balance >= 100;
  UPDATE accounts SET balance = balance + 100
    WHERE id = 'acct-2';
COMMIT TRANSACTION;

This is a Ferrosa extension — not available in Apache Cassandra. Use it for new functionality after migration, or to replace application-level two-phase patterns.

Rollback Plan

If you need to roll back to Cassandra:

1. Keep Cassandra running during the migration period — don't decommission until you're confident
2. Your application code is unchanged — rolling back is just changing the contact point back to Cassandra
3. Export data from Ferrosa using cqlsh COPY if you need to sync writes that went only to Ferrosa
4. No schema changes needed — your schema is the same on both systems