Migration Guide

Move from Apache Cassandra to Ferrosa without rewriting application code. Same CQL protocol, same drivers, same consistency model.

Migration Overview

Ferrosa is designed as a drop-in replacement for Apache Cassandra at the protocol level. 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. Migrate production 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 -i "MATERIALIZED VIEW\|CREATE FUNCTION" 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 cutting over production traffic, 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 production queries. Cover:

• Point reads by partition key
• Range scans on clustering columns
• Collection types (list, set, map)
• Prepared statements with bind variables
• Batch operations

S3 Storage Setup

For production, configure S3 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 local disk costs for object storage costs — typically a 4-10x reduction:

S3 request costs (GET/PUT) add overhead for high-throughput workloads, but the local NVMe cache absorbs most read traffic. Write-behind uploads batch SSTables to amortize PUT costs.

Key Differences from Cassandra

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