Module sharding 

Horizontal sharding support for SQLModel Rust.

This module provides infrastructure for partitioning data across multiple database shards based on a shard key.

Overview

Horizontal sharding distributes rows across multiple databases based on a shard key (e.g., user_id, tenant_id). This enables:

• Horizontal scalability beyond single-database limits
• Data isolation between tenants/regions
• Improved query performance through data locality

Example

use sqlmodel_pool::{Pool, PoolConfig, ShardedPool, ShardChooser};
use sqlmodel_core::{Model, Value};

// Define a shard chooser based on modulo hashing
struct ModuloShardChooser {
    shard_count: usize,
}

impl ShardChooser for ModuloShardChooser {
    fn choose_for_model(&self, shard_key: &Value) -> String {
        let id = match shard_key {
            Value::BigInt(n) => *n as usize,
            Value::Int(n) => *n as usize,
            _ => 0,
        };
        format!("shard_{}", id % self.shard_count)
    }

    fn choose_for_query(&self, _hints: &QueryHints) -> Vec<String> {
        // Query all shards by default
        (0..self.shard_count)
            .map(|i| format!("shard_{}", i))
            .collect()
    }
}

// Create sharded pool
let mut sharded_pool = ShardedPool::new(ModuloShardChooser { shard_count: 3 });
sharded_pool.add_shard("shard_0", pool_0);
sharded_pool.add_shard("shard_1", pool_1);
sharded_pool.add_shard("shard_2", pool_2);

// Insert routes to correct shard based on model's shard key
let order = Order { user_id: 42, ... };
let shard = sharded_pool.choose_for_model(&order);

Structs

ModuloShardChooser

A simple modulo-based shard chooser for numeric shard keys.

QueryHints

Hints for query routing when a specific shard key isn’t available.

ShardedPool

A sharded connection pool that routes operations to the correct shard.

ShardedPoolStats

Aggregate statistics for a sharded pool.

Traits

ShardChooser

Trait for determining which shard(s) to use for operations.