/ 
DBIx-Fast-0.17
/ DBIx::Fast::Cache

NAME

DBIx::Fast::Cache - Query result cache with TTL and tag invalidation

SYNOPSIS

use DBIx::Fast::Cache;

my $cache = DBIx::Fast::Cache->new(
    max_size    => 10_000,
    default_ttl => 60,
    backend     => 'LRU',
);

$cache->set('product:42', $row, ttl => 300, tags => ['products']);
my $row = $cache->get('product:42');

$cache->invalidate('products');      # drop everything tagged 'products'
$cache->delete('product:42');        # drop one key
$cache->clear;                       # drop everything

my $s = $cache->stats;
printf "hit ratio: %.2f%%\n", $s->{hit_ratio} * 100;

DESCRIPTION

In-process query cache used by DBIx::Fast. Default backend is LRU::Cache (XS, ~120 ns per operation). TTL is layered on top by wrapping every stored value as [$value, $expires_at, \@tags].

For multi-process deployments, pass a pre-built CHI instance as backend - the same API is preserved.

OPTIONS

max_size

Maximum number of keys before LRU eviction kicks in. Default: 1_000.

default_ttl

Seconds before a value is considered expired. 0 disables expiry. Default: 60.

backend

'LRU' (default, requires LRU::Cache), or a pre-built object that responds to get/set/delete/clear (typically a CHI instance). For CHI backends the TTL is also passed to the backend's set, so the external store (Redis/Memcached) expires entries physically instead of holding logically-expired data until eviction.

METHODS

get / set / delete / clear / invalidate

See "SYNOPSIS".

stats

Returns a hashref: hits, misses, sets, evictions, expirations, invalidations, total, hit_ratio, index_pairs.

evictions counts backend evictions as they are detected (the backend evicts silently; a tracked key found missing during invalidate or an index sweep counts here - for CHI backends this includes backend-side expiry). index_pairs is the current size of the tag index in key-tag pairs; it is swept automatically when it outgrows the cache capacity.

reset_stats

Zeroes all counters.

build_key ($sql, \@params)

Stable cache key derived from SQL + bind parameters. Used internally by DBIx::Fast's cached() proxy.

THREAD SAFETY

This is an in-process cache: a single instance must not be shared across threads (ithreads) - the tag index and the default LRU::Cache backend are not synchronised. Use one cache per thread, or for cross-process/cross-thread sharing pass a CHI instance (e.g. Redis/Memcached) as backend. Preforking workers each get their own cache, which is fine but not shared.

SHARED BACKENDS

The tag index used by invalidate lives in the process, even when the backend is shared (CHI/Redis): invalidate($tag) only drops the keys this process has set under that tag. With DBIx::Fast's CRUD auto-invalidation every writing worker prunes its own entries, so shared deployments converge as long as all writers run through DBIx::Fast; entries written by other processes are otherwise bounded by their TTL (which is enforced both logically on get and physically in the CHI store).

SECURITY

Keys built by DBIx::Fast's cached() proxy include the connection identity (DSN and DB user), so instances pointing at different databases or connecting as different users never serve each other's rows even when they share one external backend. If you call get/set directly with your own keys on a shared backend, include an equivalent namespace yourself. Note that cached results are served without re-checking the database's per-user permissions.

AUTHOR

SeHarrys

LICENSE

This is free software under the Artistic License 2.0.