Struct DatabaseConfig 

pub struct DatabaseConfig {

    pub url: Option<String>,
    pub primary_url: Option<String>,
    pub replica_url: Option<String>,
    pub pool_size: usize,
    pub primary_pool_size: Option<usize>,
    pub replica_pool_size: Option<usize>,
    pub replica_fallback: ReplicaFallback,
    pub read_your_writes: ReadYourWrites,
    pub pin_after_write_secs: u64,
    pub replica_max_lag_ms: Option<u64>,
    pub warn_on_pooler: bool,
    pub connect_timeout_secs: u64,
    pub startup_wait_secs: u64,
    pub auto_migrate: Option<bool>,
    pub auto_migrate_in_production: bool,
    pub statement_timeout: Option<Duration>,
    pub idle_in_transaction_timeout: Option<Duration>,
    pub migration_lock_timeout: Duration,
    pub migration_lock_retries: u32,
    pub slow_query_threshold: Duration,
    pub shards: Vec<ShardConfig>,
    pub directory_shard_router: bool,
    pub max_connections_warn_threshold: usize,
    pub fleet: Option<DatabaseFleetConfig>,
}

Database connection configuration.

When url is None (the default), the application runs without a database – useful for static-site or API-gateway use cases. Set a Postgres URL to enable the connection pool and the Db extractor.

Defaults

Field	Default
url	None
primary_url	None
replica_url	None
pool_size	10
primary_pool_size	None
replica_pool_size	None
replica_fallback	fail_readiness
connect_timeout_secs	5
auto_migrate	None
auto_migrate_in_production	false
shards	[]

Examples

use autumn_web::config::DatabaseConfig;

let db = DatabaseConfig::default();
assert!(db.url.is_none());
assert_eq!(db.pool_size, 10);

Fields

url: Option<String>

Postgres connection URL. None means no database is configured.

Compatibility alias for the primary/write role. New multi-role deployments should prefer primary_url.

When present, must start with postgres:// or postgresql://, or be a libpq-style keyword/value connection string (host=db user=app dbname=app sslmode=require).

primary_url: Option<String>

Postgres URL for the primary/write role.

All writes, transactions, advisory locks, and migrations use this role. When unset, url remains the single-primary fallback.

replica_url: Option<String>

Optional Postgres URL for the read/replica role.

Read-only paths may use this pool when configured. If omitted, read paths use the primary role.

pool_size: usize

Maximum number of connections in the pool. Default: 10.

Compatibility/default pool size used for both roles unless a role-specific size is set.

primary_pool_size: Option<usize>

Optional primary/write role pool size.

replica_pool_size: Option<usize>

Optional read/replica role pool size.

replica_fallback: ReplicaFallback

Deterministic behavior for configured replicas that cannot safely serve reads. Default: fail readiness.

read_your_writes: ReadYourWrites

Post-write read pinning strategy. Default: off (no pinning).

Set to request to pin reads to the primary for the remainder of the request after the first write. Set to session to additionally pin reads across requests via a signed cookie.

Override via AUTUMN_DATABASE__READ_YOUR_WRITES.

pin_after_write_secs: u64

Duration (seconds) for cross-request session pins.

Only used when read_your_writes = "session". A signed autumn.ryw cookie pins the client’s reads to the primary for this many seconds after a write. Default: 5.

Override via AUTUMN_DATABASE__PIN_AFTER_WRITE_SECS.

replica_max_lag_ms: Option<u64>

