Sharding

Scale horizontally by distributing your data across multiple nodes. Automatic rebalancing and high availability for your mission-critical details.

Architecture

SoliDB uses consistent hashing to partition data across a fixed number of "virtual shards" (default 256). These shards are then assigned to physical nodes in the cluster.

Virtual Shards

Data keys are hashed to a value between 0-255. This ID determines the virtual shard, ensuring uniform distribution.

Physical Nodes

Each virtual shard is assigned to `replicationFactor` physical nodes (1 leader, N followers).

Replication Strategy

Updates are synchronously replicated to the leader and asynchronously propagated to followers. Reading from followers provides eventual consistency, while reading from the leader guarantees strong consistency.

Auto-Healing & Rebalancing

The cluster actively monitors node health. If a node fails, the system automatically promotes followers to leaders to maintain availability.

Health Checks

Nodes exchange heartbeats every 500ms. A node is marked "failed" after 3 consecutive missed hearts.

Manual Rebalancing

Trigger a rebalance to redistribute shards evenly after adding/removing nodes.

curl -X POST http://localhost:6745/_api/cluster/rebalance

API Extensions

Method	Endpoint	Description
GET	/_api/health	Get basic node health status
POST	/_api/cluster/rebalance	Trigger shard rebalancing
GET	/_api/database/:db/collection/:name/sharding	Get detailed sharding info (nodes, shards)

Configuration

Enable sharding when creating a collection by specifying sharding properties.

POST /_api/database/_system/collection

{
  "name": "users",
  "shardKey": "_key",
  "numShards": 16,
  "replicationFactor": 3
}