Struct CacheConfig 

pub struct CacheConfig {
    pub enabled: bool,
    pub max_entries: usize,
    pub ttl_seconds: u64,
    pub cache_list_queries: bool,
    pub rls_enforcement: RlsEnforcement,
    pub max_entry_bytes: Option<usize>,
    pub max_total_bytes: Option<usize>,
}

Cache configuration - disabled by default as of v2.0.0-rc.12.

FraiseQL’s architecture (precomputed views + optimized PostgreSQL) makes caching unnecessary for most use cases. Enable only for federation or expensive computations.

Key Changes in rc.12

• enabled now defaults to false (was true)
• with_max_entries() and with_ttl() also set enabled: false
• New enabled() constructor for explicit opt-in

See module documentation for detailed guidance.

Fields

enabled: bool

Enable response caching.

Default: false (changed from true in v2.0.0-rc.12)

Enable only for:

• Federation with slow external services
• Expensive computations not covered by precomputed views
• High-frequency repeated queries with identical parameters

See Issue #40 for performance analysis.

max_entries: usize

Maximum number of cached entries.

When this limit is reached, the least-recently-used (LRU) entry is evicted to make room for new entries. This hard limit prevents unbounded memory growth.

Recommended values:

• Development: 1,000
• Production (small): 10,000
• Production (large): 50,000

Default: 10,000 entries (~100 MB estimated memory)

ttl_seconds: u64

Time-to-live (TTL) in seconds for cached entries.

Entries older than this are considered expired and will be removed on next access. This acts as a safety net for cases where invalidation might be missed (e.g., database changes outside of mutations).

Recommended values:

• Development: 3,600 (1 hour)
• Production: 86,400 (24 hours)
• Long-lived data: 604,800 (7 days)

Default: 86,400 seconds (24 hours)

cache_list_queries: bool

Whether to cache list queries.

List queries (e.g., users(limit: 100)) can have large result sets that consume significant memory. Set to false to only cache single-object queries (results with a single row). Results with more than one row are skipped.

Default: true

rls_enforcement: RlsEnforcement

Row-Level Security enforcement mode for multi-tenant deployments.

When caching is enabled alongside a multi-tenant schema (detected via is_multi_tenant() on the compiled schema), FraiseQL checks that RLS is active. Without RLS, two users sharing the same query may receive each other’s data from the cache.

Mode	Behaviour
Error	Server refuses to start (default, safest)
Warn	Logs a warning and continues
Off	Skips the check (single-tenant deployments)

Default: RlsEnforcement::Error

max_entry_bytes: Option<usize>

Maximum bytes for a single cache entry. Entries exceeding this are silently skipped.

Prevents a single oversized response from consuming a disproportionate share of the cache. The size is estimated by serializing the result to JSON and measuring the byte length.

Default: None (no per-entry limit). Suggested value: 10 MB (10_485_760).

max_total_bytes: Option<usize>

Maximum total bytes across all cache entries. Triggers LRU eviction when exceeded.

When set, put() checks whether adding the new entry would exceed the budget. If the budget is already exceeded the entry is silently skipped (the LRU count limit continues to apply independently).

Default: None (no total limit). Suggested value: 1 GB (1_073_741_824).

Implementations

impl CacheConfig

pub const fn with_max_entries(max_entries: usize) -> Self

Create cache configuration with custom max entries.

Uses default values for other fields (enabled=false, 24h TTL).

Arguments

• max_entries - Maximum number of entries in cache

Example

use fraiseql_core::cache::CacheConfig;

let config = CacheConfig::with_max_entries(50_000);
assert_eq!(config.max_entries, 50_000);
assert!(!config.enabled); // Disabled by default

pub const fn with_ttl(ttl_seconds: u64) -> Self

Create cache configuration with custom TTL.

Uses default values for other fields (enabled=false, 10,000 entries).

Arguments

• ttl_seconds - Time-to-live in seconds

Example

use fraiseql_core::cache::CacheConfig;

let config = CacheConfig::with_ttl(3_600);  // 1 hour
assert_eq!(config.ttl_seconds, 3_600);
assert!(!config.enabled); // Disabled by default

pub const fn enabled() -> Self

Create cache configuration with caching enabled.

Use this method when you explicitly need caching (e.g., federation, expensive computations). Most FraiseQL deployments don’t need this.

Example

use fraiseql_core::cache::CacheConfig;

let config = CacheConfig::enabled();
assert!(config.enabled);
assert_eq!(config.max_entries, 10_000);

pub const fn disabled() -> Self

Create cache configuration with caching disabled.

This is now the default behavior. Use this method for explicit clarity or to override a previously enabled configuration.

Example

use fraiseql_core::cache::CacheConfig;

let config = CacheConfig::disabled();
assert!(!config.enabled);

pub const fn estimated_memory_bytes(&self) -> usize

Estimate memory usage in bytes for this configuration.

This is a rough estimate assuming average entry size of 10 KB. Actual memory usage will vary based on query result sizes.

Returns

Estimated memory usage in bytes

Example

use fraiseql_core::cache::CacheConfig;

let config = CacheConfig::default();
let estimated_bytes = config.estimated_memory_bytes();
println!("Estimated memory: {} MB", estimated_bytes / 1_000_000);

Trait Implementations

impl Clone for CacheConfig

fn clone(&self) -> CacheConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CacheConfig

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

Formats the value using the given formatter.

impl Default for CacheConfig

fn default() -> Self

Default cache configuration - DISABLED by default as of v2.0.0-rc.12.

FraiseQL uses precomputed views (tv_* tables) and optimized PostgreSQL queries that are typically faster than cache overhead for most use cases.

Enable caching ONLY if you have:

• Federation with slow external services
• Expensive computations not covered by precomputed views
• High-frequency repeated queries (>1000 QPS with same params)

See Issue #40 for performance analysis.

Current Default

• Caching: DISABLED
• 10,000 max entries (~100 MB if enabled)
• 24 hour TTL
• List queries cached (when enabled)

impl<'de> Deserialize<'de> for CacheConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CacheConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for CacheConfig