Ferrosa

A Rust reimplementation of Apache Cassandra with S3-backed storage.

Ferrosa is a developer-preview distributed database that targets the Cassandra CQL client surface. The current implementation supports a useful subset of CQL and common driver workflows, but it is not yet a drop-in Cassandra replacement. Under the hood, it replaces Cassandra's local-disk storage model with a write-behind architecture where ephemeral local storage serves as a fast cache and S3-compatible object storage provides durability.

Status: Developer Preview. Ferrosa is under active development. APIs, on-disk formats, and configuration may change before a stable 1.0. Don't run it on data you can't lose. Please report issues — we want to hear them.

Community and support

Join the Ferrosa Discord to discuss deployments, ask questions, and report issues with the community and maintainers.

Quick Install

curl -fsSL https://ferrosadb.com/install.sh | bash

The installer detects your platform (macOS arm64/x86_64, Linux x86_64/aarch64), downloads the latest release into ~/.ferrosa/bin/, writes a default config to ~/.ferrosa/config/, and offers to register a launchctl/systemd unit and set CQL admin credentials.

To build from source instead, see Building below.

Why Ferrosa?

Apache Cassandra is a proven distributed database based on the Amazon Dynamo paper. It works well, but carries decades of accumulated complexity: non-idiomatic Java for performance reasons, tightly coupled subsystems, and a storage engine designed around assumptions (cheap local disk, persistent nodes) that don't match cloud-native infrastructure.

Ferrosa starts from a deep analysis of Cassandra's architecture — understanding what it does, what's essential, and what's accidental complexity — then builds a clean Rust implementation that takes advantage of modern hardware and cloud infrastructure.

Design Principles

• S3 as the source of truth. Nodes are ephemeral. SSTables live in object storage. A new node can serve reads within seconds by fetching from S3, not hours of streaming.
• CQL compatibility target. Ferrosa speaks CQL native protocol v3/v4 as the default, well-tested driver surface. v5 is accepted for explicit conformance testing and is being hardened for production driver use; see ferrosa-cql/specs/roadmap.md for remaining v5 work. v6+ is rejected. Ferrosa aims for wire-compatible behavior with Apache Cassandra 3.x/4.x/5.x drivers.
• Rust-native, not a transliteration. Ferrosa is built as idiomatic Rust with clean ownership boundaries, not a line-by-line port of Java code.
• Cassandra-shaped consistency model. Tunable consistency levels (ONE, QUORUM, ALL) are implemented in the storage/cluster stack and still require broader live-cluster verification before production claims.
• Independent crates. Each subsystem is a standalone Rust crate with its own tests and documentation. ferrosa-sstable can read Cassandra SSTables and is useful on its own for migration tooling.

Architecture

graph TB
    subgraph Clients
        D1[CQL Drivers]
        D2[cqlsh]
        D3[ferrosa-ctl<br/>CLI + TUI Monitor]
        D4[Graph Clients<br/>Bolt / HTTP]
    end

    subgraph "Ferrosa Node"
        CQL[ferrosa-cql<br/>CQL Protocol v5]
        Graph[ferrosa-graph<br/>Cypher + Bolt v5]
        Schema[ferrosa-schema<br/>DDL, Auth, Audit]
        Cluster[ferrosa-cluster<br/>Raft, Routing, CL]
        Index[ferrosa-index<br/>Secondary + Vector Indexes]
        UDF[ferrosa-udf<br/>WASM Sandbox]
        Storage[ferrosa-storage<br/>Memtable, Cache, Compaction, PITR]
        SST[ferrosa-sstable<br/>BTI Read + Write]
        Net[ferrosa-net<br/>Internode Protocol]
        Web[Web Console<br/>Port 9090]
    end

    subgraph "Persistence"
        NVMe[Ephemeral NVMe<br/>Local Cache]
        S3[S3-Compatible Store<br/>Durable Storage]
    end

    subgraph "Other Ferrosa Nodes"
        N2[Node 2]
        N3[Node 3]
    end

    D1 & D2 -->|CQL Native Protocol v5| CQL
    D3 -->|CQL + HTTP| CQL & Web
    D4 -->|Bolt v5 / HTTP| Graph
    CQL --> Schema
    CQL --> Storage
    CQL --> Cluster
    CQL --> Index
    CQL --> UDF
    Graph --> Schema
    Graph --> Storage
    Cluster --> Storage
    Index --> Storage
    Cluster --> Net
    Storage --> SST
    SST --> NVMe
    SST -.->|async upload| S3
    Storage --> NVMe
    Storage -.->|write-behind + PITR archive| S3
    Net <-->|Internode| N2 & N3
    Cluster -.->|Raft consensus| N2 & N3

Loading

Storage Model: Write-Behind Async S3

Writes go to a local commit log and memtable, then acknowledge to the client based on the configured consistency level. SSTables are flushed to local ephemeral storage and asynchronously uploaded to S3. The commit log is also shipped to S3 on a short interval (configurable interval) for crash recovery.

