NAME
Object::Cache::Sqlite - SQLite-based object cache with automatic expiration
SYNOPSIS
use Object::Cache::Sqlite;
my $cache = Object::Cache::Sqlite->new(
db_file => '/tmp/cache.sqlite',
);
my $scalar = 42;
my $list_ref = [ 1, 3, 5, 7, 9 ];
my $hash_ref = { name => 'John', email => 'john@example.com' };
my $cache_key = "user:123";
# Store some data for 15 minutes
$cache->set('age' , $scalar , time() + 900);
$cache->set('ids' , $list_ref, time() + 900);
$cache->set($cache_key, $hash_ref, time() + 900);
# Retrieve a value
my $user = $cache->get($cache_key);
# Delete a value
$cache->delete($cache_key);
# Get cache statistics
my $count = $cache->cached_item_count();
my $keys = $cache->cached_item_keys();
# Cleanup expired entries
$cache->remove_expired_entries();
# Clear entire cache
$cache->empty_cache();DESCRIPTION
Object::Cache::Sqlite provides a simple, fast object cache backed by SQLite. Data is automatically expired based on TTL values. Uses Cpanel::JSON::XS for fast, portable serialization.
CONSTRUCTOR
new(%args)
Creates a new cache object. Required arguments:
- db_file
-
Path to the SQLite database file. The file will be created if it doesn't exist.
Optional arguments:
- silent
-
If true, suppresses initialization messages. Default: 1
METHODS
get($key)
Retrieves a cached value by key. Returns undef if the key doesn't exist or has expired.
set($key, $value, $expires)
Stores a value in the cache. $expires is the time-to-live in seconds. If $expires is less than 100000, it's treated as relative (seconds from now). If $expires is 100000 or greater, it's treated as an absolute Unix timestamp.
Returns true on success.
delete($key)
Removes a single entry from the cache. Returns true on success.
cached_item_count()
Returns the number of non-expired entries in the cache.
cached_item_keys()
Returns an arrayref of all non-expired cache keys.
remove_expired_entries($vacuum)
Deletes all expired entries from the cache. If $vacuum is true (default), runs SQLite VACUUM to reclaim space.
empty_cache()
Deletes ALL entries from the cache and runs VACUUM. Returns the number of deleted entries.
EXPIRATION
Cache entries can have two types of expiration:
- Relative TTL
-
Values less than 100000 are treated as seconds from now.
- Absolute timestamp
-
Values 100000 or greater are treated as Unix timestamps.
Expired entries are automatically cleaned up on cache hits and can be manually cleaned with remove_expired_entries().
SEE ALSO
AUTHOR
Scott Baker - https://www.perturb.org/
LICENSE AND COPYRIGHT
This software is copyright (c) 2026 by Scott Baker.
This is free software; you can redistribute it and/or modify it under the terms of the MIT License.