Struct SqlKvStore 

pub struct SqlKvStore<C> { /* private fields */ }

The NamespaceStore contract (and StoreMaintenance) over any SqlConn: full capabilities, every batch one SqlConn::transaction.

With a Capacity, an ordinary batch holding a put returns StoreError::Full once the database uses Capacity::soft_limit bytes or more, checked inside its transaction. Delete-only batches and bounded, guarded relay-scan checkpoints, relay timer reschedules, and guarded timer retry moves may use the reserve above that limit. These timer exceptions preserve immediate relay rescheduling and persisted infrastructure backoff on a full shard. An engine Full on a delete-only batch is reported as StoreError::Unavailable, never Full.

Every method is synchronous inside: its future completes on first poll. A host that drives a blocking engine should run each call on a blocking thread.

Implementations

impl<C: SqlConn> SqlKvStore<C>

pub fn open(conn: C) -> Result<Self, StoreError>

A store over conn, after migrating its schema (schema::migrate).

Errors

StoreError::Unsupported for a database with a newer schema than this binary’s; the engine’s error otherwise.

pub fn open_existing(conn: C) -> Result<Self, StoreError>

Open an existing, matching schema without migrating or writing it. Used by native export so a backup operation cannot mutate its source.

Errors

The existing schema must exactly match this binary’s version.

pub fn open_with_capacity( conn: C, capacity: Capacity, ) -> Result<Self, StoreError>

Self::open, capped at capacity: the connection enforces the hard cap (SqlConn::set_size_limit) and the store the soft limit.

Errors

As Self::open.

pub fn apply_extended<F>( &self, p: &Partition, batch: Batch, extend: F, ) -> Result<BatchOutcome, StoreError>

where F: FnOnce(&dyn Fn(&Key) -> Result<Option<Value>, SqlError>, &mut Batch, u64) -> Result<(), SqlError> + 'static,

Apply with a synchronous target-local extension inside the guarded transaction. The extension reads local keys and appends writes only after all input guards hold.

Errors

Invalid batches, extension errors, or backend failures roll back every effect.

pub fn timer_window( &self, after: Option<&TimerCursor>, limit: u32, ) -> Result<Vec<TimerCursor>, StoreError>

Read at most limit raw timer rows in (key, partition) index order.

No row is fetched beyond the allowance, and several rows may name the same partition. An empty window marks the end; the caller decides when to wrap by passing None. The cursor need not still exist in storage.

Errors

Zero limit, failed queries, corrupt partition encodings or result columns.

pub fn capacity(&self) -> Option<Capacity>

The cap, if any.

pub fn conn(&self) -> &C

The connection.

pub fn clear_stats_cache(&self)

Forget cached NamespaceStore::stats, so the next call reads the table.

Trait Implementations

impl<C> Debug for SqlKvStore<C>

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

Formats the value using the given formatter.

impl<C: SqlConn> NamespaceStore for SqlKvStore<C>

fn capabilities(&self) -> StoreCapabilities

What this store supports.

async fn get( &self, p: &Partition, key: &Key, ) -> Result<Option<Value>, StoreError>

The value at key, if any.

async fn get_many( &self, p: &Partition, keys: &[Key], ) -> Result<Vec<Option<Value>>, StoreError>

Several keys in one round trip; results in input order. The default issues sequential Self::get calls.

async fn scan( &self, p: &Partition, start: &Key, end: &Key, after: Option<&Cursor>, limit: u32, ) -> Result<ScanPage, StoreError>

Up to limit (at least 1) entries in [start, end), ascending by key bytes. after resumes strictly after the cursor’s position; a cursor outside [start, end) (forged, or from another range) is StoreError::Invalid. A page may hold fewer than limit entries and still return next: callers page until next is None.

async fn apply( &self, p: &Partition, batch: Batch, ) -> Result<BatchOutcome, StoreError>

One atomic, all-or-nothing batch: validate it, read the backend clock once, check every precondition in order against committed state (NotAfter against that reading); on the first failure return BatchOutcome::PreconditionFailed or BatchOutcome::DeadlinePassed and write nothing, otherwise apply every write and return BatchOutcome::Committed.

async fn stats(&self, p: &Partition) -> Result<PartitionStats, StoreError>

Storage used by one partition; may be approximate or up to 60 s stale.

async fn probe(&self) -> Result<(), StoreError>

A cheap health check.

fn has( &self, p: &Partition, key: &Key, ) -> impl Future<Output = Result<bool, StoreError>> + MaybeSend

Whether key holds a value.

fn scan_many( &self, p: &Partition, ranges: &[RangeScan], ) -> impl Future<Output = Result<Vec<ScanPage>, StoreError>> + MaybeSend

Scan a served prefix of ranges in order. A nonempty request returns at least its first page and at most one page per range; callers re-request any unserved suffix. Every returned page obeys Self::scan. The default serves every range sequentially.

impl<C: SqlConn> StoreMaintenance for SqlKvStore<C>

async fn backup_to(&self, dest: &str) -> Result<(), StoreError>

The connection’s backup (SqlConn::backup_to): StoreError::Unsupported unless the backend has one.

fn layout_version(&self) -> u32

The backend’s physical layout version (its schema, e.g. SQLite’s user_version); independent of keys::LAYOUT_VERSION.

async fn migrate(&self) -> Result<u32, StoreError>

Migrate the physical layout to the version this binary expects; returns the version reached. Idempotent.