Maximum replica lag, in milliseconds (issue #3065).

When set, the app measures the replica lag in the background, and /ready reports the last sample. While the lag is over the limit, or not known, reads go to the primary. Lag alone does not fail readiness. None or 0 turns the check off. Override via AUTUMN_DATABASE__REPLICA_MAX_LAG_MS.

warn_on_pooler: bool

Log a warning at boot when a database URL looks like a connection pooler (PgBouncer, RDS Proxy, Supavisor, Neon). Default: true. See docs/guide/connection-poolers.md. Override via AUTUMN_DATABASE__WARN_ON_POOLER.

connect_timeout_secs: u64

Seconds to wait while acquiring a pooled connection, including creating a new connection when the pool grows. Default: 5.

startup_wait_secs: u64

Bounded startup wait (seconds) for the database to become reachable before the migrator fails. 0 (the default) disables the wait and preserves the current fail-fast behaviour — a single connection attempt, no retry. Set a non-zero value (e.g. 60) to have autumn migrate retry with capped exponential backoff until either the database accepts connections or the window elapses.

Override via AUTUMN_DATABASE__STARTUP_WAIT_SECS.

auto_migrate: Option<bool>

Profile-agnostic explicit override for startup migration auto-apply (issue #1903). None (the default, when the key is absent) leaves the decision to convention: dev/development auto-apply, every other profile (prod/production and custom names like fly/staging) is opt-in. Some(true) / Some(false) overrides that convention on any profile.

This supersedes Self::auto_migrate_in_production, which is retained as a back-compat alias: when auto_migrate is unset but auto_migrate_in_production = true, auto-apply is enabled on any non-dev profile (so a custom-profile operator’s existing config finally takes effect). auto_migrate wins when both are set.

Override via AUTUMN_DATABASE__AUTO_MIGRATE.

auto_migrate_in_production: bool

Back-compat alias for Self::auto_migrate (issue #1903). When true, permits automatic migration application on any non-dev profile (not just prod/production — the old name-gated behavior silently skipped custom profiles). Default: false. Prefer setting auto_migrate directly; this key is honored only when auto_migrate is unset.

Keep this disabled for multi-replica production fleets and use an explicit migration job (autumn migrate) instead.

statement_timeout: Option<Duration>

Optional database statement timeout. "0s" disables it.

Set as a session SET on checkout, and again as SET LOCAL at the start of each framework transaction, so a transaction pooler such as PgBouncer cannot drop it. The prod profile sets 30s (#3057).

Override via AUTUMN_DATABASE__STATEMENT_TIMEOUT.

idle_in_transaction_timeout: Option<Duration>

Optional idle_in_transaction_session_timeout. "0s" disables it.

Set as SET LOCAL at the start of each framework transaction. Postgres ends a session that stays idle in an open transaction for longer than this. The prod profile sets 60s (#3057).

Override via AUTUMN_DATABASE__IDLE_IN_TRANSACTION_TIMEOUT.

migration_lock_timeout: Duration

Postgres lock_timeout for the migration session. Default: 5s. "0s" disables it.

A migration that waits longer than this for a table lock fails, and the migrator retries it (see Self::migration_lock_retries). This stops a DDL statement that queues behind a long transaction from blocking all traffic on that table (#3057).

Override via AUTUMN_DATABASE__MIGRATION_LOCK_TIMEOUT.

migration_lock_retries: u32

Retries after a migration fails on migration_lock_timeout. Default: 5. 0 disables the retry. Each retry waits a jittered, exponential delay.

Override via AUTUMN_DATABASE__MIGRATION_LOCK_RETRIES.

slow_query_threshold: Duration

Slow query threshold. Default: 500ms.

shards: Vec<ShardConfig>

Horizontal shards, declared as [[database.shards]] entries.

Empty (the default) means the application is unsharded and only the url/primary_url/replica_url roles above apply. When non-empty, those top-level roles become the control topology — framework state (jobs, scheduler locks, sessions, feature flags) lives there while tenant data is routed across the shards. See ShardConfig.

directory_shard_router: bool

Route tenants through the control-plane _autumn_shard_directory table (a DirectoryShardRouter) instead of pure slot-hash routing. Default: false.

Tenants with a directory row are pinned to the named shard; everyone else falls back to the hash router. Usually set via AppBuilder::with_directory_shard_router. Ignored when no shards are configured or an explicit with_shard_router is set.

max_connections_warn_threshold: usize

Emit a startup warning when the aggregate maximum connection count across the control topology and every shard pool reaches this value. Default: 100.

Pool sizes multiply across shards: an N-shard fleet with a pool size of 20 opens up to 20 * N connections, which can exhaust Postgres’s max_connections (default 100) long before the app looks busy. This threshold surfaces that footgun at boot. Set to 0 to disable.

fleet: Option<DatabaseFleetConfig>

A fleet of SQLite databases: one file per tenant or one per routing slot (ADR 0019). None (the default) means no fleet.

With a fleet, the top-level url is the control database (sessions, jobs, flags) and tenant data is routed by ShardedDb, Shards and #[repository(sharded)] to a database file opened on first use. Requires the sqlite feature and a sqlite: control database; mutually exclusive with shards. See DatabaseFleetConfig.

Implementations

impl DatabaseConfig

pub fn effective_primary_url(&self) -> Option<&str>

Resolved primary/write database URL.

pub fn effective_primary_postgres_url(&self) -> Option<&str>

Resolved primary/write database URL, but only when it names Postgres.

Autumn ships subsystems that are Postgres-only by construction — the PgFlagStore, PgExperimentStore and PgConfigStore open a diesel::PgConnection and issue pg_notify / pg_advisory_xact_lock / jsonb SQL. Handing one a SQLite target builds a store that fails on first use with a connection error naming a driver the operator never chose. This accessor is what those constructors screen on, so an unsupported target yields “no store” at construction instead.

Fails closed: a target DatabaseBackend::detect cannot classify is refused too, rather than handed to a Postgres driver on the chance that it might work.

pub fn effective_primary_pool_size(&self) -> usize

Resolved primary/write role pool size.

pub fn effective_replica_pool_size(&self) -> usize

Resolved read/replica role pool size.

pub const fn has_shards(&self) -> bool

Whether any [[database.shards]] entries are configured.

pub fn resolved_slot_map(&self) -> Result<Vec<usize>, ConfigError>

Resolve the slot→shard map: element s is the index (into shards) of the shard that owns slot s.

This is the single source of truth for slot assignment, used by both configuration validation and runtime ShardSet construction:

• When no shard declares slots, the slot space is auto-split into contiguous even ranges by declaration order.
• When every shard declares slots, the explicit assignments are used and must cover 0..SLOT_COUNT exactly once.
• Mixing declared and undeclared slots is an error.

Errors

Returns ConfigError::Validation for mixed declarations, malformed/out-of-range/duplicate slots, or incomplete coverage.

pub fn shards_auto_split(&self) -> bool

Whether all shards are using auto-split (no shard declares slots).

Returns false when no shards are configured or any shard has an explicit slots declaration. Mixed declarations already error in resolved_slot_map, so this is a simple all-or-none check.

pub fn resolved_shard_assignments( &self, ) -> Result<Vec<ShardSlotAssignment>, ConfigError>

Resolve the per-shard slot assignment as compact range strings.

Inverts resolved_slot_map (slot→shard-index) into per-shard slot lists rendered via the same compact range notation used in slot-map error messages. Agrees with runtime routing by construction: the output derives from the same slot map that builds the live ShardSet.

Errors

Propagates any ConfigError from resolved_slot_map.

pub fn validate(&self) -> Result<(), ConfigError>

Validate database configuration.

Errors

Returns a validation error if a connection string is malformed or a shard declaration is malformed.

Trait Implementations

impl Clone for DatabaseConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DatabaseConfig

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

Formats the value using the given formatter.

impl Default for DatabaseConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DatabaseConfig

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.