Skip to content

v1.0.0: Early Read-Scaling Milestone

Choose a tag to compare

View all tags
@MartinKalema MartinKalema released this 01 Apr 10:33
· 302 commits to dev since this release
v1.0.0
ace3caf

Historical note, June 2026: This release records the first primary-replica read-scaling milestone. The project has since evolved toward a broader clustered architecture with route authority, Raft-backed partition durability, and distributed write-path hardening. For the current milestone and active roadmap, see v2.1.0-alpha.1 and docs/issue-journal.md.

The first Primary-Replica horizontal scaling implementation for the Convex open-source backend.

Write to the Primary, read from any Replica. Data replicates in real-time via NATS JetStream. Each node has its own independent PostgreSQL database.

Verified

  • 125 records across 4 tables (users, projects, tasks, messages)
  • 3 nodes: 1 Primary + 2 Replicas
  • 60 queries including filters, aggregations, cross-table joins, text search
  • All returning identical results across all three nodes

Architecture

Client → Primary (write) → PostgreSQL → NATS JetStream → Replicas (read)
  • Primary handles writes, publishes CommitDeltas to NATS
  • Replicas consume deltas, remap TabletIds, apply to their own SnapshotManager + Persistence
  • NATS JetStream carries the commit log with durable consumers
  • Each node has its own PostgreSQL database — fully independent

Components

Component Purpose
CommitDelta Transaction change capture
NatsDistributedLog NATS JetStream publish/subscribe
ReplicaDeltaConsumer Tails NATS, feeds deltas through Committer
apply_replica_delta 5-phase apply with TabletId remapping
MutationForwarderService gRPC mutation forwarding
SnapshotCheckpointer Periodic persistence snapshots
CheckpointPersistence Bootstrap Replicas from checkpoints

Stats

  • 1,718 lines of new Rust code
  • 11 new files, 16 modified files
  • 337 unit tests passing
  • 60 integration queries verified across 3 nodes

Quick Start

docker build -f self-hosted/docker-build/Dockerfile.backend \
  -t convex-backend-replicated \
  --build-arg VERGEN_GIT_SHA=$(git rev-parse HEAD) \
  --build-arg VERGEN_GIT_COMMIT_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ) .

cd self-hosted/docker
docker compose -f docker-compose.replicated.yml up

Prior Art

No one has done this before. Convex's docs state: "If you want to scale it, you'll need to modify the open-source backend code." 657+ forks on GitHub, none with horizontal scaling. This is the first.

Assets 2
Loading