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>) -> Self

Set or replace the diagnostic operation name.

pub fn cache_policy(&self) -> &QueryCachePolicy

Return the reusable cache policy backing this descriptor.

pub fn with_policy(self, policy: QueryCachePolicy) -> Self

Replace the current cache policy.

This is the lowest-friction way to reuse one policy across SQLx, Diesel, SeaORM, or repository-style call sites while keeping the loader itself fully caller-controlled.

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 refresh_policy_value(&self) -> Option<RefreshOptions>

Return the configured refresh/stale policy.

pub fn adapter_kind(&self) -> DbAdapterKind

Return the database adapter kind used for operation diagnostics.

pub fn result_shape(&self) -> DbResultShape

Return the result shape used for operation diagnostics.

pub fn adapter_context( self, adapter: DbAdapterKind, result_shape: DbResultShape, ) -> Self

Set database adapter and result-shape context for diagnostics.

Most users do not need to call this directly. Adapter crates use it to label errors from helpers such as sqlx_one, diesel_optional, or sea_all without changing the cache key, tags, TTL, or loader.

pub fn key(self, key: impl Into<String>) -> Self

Set the logical cache key for this query result.

pub fn key_builder(self, key: CacheKeyBuilder) -> Self

Set the logical cache key from a segmented key builder.

pub fn for_entity(self, kind: impl ToString, id: impl ToString) -> Self

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::Id) -> Self

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 collection(self, name: impl ToString) -> Self

Set the logical key and invalidation tag for a collection result.

pub fn tag(self, tag: impl Into<String>) -> Self

Add one invalidation tag.

pub fn collection_tag(self, name: impl ToString) -> Self

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) -> Self

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

Add several invalidation tags.

pub fn tag_set(self, tags: TagSet) -> Self

Replace invalidation tags from a reusable TagSet.

pub fn ttl(self, ttl: Duration) -> Self

Set a per-entry TTL for this query result.

pub fn refresh_policy(self, refresh: RefreshOptions) -> Self

Set refresh/stale behavior for this query result.

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

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 repository/database loader on miss.

This is a short alias for DbQuery::fetch_with. It reads more naturally when a call site is wrapping a repository method rather than a raw SQL query.

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

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>

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) -> Self

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

Formats the value using the given formatter.