Struct DbQuery 

pub struct DbQuery<T, C = PostcardCodec>
where
    C: CacheCodec,
{ /* private fields */ }

A cacheable database query descriptor.

The descriptor is deliberately explicit: callers choose the key, tags, and TTL that match their freshness model. An operation name is optional and used only for diagnostics. fetch_with executes the supplied loader only on a cache miss.

Implementations

impl<T, C> DbQuery<T, C>

where C: CacheCodec,

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

Return the optional diagnostic operation name.

pub fn with_name(self, name: impl Into<String>) -> DbQuery<T, C>

Set or replace the diagnostic operation name.

pub fn namespace(&self) -> &str

Return the namespace used for physical cache keys.

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

Return the logical key, if one has been configured.

pub fn physical_key(&self) -> Option<String>

Return the physical cache key, including the adapter namespace.

pub fn tags_value(&self) -> &[String]

Return the configured tags.

pub fn ttl_value(&self) -> Option<Duration>

Return the configured per-entry TTL.

pub fn key(self, key: impl Into<String>) -> DbQuery<T, C>

Set the logical cache key for this query result.

pub fn key_builder(self, key: CacheKeyBuilder) -> DbQuery<T, C>

Set the logical cache key from a segmented key builder.

pub fn tag(self, tag: impl Into<String>) -> DbQuery<T, C>

Add one invalidation tag.

pub fn tags<I, S>(self, tags: I) -> DbQuery<T, C>

where I: IntoIterator<Item = S>, S: Into<String>,

Add several invalidation tags.

pub fn tag_set(self, tags: TagSet) -> DbQuery<T, C>

Replace invalidation tags from a reusable TagSet.

pub fn ttl(self, ttl: Duration) -> DbQuery<T, C>

Set a per-entry TTL for this query result.

pub async fn fetch_with<E, F, Fut>(self, loader: F) -> Result<T, DbCacheError>

where T: Serialize + DeserializeOwned + Send + 'static, E: Error + Send + Sync + 'static, F: FnOnce() -> Fut + Send + 'static, Fut: Future<Output = Result<T, E>> + Send + 'static,

Fetch a cached value or run the supplied database loader on miss.

The loader is intentionally caller-supplied so the database library remains responsible for pools, transactions, compile-time checked queries, and row mapping. HydraCache owns only the cache boundary.

pub async fn fetch_value_with<U, E, F, Fut>( self, loader: F, ) -> Result<U, DbCacheError>

where U: Serialize + DeserializeOwned + Send + 'static, E: Error + Send + Sync + 'static, F: FnOnce() -> Fut + Send + 'static, Fut: Future<Output = Result<U, E>> + Send + 'static,

Fetch a cached value with an output type chosen by an adapter.

Most application code should use DbQuery::fetch_with. This method is intended for adapter crates that keep the descriptor type focused on a database row while caching shapes such as Option<T> or Vec<T>.

Trait Implementations

impl<T, C> Clone for DbQuery<T, C>

where C: CacheCodec,

fn clone(&self) -> DbQuery<T, C>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, C> Debug for DbQuery<T, C>

where C: CacheCodec,

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

Formats the value using the given formatter.

impl<T, C> SqlxQueryExt<T, C> for DbQuery<T, C>

where C: CacheCodec,

fn fetch_one<'q, 'async_trait, DB, A, E>( self, executor: E, query: QueryAs<'q, DB, T, A>, ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>

where T: Serialize + DeserializeOwned + Send + Unpin + for<'r> FromRow<'r, DB::Row> + 'static, DB: Database + Send + Sync + 'static + 'async_trait, A: IntoArguments<'q, DB> + Send + 'static + 'async_trait, E: Send + Sync + 'static + 'async_trait, for<'c> &'c E: Executor<'c, Database = DB>, Self: 'async_trait, 'q: 'static + 'async_trait,

Execute a SQLx query on miss and cache exactly one row.

fn fetch_optional<'q, 'async_trait, DB, A, E>( self, executor: E, query: QueryAs<'q, DB, T, A>, ) -> Pin<Box<dyn Future<Output = Result<Option<T>>> + Send + 'async_trait>>

where T: Serialize + DeserializeOwned + Send + Unpin + for<'r> FromRow<'r, DB::Row> + 'static, DB: Database + Send + Sync + 'static + 'async_trait, A: IntoArguments<'q, DB> + Send + 'static + 'async_trait, E: Send + Sync + 'static + 'async_trait, for<'c> &'c E: Executor<'c, Database = DB>, Self: 'async_trait, 'q: 'static + 'async_trait,

Execute a SQLx query on miss and cache either one row or None.

fn fetch_all<'q, 'async_trait, DB, A, E>( self, executor: E, query: QueryAs<'q, DB, T, A>, ) -> Pin<Box<dyn Future<Output = Result<Vec<T>>> + Send + 'async_trait>>

where T: Serialize + DeserializeOwned + Send + Unpin + for<'r> FromRow<'r, DB::Row> + 'static, DB: Database + Send + Sync + 'static + 'async_trait, A: IntoArguments<'q, DB> + Send + 'static + 'async_trait, E: Send + Sync + 'static + 'async_trait, for<'c> &'c E: Executor<'c, Database = DB>, Self: 'async_trait, 'q: 'static + 'async_trait,

Execute a SQLx query on miss and cache all returned rows.