Struct ShardedPool 

pub struct ShardedPool<C: Connection, S: ShardChooser> { /* private fields */ }

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

ShardedPool wraps multiple Pool instances, one per shard, and uses a ShardChooser to determine which shard to use for each operation.

Example

// Create pools for each shard
let pool_0 = Pool::new(PoolConfig::new(10));
let pool_1 = Pool::new(PoolConfig::new(10));

// Create sharded pool with modulo chooser
let chooser = ModuloShardChooser::new(2);
let mut sharded = ShardedPool::new(chooser);
sharded.add_shard("shard_0", pool_0);
sharded.add_shard("shard_1", pool_1);

// Acquire connection from specific shard
let conn = sharded.acquire_for_model(&cx, &order, factory).await?;

Implementations

impl<C: Connection, S: ShardChooser> ShardedPool<C, S>

pub fn new(chooser: S) -> Self

Create a new sharded pool with the given shard chooser.

pub fn add_shard(&mut self, name: impl Into<String>, pool: Pool<C>)

Add a shard to the pool.

Arguments

• name - The shard name (must match names returned by the chooser)
• pool - The connection pool for this shard

pub fn add_shard_with_config( &mut self, name: impl Into<String>, config: PoolConfig, )

Add a shard with a new pool created from the given config.

pub fn chooser(&self) -> &S

Get a reference to the shard chooser.

pub fn get_shard(&self, name: &str) -> Option<&Pool<C>>

Get a reference to a specific shard’s pool.

pub fn shard_names(&self) -> Vec<String>

Get all shard names.

pub fn shard_count(&self) -> usize

Get the number of shards.

pub fn has_shard(&self, name: &str) -> bool

Check if a shard exists.

pub fn choose_for_model<M: Model>(&self, model: &M) -> Result<String, Error>

Choose the shard for a model based on its shard key.

Returns the shard name. Use this when you need to know the shard without acquiring a connection.

pub fn choose_for_query(&self, hints: &QueryHints) -> Vec<String>

Choose shards for a query based on hints.

pub async fn acquire_for_model<M, F, Fut>( &self, cx: &Cx, model: &M, factory: F, ) -> Outcome<PooledConnection<C>, Error>

where M: Model, F: Fn() -> Fut, Fut: Future<Output = Outcome<C, Error>>,

Acquire a connection from the shard determined by the model’s shard key.

Arguments

• cx - The async context
• model - The model instance (must have a shard key)
• factory - Connection factory function

Errors

Returns an error if:

• The model has no shard key
• The determined shard doesn’t exist
• Connection acquisition fails

pub async fn acquire_from_shard<F, Fut>( &self, cx: &Cx, shard_name: &str, factory: F, ) -> Outcome<PooledConnection<C>, Error>

where F: Fn() -> Fut, Fut: Future<Output = Outcome<C, Error>>,

Acquire a connection from a specific shard by name.

Arguments

• cx - The async context
• shard_name - The name of the shard to acquire from
• factory - Connection factory function

Errors

Returns an error if:

• The shard doesn’t exist
• Connection acquisition fails

pub async fn acquire_for_query<F, Fut>( &self, cx: &Cx, hints: &QueryHints, factory: F, ) -> Result<HashMap<String, PooledConnection<C>>, Error>

where F: Fn() -> Fut + Clone, Fut: Future<Output = Outcome<C, Error>>,

Acquire connections from multiple shards for scatter-gather queries.

Returns a map of shard name to pooled connection for each successfully acquired connection. Failed acquisitions are logged but don’t fail the entire operation.

Arguments

• cx - The async context
• hints - Query routing hints
• factory - Connection factory function

pub fn close(&self)

Close all shards.

pub fn is_closed(&self) -> bool

Check if all shards are closed.

pub fn stats(&self) -> ShardedPoolStats

Get aggregate statistics across all shards.