Trait KeyValueStore 

pub trait KeyValueStore: Send + Sync {
    // Required methods
    fn get(&self, key: &[u8]) -> StorageBackendResult<Option<Vec<u8>>>;
    fn put(&self, key: &[u8], value: &[u8]) -> StorageBackendResult<()>;
    fn delete(&self, key: &[u8]) -> StorageBackendResult<()>;
    fn scan_prefix(
        &self,
        prefix: &[u8],
    ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>>;
    fn delete_prefix(&self, prefix: &[u8]) -> StorageBackendResult<usize>;
    fn batch(&self) -> Box<dyn KeyValueBatch + '_>;
    fn in_transaction(&self) -> bool;
    fn transaction_has_written(&self) -> StorageBackendResult<bool>;

    // Provided methods
    fn resource_leases(&self) -> Option<&dyn ResourceLeaseProvider> { ... }
    fn auxiliary_encryption_key(&self) -> Option<StorageEncryptionKey> { ... }
    fn retention_control(&self) -> Option<StorageReadControl> { ... }
    fn notification_publications(
        &self,
    ) -> Option<&dyn NotificationPublicationStore> { ... }
    fn serializable_session(&self) -> Option<&dyn SerializableSession> { ... }
    fn reclaim_obsolete(&self) -> StorageBackendResult<()> { ... }
    fn vacuum(&self) -> StorageBackendResult<()> { ... }
    fn write_cancellation(&self) -> Option<CancellationToken> { ... }
    fn open_controlled_session(
        &self,
        _control: &StorageReadControl,
    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> { ... }
    fn open_session_with_cancellation(
        &self,
        cancellation: &CancellationToken,
    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> { ... }
    fn open_retained_read_session(
        &self,
        cancellation: &CancellationToken,
    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> { ... }
    fn transaction_model(&self) -> StorageTransactionModel { ... }
    fn identifier_allocator(&self) -> Option<&dyn IdentifierAllocator> { ... }
    fn with_read_view(
        &self,
        _read: &mut KeyValueReadScope<'_>,
    ) -> StorageBackendResult<()> { ... }
    fn with_mutation(
        &self,
        _mutate: &mut KeyValueMutation<'_>,
    ) -> StorageBackendResult<()> { ... }
    fn with_versioned_mutation(
        &self,
        _mutate: &mut KeyValueVersionedMutation<'_>,
    ) -> StorageBackendResult<()> { ... }
    fn transaction_affinity(&self) -> Option<StorageSessionAffinity> { ... }
    fn storage_identity(
        &self,
    ) -> StorageBackendResult<Option<PersistentStorageIdentity>> { ... }
    fn open_session(&self) -> StorageBackendResult<Arc<dyn KeyValueStore>> { ... }
    fn visit_value(
        &self,
        _key: &[u8],
        control: &StorageReadControl,
        _visit: &mut ValueReadVisitor<'_>,
    ) -> StorageBackendResult<()> { ... }
    fn visit_value_bounded(
        &self,
        _key: &[u8],
        _max_bytes: usize,
        control: &StorageReadControl,
        _visit: &mut ValueReadVisitor<'_>,
    ) -> StorageBackendResult<()> { ... }
    fn visit_prefix_after(
        &self,
        _prefix: &[u8],
        _after: Option<&[u8]>,
        _limit: usize,
        control: &StorageReadControl,
        _visit: &mut KeyValueReadVisitor<'_>,
    ) -> StorageBackendResult<()> { ... }
    fn contains_prefix_budgeted(
        &self,
        prefix: &[u8],
        control: &StorageReadControl,
    ) -> StorageBackendResult<bool> { ... }
    fn contains_key(&self, key: &[u8]) -> StorageBackendResult<bool> { ... }
    fn scan_prefix_after(
        &self,
        prefix: &[u8],
        after: Option<&[u8]>,
        limit: usize,
    ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>> { ... }
    fn scan_prefix_keys_after(
        &self,
        prefix: &[u8],
        after: Option<&[u8]>,
        limit: usize,
    ) -> StorageBackendResult<Vec<Vec<u8>>> { ... }
    fn first_prefix_after(
        &self,
        prefix: &[u8],
        after: Option<&[u8]>,
    ) -> StorageBackendResult<Option<(Vec<u8>, Vec<u8>)>> { ... }
    fn begin_transaction(&self) -> StorageBackendResult<()> { ... }
    fn begin_read_transaction(&self) -> StorageBackendResult<()> { ... }
    fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()> { ... }
    fn change_version(&self) -> StorageBackendResult<Option<u64>> { ... }
    fn read_view_revision(
        &self,
    ) -> StorageBackendResult<Option<KeyValueReadRevision>> { ... }
    fn change_version_monitor_is_nonblocking(
        &self,
    ) -> StorageBackendResult<bool> { ... }
    fn pin_transaction_snapshot(&self) -> StorageBackendResult<()> { ... }
    fn refresh_transaction_snapshot(
        &self,
        _cancellation: &CancellationToken,
    ) -> StorageBackendResult<()> { ... }
    fn commit_transaction(&self) -> StorageBackendResult<()> { ... }
    fn rollback_transaction(&self) -> StorageBackendResult<()> { ... }
    fn savepoint(&self, _name: &str) -> StorageBackendResult<()> { ... }
    fn release_savepoint(&self, _name: &str) -> StorageBackendResult<()> { ... }
    fn rollback_to_savepoint(&self, _name: &str) -> StorageBackendResult<()> { ... }
}

Ordered byte-key storage used by Key/Value catalog and index backends.

Required Methods

fn get(&self, key: &[u8]) -> StorageBackendResult<Option<Vec<u8>>>

fn put(&self, key: &[u8], value: &[u8]) -> StorageBackendResult<()>

fn delete(&self, key: &[u8]) -> StorageBackendResult<()>

fn scan_prefix( &self, prefix: &[u8], ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>>

fn delete_prefix(&self, prefix: &[u8]) -> StorageBackendResult<usize>

fn batch(&self) -> Box<dyn KeyValueBatch + '_>

fn in_transaction(&self) -> bool

fn transaction_has_written(&self) -> StorageBackendResult<bool>

Report ordinary record and derived-index writes, excluding typed auxiliary notification effects. Ordinary writes remain forbidden in read-only transactions.

Provided Methods

fn resource_leases(&self) -> Option<&dyn ResourceLeaseProvider>

Physical resource ownership for retained builds and recovery. Versioned wrappers must forward this capability.

fn auxiliary_encryption_key(&self) -> Option<StorageEncryptionKey>

Credential for database-owned auxiliary files. Wrappers over an encrypted store must forward it; None permits unencrypted auxiliary storage.

fn retention_control(&self) -> Option<StorageReadControl>

Shared session allowance, including resources retained by readers after their producer finishes. Versioned wrappers must forward this capability.

fn notification_publications(&self) -> Option<&dyn NotificationPublicationStore>

Atomic auxiliary notification publication and fresh committed recovery. Session wrappers must forward this capability.

fn serializable_session(&self) -> Option<&dyn SerializableSession>

Original participant admission and logical observations. Wrappers must forward this capability, including original attribution on retained read-only sessions; capability presence does not establish complete SQL SSI support.

fn reclaim_obsolete(&self) -> StorageBackendResult<()>

Reclaim obsolete records and committed history without a whole-file rewrite. Versioned wrappers must forward maintenance; serialized stores that eagerly remove obsolete values may keep the default.

fn vacuum(&self) -> StorageBackendResult<()>

Reclaim obsolete records and compact physical storage where supported, outside this session’s transaction.

fn write_cancellation(&self) -> Option<CancellationToken>

Token shared with the execution that owns this session’s writes. Cancellation must not prevent rollback cleanup or diagnostic reads. Versioned wrappers must forward this capability.

fn open_controlled_session( &self, _control: &StorageReadControl, ) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Open an independent writer sharing the invoking maintenance operation’s allowance and write cancellation. Retained reads and cleanup keep independent cancellation. Capable wrappers must forward this without granting another memory limit.

fn open_session_with_cancellation( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Create a transaction-isolated session with the caller’s write cancellation and a fresh retention budget.

fn open_retained_read_session( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Retain this exact committed/private view in a separate read-only session, including its original logical reader attribution. The returned session cannot publish records or complete the source transaction. Versioned wrappers must forward this capability; opening a newer independent snapshot is not equivalent.

fn transaction_model(&self) -> StorageTransactionModel

Whether writes remain private while independent sessions read and write. Versioned stores must provide command refresh, retained reads, savepoint undo and conditional publication under one reported affinity.

fn identifier_allocator(&self) -> Option<&dyn IdentifierAllocator>

Durable reservations outside private record undo. Serialized custom stores may omit this capability; wrappers over a capable store must forward it.

fn with_read_view( &self, _read: &mut KeyValueReadScope<'_>, ) -> StorageBackendResult<()>

Evaluate a compound read once against one fixed committed/private view. The callback must use the supplied reader and must not reenter this session. Stores without this capability reject it explicitly.

fn with_mutation( &self, _mutate: &mut KeyValueMutation<'_>, ) -> StorageBackendResult<()>

Evaluate once against the same view that supplies write preconditions, then atomically stage the batch. Errors and unwinds discard that batch; failed publication retains the evaluated attempt. The callback must not reenter this session or perform transaction control.

fn with_versioned_mutation( &self, _mutate: &mut KeyValueVersionedMutation<'_>, ) -> StorageBackendResult<()>

Evaluate and stage once with the actual durable writer and a non-reused mutation revision. Origins may be persisted alongside canonical values, but do not prove publication or visibility. The callback has the same non-reentrancy rules as with_mutation; capable wrappers must preserve the original origin and atomic batch.

fn transaction_affinity(&self) -> Option<StorageSessionAffinity>

Identity of the transaction context shared by this store’s catalog and data handles. Independent sessions must report different identities, even over the same file.

fn storage_identity( &self, ) -> StorageBackendResult<Option<PersistentStorageIdentity>>

fn open_session(&self) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Open an independent transaction session over the same logical store. The default keeps simple test/custom stores source-compatible while making the missing MVCC capability explicit when a persistent engine needs a committed reader alongside a pinned statement snapshot.

fn visit_value( &self, _key: &[u8], control: &StorageReadControl, _visit: &mut ValueReadVisitor<'_>, ) -> StorageBackendResult<()>

Visit one borrowed value under the retained read. Providers reserve any temporary encoded payload before fetching it; callbacks must not reenter the store.

fn visit_value_bounded( &self, _key: &[u8], _max_bytes: usize, control: &StorageReadControl, _visit: &mut ValueReadVisitor<'_>, ) -> StorageBackendResult<()>

Visit one value with an encoded-size cap checked before provider materialization. This is distinct from the shared workspace allowance; unsupported stores must not fetch an unbounded value as a fallback.

fn visit_prefix_after( &self, _prefix: &[u8], _after: Option<&[u8]>, _limit: usize, control: &StorageReadControl, _visit: &mut KeyValueReadVisitor<'_>, ) -> StorageBackendResult<()>

Visit at most limit entries in key order, strictly after after when supplied. Encoded values remain borrowed from their provider owner and callbacks must not reenter the store.

fn contains_prefix_budgeted( &self, prefix: &[u8], control: &StorageReadControl, ) -> StorageBackendResult<bool>

Test prefix existence under the read allowance. Providers that materialize values should implement a key-only probe.

fn contains_key(&self, key: &[u8]) -> StorageBackendResult<bool>

fn scan_prefix_after( &self, prefix: &[u8], after: Option<&[u8]>, limit: usize, ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>>

Return at most limit key/value pairs in key order, strictly after after when supplied. This is the bounded value cursor used by large format migrations and other paged consumers.

fn scan_prefix_keys_after( &self, prefix: &[u8], after: Option<&[u8]>, limit: usize, ) -> StorageBackendResult<Vec<Vec<u8>>>

Return at most limit keys in key order, strictly after after when it is present. Backends should override this method with a key-only, bounded range scan so cursor consumers neither materialize the entire prefix nor read values they do not need on every page.

fn first_prefix_after( &self, prefix: &[u8], after: Option<&[u8]>, ) -> StorageBackendResult<Option<(Vec<u8>, Vec<u8>)>>

fn begin_transaction(&self) -> StorageBackendResult<()>

fn begin_read_transaction(&self) -> StorageBackendResult<()>

fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()>

fn change_version(&self) -> StorageBackendResult<Option<u64>>

fn read_view_revision( &self, ) -> StorageBackendResult<Option<KeyValueReadRevision>>

Complete committed/private visibility identity, including savepoint undo. None requires consumers to use their existing refresh path. Tokens are process-local and do not replace transaction isolation or logical read observations.

fn change_version_monitor_is_nonblocking(&self) -> StorageBackendResult<bool>

fn pin_transaction_snapshot(&self) -> StorageBackendResult<()>

fn refresh_transaction_snapshot( &self, _cancellation: &CancellationToken, ) -> StorageBackendResult<()>

Advance an active logical transaction’s committed view while preserving its private writes and retained readers. The caller chooses command boundaries allowed by SQL isolation. Stores without this capability must reject the request; ending or replaying the caller’s transaction is not a valid fallback.

fn commit_transaction(&self) -> StorageBackendResult<()>

fn rollback_transaction(&self) -> StorageBackendResult<()>

fn savepoint(&self, _name: &str) -> StorageBackendResult<()>

fn release_savepoint(&self, _name: &str) -> StorageBackendResult<()>

fn rollback_to_savepoint(&self, _name: &str) -> StorageBackendResult<()>

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl KeyValueStore for MemoryKeyValueStore

impl KeyValueStore for VersionedKeyValueStore