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 for_entity(self, kind: impl ToString, id: impl ToString) -> DbQuery<T, C>

Set the logical key and add an entity invalidation tag.

for_entity("user", 42) sets the key to user:42 and adds the tag user:42. Both segments are escaped with CacheKeyBuilder, so : and % inside one segment cannot accidentally create extra key segments.

Example

use hydracache::HydraCache;
use hydracache_db::DbCache;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct User {
    id: i64,
}

let queries = DbCache::new(HydraCache::local().build(), "db");
let query = queries
    .cached::<User>()
    .tag("users")
    .for_entity("user", 42);

assert_eq!(query.key_value(), Some("user:42"));
assert_eq!(
    query.tags_value(),
    &["users".to_owned(), "user:42".to_owned()]
);

pub fn for_cache_entity(self, id: <T as CacheEntity>::Id) -> DbQuery<T, C>

where T: CacheEntity,

Set the logical key and tags from CacheEntity metadata.

This is the metadata-driven equivalent of DbQuery::for_entity. It preserves any existing tags, then adds the entity tag and optional collection tag defined by T.

Example

use hydracache::HydraCache;
use hydracache_db::{CacheEntity, DbCache};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct User {
    id: i64,
}

impl CacheEntity for User {
    type Id = i64;

    const ENTITY: &'static str = "user";
    const COLLECTION: Option<&'static str> = Some("users");
}

let queries = DbCache::new(HydraCache::local().build(), "db");
let query = queries
    .cached::<User>()
    .tag("tenant:7")
    .for_cache_entity(42);

assert_eq!(query.key_value(), Some("user:42"));
assert_eq!(
    query.tags_value(),
    &[
        "tenant:7".to_owned(),
        "user:42".to_owned(),
        "users".to_owned()
    ]
);

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

Add one invalidation tag.

pub fn collection_tag(self, name: impl ToString) -> DbQuery<T, C>

Add a collection invalidation tag from one escaped key segment.

Use this with DbCache::entity or DbQuery::for_entity when one entity result also belongs to a broader list or query group.

Example

use hydracache::HydraCache;
use hydracache_db::DbCache;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct User {
    id: i64,
}

let queries = DbCache::new(HydraCache::local().build(), "db");
let query = queries
    .entity::<User>("user", 42)
    .collection_tag("users:active");

assert_eq!(
    query.tags_value(),
    &["user:42".to_owned(), "users%3Aactive".to_owned()]
);

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.