Struct QueryCachePolicy 

pub struct QueryCachePolicy { /* private fields */ }

Reusable cache metadata for one database query result.

QueryCachePolicy contains the database-neutral parts of query result caching: diagnostic name, logical key, invalidation tags, and optional TTL. It is intentionally independent of SQLx, Diesel, SeaORM, or any other database client.

Example

use std::time::Duration;

use hydracache_db::QueryCachePolicy;

let policy = QueryCachePolicy::named("load-user")
    .key("user:42")
    .tag("user:42")
    .ttl(Duration::from_secs(60));

assert_eq!(policy.name(), Some("load-user"));
assert_eq!(policy.key_value(), Some("user:42"));
assert_eq!(policy.tags_value(), &["user:42".to_owned()]);
assert_eq!(policy.ttl_value(), Some(Duration::from_secs(60)));

The query_cache_policy! macro provides a shorter declarative form when the policy is known at the call site.

Implementations

impl QueryCachePolicy

pub fn new() -> Self

Create an empty cache policy.

pub fn short_lived() -> Self

Create a short-lived policy for values that should smooth brief bursts.

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

Example

use std::time::Duration;

use hydracache_db::QueryCachePolicy;

let policy = QueryCachePolicy::short_lived().key("user:42");

assert_eq!(policy.ttl_value(), Some(Duration::from_secs(30)));
assert_eq!(policy.key_value(), Some("user:42"));

pub fn read_mostly() -> Self

Create a read-mostly 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() -> Self

Create a policy intended for one entity-shaped result.

The preset uses a 5 minute TTL and expects the caller to add an entity key/tag with QueryCachePolicy::for_entity or QueryCachePolicy::for_cache_entity.

pub fn no_ttl_explicit_invalidation() -> Self

Create a policy for explicit-invalidation-only values.

No TTL is configured. The value remains cached until the caller invalidates a key/tag, removes it, flushes the cache, or the backend evicts it due to capacity pressure.

pub fn negative_cache() -> Self

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

Create a cache policy with a diagnostic operation name.

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

Return the optional diagnostic operation name.

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

Return the logical key, if one has been configured.

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

Return configured 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 required_dimensions_value(&self) -> &[String]

Return statically declared key dimensions required by this policy.

These labels are diagnostics only; values are intentionally not stored.

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

Return static key dimension labels recorded by macro/profile tooling.

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

Return static tag dimension labels recorded by macro/profile tooling.

pub fn dimension_profile(&self) -> Option<&DimensionProfile>

Return the optional required-dimension profile.

pub fn dimension_validation_mode(&self) -> DimensionValidationMode

Return the profile validation mode.

pub fn lint_metadata(&self) -> Option<&PolicyLintMetadata>

Return optional SQL dependency-lint metadata for CI/build-time tooling.

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

Set or replace the diagnostic operation name.

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

Set the logical cache key.

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 the same entity invalidation tag.

pub fn for_cache_entity<T>(self, id: T::Id) -> Self

where T: CacheEntity,

Set the logical key and tags from CacheEntity metadata.

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.

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.

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

Set refresh/stale behavior for this query result.

pub fn required_dimensions<I, S>(self, dimensions: I) -> Self

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

Store statically declared key dimensions for diagnostics and review.

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

Add one statically declared key dimension for diagnostics and review.

pub fn with_key_dimension_labels<I, S>(self, labels: I) -> Self

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

Store key dimension labels for profile validation.

pub fn with_tag_dimension_labels<I, S>(self, labels: I) -> Self

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

Store tag dimension labels for profile validation.

pub fn with_dimension_profile(self, profile: DimensionProfile) -> Self

Attach a reusable required-dimension profile.

pub fn with_dimension_validation_mode( self, mode: DimensionValidationMode, ) -> Self

Set whether profile violations should warn or fail a CI/release gate.

pub fn allow_dimension_violation( self, label: impl Into<String>, reason: impl Into<String>, ) -> Result<Self, DimensionAllowError>

Allow one profile dimension violation with an explicit review reason.

pub fn validate_dimension_profile(&self) -> ProfileValidation

Validate the configured profile against recorded key/tag labels.

pub fn enforce_dimension_profile(&self) -> Result<()>

Return an error when profile validation is in deny mode and fails.

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

Attach SQL text for off-runtime dependency linting.

pub fn dependency_lint_mode(self, mode: DeclaredLintMode) -> Self

Set the lint mode used by CI/build-time dependency checking.

pub fn declared_dependency(self, relation: DeclaredRelation) -> Self

Declare one relation that the query is expected to read.

pub fn declared_dependencies<I>(self, relations: I) -> Self

where I: IntoIterator<Item = DeclaredRelation>,

Declare several relations that the query is expected to read.

pub fn lint_allow(self, finding: LintFinding, reason: impl Into<String>) -> Self

Suppress one dependency-lint finding with an explicit reason.

Trait Implementations

impl Clone for QueryCachePolicy

fn clone(&self) -> QueryCachePolicy

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for QueryCachePolicy

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

Formats the value using the given formatter.

impl Default for QueryCachePolicy

fn default() -> QueryCachePolicy

Returns the “default value” for a type.

impl Eq for QueryCachePolicy

impl PartialEq for QueryCachePolicy

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for QueryCachePolicy