← Back to homepage

Getting Started

Install Ferrosa and run a single-node instance in minutes. Everything you need to connect existing CQL drivers and start querying.

Installation

Run Ferrosa

Minimal startup

# Start with defaults — CQL on :9042, web console on :9090
./target/release/ferrosa

With graph engine enabled

FERROSA_GRAPH_ENABLED=true ./target/release/ferrosa

Custom ports and auth disabled (development)

FERROSA_CQL_BIND=127.0.0.1:9042 \
FERROSA_WEB_BIND=127.0.0.1:9090 \
FERROSA_AUTH_DISABLED=true \
FERROSA_GRAPH_ENABLED=true \
./target/release/ferrosa

Default ports

Service	Port	Protocol
CQL Server	9042	CQL native protocol v5
Web Console	9090	HTTP (REST API + static UI + WebSocket)
Graph HTTP	7474	HTTP/JSON (Cypher queries)
Prometheus Metrics	9090/metrics	HTTP (text exposition)
Internode (cluster)	7000	Custom binary protocol

Connect a CQL Driver

Ferrosa speaks CQL protocol v5 — the same wire protocol as Apache Cassandra. Any standard CQL driver works unchanged.

Python

from cassandra.cluster import Cluster

cluster = Cluster(['127.0.0.1'])
session = cluster.connect()

# Create a keyspace
session.execute("""
    CREATE KEYSPACE demo WITH replication = {
        'class': 'SimpleStrategy',
        'replication_factor': 1
    }
""")

# Create a table
session.execute("""
    CREATE TABLE demo.users (
        user_id uuid PRIMARY KEY,
        name text,
        email text
    )
""")

# Insert and query
session.execute("""
    INSERT INTO demo.users (user_id, name, email)
    VALUES (uuid(), 'Alice', 'alice@example.com')
""")

rows = session.execute("SELECT * FROM demo.users")
for row in rows:
    print(row.name, row.email)

Java

// Same DataStax Java driver — just change the contact point
CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
    .withLocalDatacenter("datacenter1")
    .build();

ResultSet rs = session.execute("SELECT * FROM demo.users");

Go

cluster := gocql.NewCluster("127.0.0.1")
session, _ := cluster.CreateSession()
defer session.Close()

var name, email string
session.Query("SELECT name, email FROM demo.users LIMIT 1").Scan(&name, &email)

cqlsh

# Standard cqlsh connects directly
cqlsh 127.0.0.1 9042

Configuration Reference

Ferrosa is configured via environment variables. All are optional with sensible defaults.

Core

Variable	Default	Description
FERROSA_CQL_BIND	0.0.0.0:9042	CQL server bind address
FERROSA_WEB_BIND	0.0.0.0:9090	Web console bind address
FERROSA_AUTH_DISABLED	false	Disable SASL authentication
FERROSA_GRAPH_ENABLED	false	Enable graph engine + HTTP endpoint
RUST_LOG	info	Tracing filter (e.g. debug, ferrosa_cql=trace)

Cluster (ferrosa-net / ferrosa-cluster)

Variable	Default	Description
FERROSA_CLUSTER_NAME	ferrosa	Cluster name (must match across nodes)
FERROSA_CLUSTER_MODE	standalone	Cluster mode: standalone, pair, or cluster
FERROSA_SEED	—	Comma-separated seed addresses
FERROSA_INTERNODE_BIND	0.0.0.0:7000	Internode protocol bind address
FERROSA_INTERNODE_BROADCAST	—	Address other nodes use to reach this node
FERROSA_INTERNODE_PSK	—	Pre-shared key for internode auth (HMAC-SHA256)
FERROSA_DATA_CENTER	dc1	Data center name
FERROSA_RACK	rack1	Rack name within the data center
FERROSA_NUM_TOKENS	256	Number of tokens on the ring
FERROSA_DEFAULT_CL	QUORUM	Default consistency level
FERROSA_HEARTBEAT_INTERVAL_MS	1000	Heartbeat interval between peers
FERROSA_HEARTBEAT_TIMEOUT_MS	5000	Timeout before marking a peer as down
FERROSA_MAX_INTERNODE_CONNECTIONS	64	Max concurrent internode connections
FERROSA_AUTO_JOIN	true	Automatically join the ring on startup (dev mode)
FERROSA_HINTED_HANDOFF_MAX_MB	1024	Max disk space for hinted handoff per peer (MB)

