Struct DbCache 

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

A database-oriented view over a HydraCache instance.

DbCache groups query result keys under a namespace while keeping all cache storage, single-flight, tags, TTL, and stats in the shared local cache.

Example

use std::time::Duration;

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

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

let local = HydraCache::local().build();
let queries = DbCache::new(local, "db");

let user = queries
    .entity::<User>("user", 42)
    // Later, invalidate_tag("user:42") removes this result.
    .collection_tag("users")
    .ttl(Duration::from_secs(60))
    .fetch_with(|| async {
        // Replace this block with code from sqlx, diesel, sea-orm, or any
        // other database client. It is called only when the cache does not
        // already contain "db:user:42" or when the cached value has expired.
        Ok::<_, std::io::Error>(User {
            id: 42,
            name: "Ada".to_owned(),
        })
    })
    .await?;

assert_eq!(user.id, 42);

Implementations

impl<C> DbCache<C>

where C: CacheCodec,

pub fn new(cache: HydraCache<C>, namespace: impl Into<String>) -> DbCache<C>

Create a database query cache adapter over an existing local cache.

pub fn namespace(&self) -> &str

Return the namespace used for physical cache keys.

pub fn cache(&self) -> &HydraCache<C>

Return the underlying local cache.

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

Start describing a cacheable database-loaded value.

This is the preferred entry point when the query is already visible inside the fetch_with loader through a database client, ORM, or repository method.

pub fn cached_with<T>(&self, policy: QueryCachePolicy) -> DbQuery<T, C>

Start describing a cacheable database-loaded value with a reusable QueryCachePolicy.

This is useful when the same key/tag/TTL pattern is shared by a repository method, a SQLx call site, and a future ORM adapter.

pub fn entity<T>(&self, kind: impl ToString, id: impl ToString) -> DbQuery<T, C>

Start describing an entity-shaped cached value.

This is a convenience layer over DbCache::cached that sets both the logical key and the entity invalidation tag from escaped key segments. For example, entity::<User>("user", 42) creates key user:42 and tag user:42; with namespace db, the physical cache key is db:user:42.

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

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

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

where T: CacheEntity,

Start describing an entity-shaped cached value from CacheEntity metadata.

This helper removes repeated entity and collection literals from call sites. It sets the logical key, 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.for_entity::<User>(42);

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

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

Start describing a collection-shaped cached value.

This sets both the logical key and the collection invalidation tag to the escaped collection name. For example, collection::<User>("users") creates key users and tag users.

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.collection::<User>("users:active");

assert_eq!(query.key_value(), Some("users%3Aactive"));
assert_eq!(query.tags_value(), &["users%3Aactive".to_owned()]);
assert_eq!(query.physical_key(), Some("db:users%3Aactive".to_owned()));

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

Start describing a cacheable database-loaded value with a diagnostic name.

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

Start describing a cacheable SQL query result.

Prefer DbCache::cached or DbCache::named when writing new code. This method remains useful if you want the SQL text itself to be the diagnostic label for errors and logs.

Trait Implementations

impl<C> Clone for DbCache<C>

where C: CacheCodec,

fn clone(&self) -> DbCache<C>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C> Debug for DbCache<C>

where C: CacheCodec,

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

Formats the value using the given formatter.