Enum ReadRouting 

#[non_exhaustive]
pub enum ReadRouting {
    Any,
    Primary,
    Replica {
        max_lag_ms: Option<u64>,
    },
}

Where one compiled query’s reads may be served from.

Why this exists as a schema field

Read-replica routing is otherwise a whole-server decision: the pin window and the staleness budget apply to every query alike, so an operator sizing them for the strictest query gives up the offload on all the others, and sizing them for the common case silently serves the strict one stale. A per-query override is the only way to have both.

The contract

FraiseQL defines and enforces this shape; an authoring language emits it. A @reads_from(...) directive is one spelling of it, and the spelling is that project’s to choose — what is fixed here is what the runtime can actually guarantee, which is exactly these three answers. Replica topology deliberately stays out: URLs are server configuration and secrets, not compiled schema.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Any

Server policy decides: replicas when configured and eligible, primary inside the read-your-writes pin window or when no replica qualifies.

The default, and what every query did before this field existed.

Primary

Never serve this query from a replica.

For reads where staleness is a correctness problem rather than a performance trade — a balance before a transfer, an authorization decision, the row a client is about to act on.

Also bypasses the result cache. A cached row is stale data by construction, so a query that asked not to be served stale from a replica and was then served stale from memory would have got the opposite of what it asked for. Primary means “fresh”, not “from a particular host”.

Replica

Prefer a replica even inside the read-your-writes pin window, optionally under a tighter (or looser) staleness budget than the server’s.

For reads that are explicitly allowed to be behind — feeds, dashboards, exports — where paying primary capacity for freshness nobody needs is the waste worth naming.

Still falls back to the primary when no replica qualifies: this is a statement about which server should answer, and refusing to answer at all would turn a capacity preference into an outage.

Fields

max_lag_ms: Option<u64>

Staleness budget for this query alone, in milliseconds.

None uses the server’s read_replica_max_lag_ms. A value here replaces it rather than intersecting with it — a query that knows it tolerates ten minutes is as legitimate as one that needs 50 ms, and both are the schema author’s call.

A budget on a server with no measurement configured is still honoured: probing is unconditional, so the reading exists whether or not the server set a global budget.

Implementations

impl ReadRouting

pub const fn is_default(&self) -> bool

Whether this is Any — the serde skip predicate, so a schema that never mentions routing round-trips byte-identically.

pub const fn allows_replica(&self) -> bool

Whether a replica may serve this query at all.

pub const fn honours_write_pin(&self) -> bool

Whether the read-your-writes pin window applies to this query.

Replica opts out of it: the pin exists so a client reads its own writes, and a query annotated as tolerating staleness has said that is not what it is for.

pub const fn allows_cached_result(&self) -> bool

Whether a result-cache hit may serve this query.

See Primary for why it may not.

pub const fn effective_max_lag_ms( &self, server_max_lag_ms: Option<u64>, ) -> Option<u64>

This query’s staleness budget in milliseconds, given the server’s.

Trait Implementations

impl Clone for ReadRouting

fn clone(&self) -> ReadRouting

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for ReadRouting

impl Debug for ReadRouting

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

Formats the value using the given formatter.

impl Default for ReadRouting

fn default() -> ReadRouting

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ReadRouting

fn deserialize<__D>( __deserializer: __D, ) -> Result<ReadRouting, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ReadRouting

impl PartialEq for ReadRouting

fn eq(&self, other: &ReadRouting) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ReadRouting

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ReadRouting