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() -> QueryCachePolicy

Create an empty cache policy.

pub fn short_lived() -> QueryCachePolicy

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() -> QueryCachePolicy

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() -> QueryCachePolicy

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() -> QueryCachePolicy

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() -> QueryCachePolicy

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

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

Set or replace the diagnostic operation name.

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

Set the logical cache key.

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

Set the logical cache key from a segmented key builder.

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

Set the logical key and add the same entity invalidation tag.

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

where T: CacheEntity,

Set the logical key and tags from CacheEntity metadata.

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

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

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

Add one invalidation tag.

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

Add a collection invalidation tag from one escaped key segment.

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

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

Add several invalidation tags.

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

Replace invalidation tags from a reusable TagSet.

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

Set a per-entry TTL.

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

Set refresh/stale behavior for this query result.

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

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>, ) -> QueryCachePolicy

Add one statically declared key dimension for diagnostics and review.

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

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

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

Store tag dimension labels for profile validation.

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

Attach a reusable required-dimension profile.

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

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<QueryCachePolicy, 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<(), DbCacheError>

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

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

Attach SQL text for off-runtime dependency linting.

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

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

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

Declare one relation that the query is expected to read.

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

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>, ) -> QueryCachePolicy

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<(), Error>

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

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 QueryCachePolicy