Clustering & Replication

Current status

Tellstone runs as a single node — there is no replication or cluster membership yet. However, it does include per-shard WAL persistence for crash recovery (see Architecture for details). Enable it with --enable-persistence.

Without replication, a running Tellstone process is still a single point of failure at the cluster level. Plan deployments accordingly: Tellstone today is best suited as an in-cluster accelerator or cache in front of a system of record, or paired with application-level sharding for horizontal scaling.

Planned for Phase 2

The project’s stated roadmap includes:

Event-driven replication (for example, backed by NATS JetStream) to propagate writes from a primary to one or more followers.
Write-through / write-behind persistence to a downstream durable store, matching the “Write-Behind Puffer” framing the project uses to describe itself.
Official client SDKs beyond the current Go client.
A broader RESP command set (RESP3, INCR, EXPIRE, MULTI/EXEC).
Distributed consensus for coordinated operations across nodes.

None of this is implemented yet. If you’re interested in helping design or build replication, persistence, or a wider command set, see Contributing in the main repo — that’s explicitly called out as an area where help is wanted.

Scaling today, without clustering

Until replication lands, options for scaling beyond one node are application-level:

Shard keys across independent Tellstone instances yourself (consistent hashing in your client), since Tellstone doesn’t do this for you across nodes yet.
Run Tellstone as a cache in front of a durable, already-replicated database, so a lost node only costs you cache warmth, not data.
Implement application-level sharding and failover logic to handle node failures.

Architecture for Future Scaling

The current architecture is designed with future distributed features in mind:

The sharded storage engine with GOMAXPROCS shards provides a foundation for distributed sharding.
The protocol design allows for extension to support distributed operations.
The metrics and tracing infrastructure will support monitoring across distributed nodes.