Storage

Variable	Default	Description
FERROSA_DATA_DIR	/var/lib/ferrosa	Local data directory for SSTables and commit log
FERROSA_CACHE_MAX_BYTES	10737418240	Local LRU cache size (10 GB)
FERROSA_FLUSH_THRESHOLD_BYTES	67108864	Memtable flush threshold (64 MB)
FERROSA_S3_ENDPOINT	—	S3-compatible endpoint URL
FERROSA_S3_BUCKET	—	S3 bucket for durable storage
FERROSA_S3_REGION	us-east-1	AWS region for S3
FERROSA_S3_ACCESS_KEY_ID	—	Access key (falls back to instance profile)
FERROSA_S3_SECRET_ACCESS_KEY	—	Secret access key
FERROSA_S3_ALLOW_HTTP	false	Allow non-TLS for local dev (MinIO)
FERROSA_S3_PREFIX	—	Key prefix for multi-tenant separation
FERROSA_S3_UPLOAD_QUEUE_DEPTH	16	Upload backpressure queue depth

Compaction (STCS)

Variable	Default	Description
FERROSA_COMPACTION_MIN_THRESHOLD	4	Min SSTables to trigger compaction
FERROSA_COMPACTION_MAX_THRESHOLD	32	Max SSTables per compaction task
FERROSA_COMPACTION_BUCKET_LOW	0.5	Lower size ratio for bucket membership
FERROSA_COMPACTION_BUCKET_HIGH	1.5	Upper size ratio for bucket membership

CLI Tools

ferrosa-ctl

Admin CLI for querying and monitoring a running Ferrosa node.

# Run a CQL query
ferrosa-ctl query "SELECT * FROM demo.users"

# Describe schema
ferrosa-ctl describe

# Show Prometheus metrics
ferrosa-ctl metrics

# Node health status
ferrosa-ctl status

# Active CQL connections
ferrosa-ctl connections --sort client_addr

# Currently running queries (long-running only)
ferrosa-ctl queries --long-running

# Storage engine stats
ferrosa-ctl storage

# Live TUI dashboard (ratatui)
ferrosa-ctl monitor

# Cluster management
ferrosa-ctl add-node 10.0.0.5:7000        # Pre-approve a node for cluster join
ferrosa-ctl decommission 10.0.0.3:7000   # Gracefully remove a node
ferrosa-ctl ring                          # Show token ring distribution
ferrosa-ctl rebalance                     # Trigger token rebalancing

The monitor command launches a terminal dashboard with 5 panels showing connections, active queries, storage stats, and more. Navigate with arrow keys, refresh is automatic. Connect to a specific host with --host 10.0.0.1:9042.

Architecture Overview

Ferrosa is composed of 12 independent Rust crates that can be used together or embedded individually.

Operational Notes

S3 Storage Resilience

When S3 is configured as the durable backend, Ferrosa writes asynchronously to S3 via an upload queue. If S3 becomes temporarily unreachable:

• Reads and writes continue against local disk and memtables.
• Uploads are retried automatically when connectivity resumes.
• Data written during the outage exists only on local disk until the next successful upload.

Multi-Node Cluster (Experimental)

Three-node cluster mode (FERROSA_CLUSTER_MODE=cluster) uses Raft consensus for metadata and tunable consistency for data. Current limitations:

• When one node in a three-node cluster goes down, reads and writes continue at reduced availability depending on the configured consistency level.
• Schema state on surviving nodes may temporarily diverge until the failed node rejoins and the Raft log is replayed.
• Automatic rebalancing after node loss is not yet implemented — use ferrosa-ctl for manual recovery.

For the full architecture spec, see the the project repository.

What's Next