Struct PreparedQueryPolicy 

pub struct PreparedQueryPolicy { /* private fields */ }

Prepared database query cache metadata.

PreparedQueryPolicy stores stable query-cache metadata once and binds only the dynamic part, such as an entity id, on the hot path. It remains database-neutral: SQLx, Diesel, SeaORM, or a hand-written repository can all turn the prepared policy into the ordinary QueryCachePolicy consumed by DbCache.

Example

use std::time::Duration;

use hydracache_db::{CacheEntity, PreparedQueryPolicy};

struct User;

impl CacheEntity for User {
    type Id = i64;

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

let prepared = PreparedQueryPolicy::for_cache_entity::<User>()
    .with_name("load-user")
    .ttl(Duration::from_secs(60));

let policy = prepared.bind_id(42);
assert_eq!(policy.name(), Some("load-user"));
assert_eq!(policy.key_value(), Some("user:42"));
assert_eq!(policy.tags_value(), &["users".to_owned(), "user:42".to_owned()]);

Implementations

impl PreparedQueryPolicy

pub fn new() -> PreparedQueryPolicy

Create an empty prepared policy.

pub fn short_lived() -> PreparedQueryPolicy

Create a short-lived prepared policy for burst smoothing.

The preset uses a 30 second TTL and leaves key/tags to the caller.

pub fn read_mostly() -> PreparedQueryPolicy

Create a read-mostly prepared policy for values that change rarely.

The preset uses a 5 minute TTL. Pair it with entity or collection tags so writes can still invalidate cached results explicitly.

pub fn per_entity() -> PreparedQueryPolicy

Create a prepared policy intended for one entity-shaped result.

The preset uses a 5 minute TTL and expects the caller to add an entity prefix with PreparedQueryPolicy::entity or to start from PreparedQueryPolicy::for_cache_entity.

pub fn no_ttl_explicit_invalidation() -> PreparedQueryPolicy

Create a prepared policy for explicit-invalidation-only values.

No TTL is configured. The value remains cached until invalidated, removed, flushed, or evicted due to capacity pressure.

pub fn negative_cache() -> PreparedQueryPolicy

Create a prepared policy for caching negative lookups briefly.

Use this for Option<T> or domain-specific “not found” results where repeated misses are expensive but long-lived absence would be unsafe. The preset uses a 30 second TTL.

pub fn named(name: impl Into<String>) -> PreparedQueryPolicy

Create a prepared policy with a diagnostic operation name.

pub fn for_entity(kind: impl ToString) -> PreparedQueryPolicy

Create a prepared entity-id policy from one escaped entity segment.

The entity segment is escaped once. Each PreparedQueryPolicy::bind_id call only escapes and appends the id segment.

pub fn for_cache_entity<T>() -> PreparedQueryPolicy

where T: CacheEntity,

Create a prepared entity-id policy from CacheEntity metadata.

The entity prefix and optional collection tag are precomputed once.

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

Return the optional diagnostic operation name.

pub fn requires_id(&self) -> bool

Return true when this policy needs an id binding before it has a key.

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

Return the static logical key, if this prepared policy has one.

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

Return the precomputed entity key prefix, if this is an entity policy.

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

Return precomputed invalidation tags.

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

Return the optional per-entry TTL.

pub fn refresh_policy_value(&self) -> Option<RefreshOptions>

Return the optional refresh/stale policy.

pub fn with_name(self, name: impl Into<String>) -> PreparedQueryPolicy

Set or replace the diagnostic operation name.

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

Set a static logical key.

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

Set a static logical key from a segmented key builder.

pub fn entity(self, kind: impl ToString) -> PreparedQueryPolicy

Set an entity-id key prefix from one escaped entity segment.

pub fn cache_entity<T>(self) -> PreparedQueryPolicy

where T: CacheEntity,

Set an entity-id key prefix and optional collection tag from CacheEntity metadata while preserving preset TTL/name settings.

Example

use std::time::Duration;

use hydracache_db::{CacheEntity, PreparedQueryPolicy};

struct User;

impl CacheEntity for User {
    type Id = i64;

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

let policy = PreparedQueryPolicy::per_entity().cache_entity::<User>();

assert_eq!(policy.entity_key_prefix(), Some("user"));
assert_eq!(policy.tags_value(), &["users".to_owned()]);
assert_eq!(policy.ttl_value(), Some(Duration::from_secs(300)));

pub fn collection(self, name: impl ToString) -> PreparedQueryPolicy

Set a static collection key and add the same collection invalidation tag.

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

Add one precomputed invalidation tag.

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

Add a precomputed collection invalidation tag from one escaped segment.

pub fn tags<I, S>(self, tags: I) -> PreparedQueryPolicy

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

Add several precomputed invalidation tags.

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

Replace precomputed invalidation tags from a reusable TagSet.

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

Set a precomputed per-entry TTL.

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

Set refresh/stale behavior for this prepared query result.

pub fn to_policy(&self) -> QueryCachePolicy

Convert this prepared policy into a runtime QueryCachePolicy.

Entity-id policies still need PreparedQueryPolicy::bind_id to set a key. Static-key and collection policies can use this method directly.

pub fn bind_id(&self, id: impl ToString) -> QueryCachePolicy

Bind an id to this prepared policy and produce a runtime policy.

For entity policies, this creates the final logical key and adds the entity tag. For static-key policies, the id is ignored and PreparedQueryPolicy::to_policy behavior is used.

Trait Implementations

impl Clone for PreparedQueryPolicy

fn clone(&self) -> PreparedQueryPolicy

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PreparedQueryPolicy

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

Formats the value using the given formatter.

impl Default for PreparedQueryPolicy

fn default() -> PreparedQueryPolicy

Returns the “default value” for a type.

impl Eq for PreparedQueryPolicy

impl PartialEq for PreparedQueryPolicy

fn eq(&self, other: &PreparedQueryPolicy) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for PreparedQueryPolicy