Struct ShardConfig 

pub struct ShardConfig {
    pub name: String,
    pub primary_url: String,
    pub slots: Option<Vec<SlotSpec>>,
    pub replica_url: Option<String>,
    pub primary_pool_size: Option<usize>,
    pub replica_pool_size: Option<usize>,
    pub replica_fallback: Option<ReplicaFallback>,
}

One horizontal shard of the application’s data, declared via [[database.shards]] in autumn.toml.

Each shard is a full primary/replica topology of its own, so the replica story composes with sharding: any shard may have a read replica, role-specific pool sizes, and its own fallback behavior. Fields left unset fall back to the corresponding [database] value.

Routing: keys → logical slots → shards

Routing keys hash onto a fixed set of SLOT_COUNT (16384) logical slots, and each slot maps to one shard. The key→slot hash is a permanent contract; the slot→shard map is plain configuration. Growing from two shards to three means moving whole slots — copy a slot’s rows to the new shard, flip its slots entry, deploy — without rehashing any keys.

When every shard declares slots, declaration order is meaningless and entries can be reordered, renamed, or removed freely (as long as the map still covers every slot exactly once). When no shard declares slots, the framework auto-splits the slot space into contiguous even ranges by declaration order — convenient to start with, but reordering entries then moves data. Pin explicit slots before making any topology change.

Example

[database]
primary_url = "postgres://db-control/app"   # control role: jobs, sessions, flags

[[database.shards]]
name = "shard0"
primary_url = "postgres://db-shard0/app"
slots = ["0-8191"]

[[database.shards]]
name = "shard1"
primary_url = "postgres://db-shard1/app"
slots = ["8192-16383"]
replica_url = "postgres://db-shard1-ro/app"
replica_fallback = "primary"

Fields

name: String

Stable shard identity used in logs, metric tags, health component names (db:shard:<name>), and autumn migrate --shard <name>.

Must be non-empty, unique across shards, and restricted to [a-z0-9_-] so it can be embedded in metric/health keys.

primary_url: String

Postgres URL for this shard’s primary/write role. Required.

slots: Option<Vec<SlotSpec>>

Logical slots this shard owns, as indices and/or "A-B" inclusive ranges (e.g. slots = ["0-8191", 16000, "16382-16383"]).

All-or-none across shards: either every shard declares slots (explicit map covering 0..16384 exactly once; an empty list marks a drained shard being decommissioned) or none does (contiguous auto-split by declaration order).

replica_url: Option<String>

Optional Postgres URL for this shard’s read-replica role.

primary_pool_size: Option<usize>

Optional primary pool size override. Falls back to database.primary_pool_size, then database.pool_size.

replica_pool_size: Option<usize>

Optional replica pool size override. Falls back to database.replica_pool_size, then database.pool_size.

replica_fallback: Option<ReplicaFallback>

Optional replica fallback override. Falls back to database.replica_fallback.

Implementations

impl ShardConfig

pub fn effective_primary_pool_size(&self, defaults: &DatabaseConfig) -> usize

Resolved primary pool size for this shard.

pub fn effective_replica_pool_size(&self, defaults: &DatabaseConfig) -> usize

Resolved replica pool size for this shard.

pub fn effective_replica_fallback( &self, defaults: &DatabaseConfig, ) -> ReplicaFallback

Resolved replica fallback behavior for this shard.

Trait Implementations

impl Clone for ShardConfig

fn clone(&self) -> ShardConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ShardConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ShardConfig

fn default() -> ShardConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ShardConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.