Data durability during the async upload window is protected by:

1. Quorum writes — data exists on multiple replicas before acknowledgment
2. Commit log shipping — small, frequent uploads to S3 (seconds, not minutes)
3. Upload priority — freshly-flushed SSTables upload before compaction output
4. Replica coordination — at least one replica confirming S3 upload marks data fully durable
5. Increased quorum (optional) — users can set write CL=ALL or higher RF for maximum durability during migration

Reads check memtable first, then local SSTable cache, falling back to S3 on cache miss. Bloom filters and partition indices are always cached locally.

Ferrosa 0.13 changes the in-memory shape of flushed SSTables: table views carry lightweight descriptors, open SSTableReader handles are routed through an engine-wide capped pool, large range/repair reads stream partition data instead of materializing tiers, and compaction inputs are pool-routed behind a global concurrency gate.

SSTable Compatibility

Ferrosa implements Cassandra's SSTable formats in phases:

• BTI format (trie-based, Cassandra 5.x default) — primary read/write format, implemented first
• Big format (legacy) — read support planned for migrating older Cassandra deployments

Storage I/O is abstracted behind ReadAt/WriteAt traits, enabling the same SSTable code to read from local files or S3. A future native Ferrosa format optimized for S3 access patterns is planned behind a feature flag.

Cluster Coordination

• Metadata consensus: Raft (via openraft) for schema, topology, and token management
• Data consistency: Cassandra-compatible tunable consistency levels
• Failure detection: Heartbeat-based with configurable thresholds
• Internode protocol: Custom binary protocol over TCP with TLS

Distributed transactions (Accord-style) exist in the implementation and test specs, but public Jepsen-style verification is still a planned evidence item rather than a release guarantee.

PostgreSQL Wire Protocol (developer preview)

Alongside CQL, Ferrosa speaks the PostgreSQL v3 wire protocol on port 5432 with SCRAM-SHA-256 auth, so standard clients (psql, psycopg2, tokio-postgres) connect to the same data. The current surface covers:

• Queries: SELECT with projection, WHERE (=/!=/range, AND/OR/NOT), inner JOIN, GROUP BY + COUNT/SUM/MIN/MAX/AVG, HAVING, DISTINCT, ORDER BY/LIMIT/OFFSET, three-valued NULL logic, and no-FROM expression selects (SELECT 1, version()).
• Writes: single-row INSERT/UPDATE/DELETE (with NULL handling), sharing the same storage engine and row encoder as the CQL path — a row written over Postgres reads back identically over CQL.
• Transactions: BEGIN/COMMIT/ROLLBACK protocol state (idle/in-txn/failed); Accord-backed atomicity is in progress.

Both the simple and extended (Parse/Bind/Execute) query protocols are supported. The front-end's behavior is continuously cross-checked against a real PostgreSQL 16 by a differential oracle in CI (the postgres-oracle job): the same data and SQL run against both systems and the result sets must agree; unsupported SQL fails loud rather than returning wrong rows. See the PostgreSQL wire reference and specs/implemented/postgres-differential-oracle.md.

Crates

Crate	Description
ferrosa	Binary — composes all crates into the running database
ferrosa-cluster	Raft metadata, node membership, tunable CL, request routing, hinted handoff
ferrosa-cql	CQL native protocol v5, query parsing, execution, EXPLAIN
ferrosa-graph	Graph query engine — Cypher parser, Bolt v5, adjacency index, HTTP endpoint
ferrosa-index	Pluggable secondary indexes — B-tree, hash, composite, phonetic, vector
ferrosa-udf	WASM-sandboxed user-defined functions and aggregates
ferrosa-storage	Memtable, commit log, compaction, S3 write-behind, PITR, cache management
ferrosa-schema	Table/keyspace definitions, auth, audit, system keyspaces
ferrosa-sstable	Read/write BTI SSTables, trie indices, Bloom filter, compression
ferrosa-net	Internode protocol, connection management, priority-lane RPC
ferrosa-ctl	CLI admin tool with TUI monitoring, snapshot/restore commands
ferrosa-common	Shared types: Token, PartitionKey, DecoratedKey, CQL types

Testing

cargo test                        # Workspace tests
cargo test -p ferrosa-storage     # Single crate
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

Project Status

Ferrosa is a developer-preview workspace with 18 Rust crates. Core single-node CQL/storage paths, graph/query experiments, secondary indexes, Raft-backed metadata coordination, anti-entropy repair, and PITR building blocks are implemented, but the public release is not yet production-hardened. Cluster bootstrap/rebalance, end-to-end Jepsen verification, full CQL/query conformance, arbitrary query CDC, complete observability backing tables, strict repair memory bounds under every SSTable-overlap shape, and binary vector sidecars remain tracked as proposed/open or verification work in the specs.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development workflow, hygiene checklist, and what we accept. By contributing, you agree to the Code of Conduct.

Security issues should be reported privately — see SECURITY.md.

License

Ferrosa is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE for details.

Copyright 2026 Ferrosa, Inc.