Redis-like caching. Zero infrastructure.

Start here

Quickstart

Add the dependency and start calling it. There is no path to configure and no migration to run.

from lytecache import LyteCache

cache = LyteCache()                     # no path, no setup -- just works
cache.set("user:42", {"name": "Samson"}, ttl=300)
cache.get("user:42")                    # {"name": "Samson"}
cache.incr("hits")                      # 1

import io.lytecache.LyteCache;
import java.time.Duration;

try (LyteCache cache = new LyteCache()) {
    cache.set("user:42", "Samson", Duration.ofMinutes(5));
    cache.getString("user:42");          // "Samson"
    cache.incr("hits");                  // 1
}

import { LyteCache } from "lytecache";

const cache = new LyteCache();               // no path, no setup -- just works
cache.set("user:42", { name: "Samson" }, { ttl: 300 });
cache.get("user:42");                        // { name: "Samson" }
cache.incr("hits");                          // 1

cache, _ := lytecache.New()          // no path, no setup -- just works
defer cache.Close()

cache.Set("user:42", map[string]any{"name": "Samson"}, lytecache.TTL(5*time.Minute))
var user map[string]any
cache.Get("user:42", &user)                // {"name": "Samson"}
cache.Incr("hits", 1)                        // 1

use Lytecache\LyteCache;

$cache = new LyteCache();               // no path, no setup -- just works
$cache->set("user:42", ["name" => "Samson"], ttl: 300);
$cache->get("user:42");                 // ["name" => "Samson"]
$cache->incr("hits");                   // 1

Close the cache when you're done with it. Each language has its own idiom: with LyteCache() as cache: in Python, try (LyteCache cache = new LyteCache()) in Java, using cache = new LyteCache() in Node.js (or call cache[Symbol.dispose]() directly), and defer cache.Close() in Go. PHP closes the cache in __destruct(), so you never have to call $cache->close() yourself. Closing flushes buffered state and stops the background sweeper. PHP has no background sweeper; TTL & expiration explains what it does instead.

Start here

Your first cache

About ten minutes, one script. You'll cache a slow HTTP call, share the cache between two processes, and look at the result from a shell. The tutorial uses Python. The other four languages work the same way, and every reference group shows their method names on the toggle.

1. Install it and store one value

   Run pip install lytecache, then try the smallest program that does something:

   Python Copy

   from lytecache import LyteCache
   
   cache = LyteCache()
   cache.set("greeting", "hello")
   print(cache.get("greeting"))

   It prints hello. You didn't start a server or choose a file. The first write created the file, and step 5 shows you where it is.

2. Make a slow call twice

   Save this as slow_api.py. httpbin.org/delay/1 waits a second before it answers, standing in for any slow or rate-limited API.

   slow_api.py Copy

   import json
   import time
   import urllib.request
   
   from lytecache import LyteCache
   
   cache = LyteCache()
   URL = "https://httpbin.org/delay/1"   # waits one second on purpose
   
   
   def fetch(url):
       key = f"http:{url}"
       cached = cache.get(key)
       if cached is not None:
           return cached
       with urllib.request.urlopen(url) as resp:
           data = json.load(resp)
       cache.set(key, data)
       return data
   
   
   for attempt in (1, 2):
       start = time.perf_counter()
       fetch(URL)
       print(f"call {attempt}: {(time.perf_counter() - start) * 1000:.2f} ms")

   Terminal Copy

   $ python slow_api.py
   call 1: 1399.60 ms
   call 2: 0.10 ms

   The first call went over the network and took 1.4 seconds. The second came from the cache in a tenth of a millisecond: one SQLite read from a file on your disk. Your numbers will differ. The gap won't.

3. Give the data an expiry

   Right now the response is cached forever. Change the set line to give it a TTL:

   slow_api.py Copy

       cache.set(key, data, ttl=300)   # seconds

   Choose the number by asking how stale an answer you can live with. An exchange-rate feed that updates every few minutes is fine at 300 seconds. A user's own profile, which they expect to change the moment they edit it, shouldn't wait for a TTL at all: delete it when it changes (see Invalidate on write). The unit is seconds, so ttl=300000 would be 83 hours.

   Run the script now and both calls still hit the cache. The entry from step 2 was written without a TTL, and fetch() only writes on a miss, so your change hasn't touched it. A new TTL only applies to entries written after the change, which is worth remembering in production too. Clear the cache once and run it again:

   Terminal Copy

   $ python -c "from lytecache import LyteCache; LyteCache().flush()"
   $ python slow_api.py
   call 1: 1471.90 ms
   call 2: 0.10 ms

4. Run it from a second process

   Run the script again from the same directory, or from a second terminal:

   Terminal Copy

   $ python slow_api.py
   call 1: 0.04 ms
   call 2: 0.02 ms

   Both calls were hits. This is a brand-new process with nothing in memory, and it found the entry the last run wrote. This is where lytecache stops looking like a dictionary. The cache lives in a file, so every process that opens it shares it, and it survives restarts. A Node.js or Go program started from the same directory would read the same entry.

5. Look at it from the shell

   Install the CLI (brew install lytecache/tap/lytecache; other platforms are in Install) and run it from the same directory:

   Terminal Copy

   $ lytecache which
   /Users/you/Library/Caches/lytecache/fb0e4baed14c.db
   (exists)
   $ lytecache keys --long
   KEY                               TYPE  TTL    SIZE
   http:https://httpbin.org/delay/1  json  299.5  261
   $ lytecache get 'http:https://httpbin.org/delay/1'
   {
     "args": {},
     "data": "",
     ...

   which shows the file your script created. Its name comes from the directory you ran in, so the CLI finds it with no flags as long as you run it from the same place. keys --long shows the key, its type (json, because the response was a dict), the seconds left on its TTL, and its size. Seeing the row is usually what makes the model click: it's data in a file, and anything that can open the file can read it.

6. What to read next

   The recipes cover what you'll want next: caching API calls with memoize, avoiding a stampede when a hot key expires, and idempotency keys. If something doesn't behave the way this tutorial did, start with Troubleshooting.

Start here

Where is my data?

Every implementation picks the same default file for the same project. Start a Python script and a Go service from the same directory and they share one cache, with nothing to configure.

<platform cache dir>/lytecache/<project-id>.db

<project-id> is the first 12 hex characters of the SHA-256 hash of your working directory's resolved absolute path. Every implementation derives it the same way, so a Python script and a Java service started from the same directory land on the same file. Nothing is written into your repo. (The glossary explains SHA-256.)

Overriding it

• Pass an explicit path: LyteCache("/data/cache.db") in Python, .path(Path.of("/data/cache.db")) on the Java builder, new LyteCache({ path: "/data/cache.db" }) in Node.js, lytecache.WithPath("/data/cache.db") in Go, new LyteCache(path: "/data/cache.db") in PHP.
• Set LYTECACHE_PATH=/data/cache.db in the environment. It overrides the default in every language.

To find out which file a cache is using, ask it: LyteCache.default_path() / cache.path in Python, LyteCache.defaultPath() / cache.path() in Java, LyteCache.defaultPath() / cache.path in Node.js, lytecache.DefaultPath() / cache.Path() in Go, LyteCache::defaultPath() / $cache->path() in PHP. From a shell, lytecache which prints the path and whether the file exists.

Laravel is the one exception. Its cache driver defaults to storage_path('framework/cache/lytecache.db'), because that's where a Laravel app keeps its cache files. Change it with stores.lytecache.path in config/cache.php.

Start here

When to use lytecache

Guides

Recipes

Task-first answers to the things people actually build with lytecache. Each recipe says when to use it, shows it in all five languages, and ends with the catch.

@cache.memoize(ttl=300)             # rates update every few minutes
def exchange_rates(base):
    resp = requests.get(f"https://api.example.com/rates?base={base}", timeout=5)
    resp.raise_for_status()         # an exception is never cached
    return resp.json()

exchange_rates("USD")   # network
exchange_rates("USD")   # cache, for the next 300 seconds

Rates rates = cache.memoize("rates:" + base, Duration.ofMinutes(5),
    () -> ratesClient.fetch(base));    // an exception is never cached

// memoizeAsync for a loader that returns a Promise
const rates = await cache.memoizeAsync(`rates:${base}`, 300, async () => {
  const resp = await fetch(`https://api.example.com/rates?base=${base}`);
  if (!resp.ok) throw new Error(`rates: HTTP ${resp.status}`); // never cached
  return resp.json();
});

rates, err := lytecache.Memoize(cache, "rates:"+base, 5*time.Minute,
    func() (Rates, error) {
        return ratesClient.Fetch(base) // a non-nil error is never cached
    })

$rates = $cache->remember("rates:{$base}", 300, function () use ($http, $base) {
    return $http->get("https://api.example.com/rates", ["base" => $base])
        ->throw()                       // an exception is never cached
        ->json();
});

def get_report(day):
    key = f"report:{day}"
    report = cache.get(key)
    if report is not None:
        return report
    with cache.lock(f"rebuild:{key}", timeout=30):
        report = cache.get(key)          # rebuilt while we waited?
        if report is None:
            report = build_report(day)   # the slow part
            cache.set(key, report, ttl=600)
    return report

Report getReport(String day) {
    String key = "report:" + day;
    Report report = cache.get(key, Report.class);
    if (report != null) return report;
    try (CacheLock lock = cache.lock("rebuild:" + key, Duration.ofSeconds(30))) {
        report = cache.get(key, Report.class);   // rebuilt while we waited?
        if (report == null) {
            report = buildReport(day);           // the slow part
            cache.set(key, report, Duration.ofMinutes(10));
        }
    }
    return report;
}

function getReport(day: string): Report {
  const key = `report:${day}`;
  let report = cache.get<Report>(key);
  if (report !== undefined) return report;
  using lock = cache.lock(`rebuild:${key}`, { timeoutMs: 30_000 });
  report = cache.get<Report>(key);         // rebuilt while we waited?
  if (report === undefined) {
    report = buildReport(day);             // the slow part
    cache.set(key, report, { ttl: 600 });
  }
  return report;
}

func getReport(day string) (Report, error) {
    key := "report:" + day
    var r Report
    if found, err := cache.Get(key, &r); err != nil || found {
        return r, err
    }
    lock, err := cache.Lock("rebuild:"+key, 30*time.Second)
    if err != nil {
        return r, err // lytecache.ErrLockTimeout if a rebuild takes too long
    }
    defer lock.Release()
    if found, err := cache.Get(key, &r); err != nil || found { // rebuilt while we waited?
        return r, err
    }
    if r, err = buildReport(day); err != nil { // the slow part
        return r, err
    }
    return r, cache.Set(key, r, lytecache.TTL(10*time.Minute))
}

function getReport(LyteCache $cache, string $day): array
{
    $key = "report:{$day}";
    $report = $cache->get($key);
    if ($report !== null) {
        return $report;
    }
    return $cache->lock("rebuild:{$key}", timeout: 30.0)->block(function () use ($cache, $key, $day) {
        $report = $cache->get($key);          // rebuilt while we waited?
        if ($report === null) {
            $report = buildReport($day);      // the slow part
            $cache->set($key, $report, ttl: 600);
        }
        return $report;
    });
}

def exchange_rates():
    fresh = cache.get("rates:fresh")
    if fresh is not None:
        return fresh
    try:
        rates = {"data": fetch_rates(), "fetched_at": time.time()}
    except UpstreamError:
        stale = cache.get("rates:stale")
        if stale is None:
            raise                                 # nothing to fall back on
        return {**stale, "stale": True}           # show "as of fetched_at"
    cache.set("rates:fresh", rates, ttl=60)        # how often you want new data
    cache.set("rates:stale", rates, ttl=24 * 3600) # how old still beats an error
    return rates

record Rates(Map<String, Double> data, long fetchedAt, boolean stale) {}

Rates exchangeRates() {
    Rates fresh = cache.get("rates:fresh", Rates.class);
    if (fresh != null) return fresh;
    Rates rates;
    try {
        rates = new Rates(ratesClient.fetch(), System.currentTimeMillis(), false);
    } catch (UpstreamException e) {
        Rates stale = cache.get("rates:stale", Rates.class);
        if (stale == null) throw e;                   // nothing to fall back on
        return new Rates(stale.data(), stale.fetchedAt(), true);
    }
    cache.set("rates:fresh", rates, Duration.ofMinutes(1));
    cache.set("rates:stale", rates, Duration.ofDays(1));
    return rates;
}

async function exchangeRates() {
  const fresh = cache.get("rates:fresh");
  if (fresh !== undefined) return fresh;
  let rates;
  try {
    rates = { data: await fetchRates(), fetchedAt: Date.now() };
  } catch (err) {
    const stale = cache.get("rates:stale");
    if (stale === undefined) throw err;           // nothing to fall back on
    return { ...stale, stale: true };             // show "as of fetchedAt"
  }
  cache.set("rates:fresh", rates, { ttl: 60 });
  cache.set("rates:stale", rates, { ttl: 24 * 3600 });
  return rates;
}

type Rates struct {
    Data      map[string]float64 `json:"data"`
    FetchedAt time.Time          `json:"fetched_at"`
    Stale     bool               `json:"stale"`
}

func exchangeRates() (Rates, error) {
    var r Rates
    if found, _ := cache.Get("rates:fresh", &r); found {
        return r, nil
    }
    data, err := fetchRates()
    if err != nil {
        if found, _ := cache.Get("rates:stale", &r); found {
            r.Stale = true // show "as of FetchedAt"
            return r, nil
        }
        return r, err // nothing to fall back on
    }
    r = Rates{Data: data, FetchedAt: time.Now()}
    cache.Set("rates:fresh", r, lytecache.TTL(time.Minute))
    cache.Set("rates:stale", r, lytecache.TTL(24*time.Hour))
    return r, nil
}

function exchangeRates(LyteCache $cache): array
{
    $fresh = $cache->get("rates:fresh");
    if ($fresh !== null) {
        return $fresh;
    }
    try {
        $rates = ["data" => fetchRates(), "fetched_at" => time()];
    } catch (UpstreamException $e) {
        $stale = $cache->get("rates:stale");
        if ($stale === null) {
            throw $e;                                // nothing to fall back on
        }
        return [...$stale, "stale" => true];         // show "as of fetched_at"
    }
    $cache->set("rates:fresh", $rates, ttl: 60);
    $cache->set("rates:stale", $rates, ttl: 24 * 3600);
    return $rates;
}

def allow(client_id, limit=100, window=60):
    bucket = int(time.time() // window)
    key = f"rate:{client_id}:{bucket}"
    count = cache.incr(key)
    if count == 1:
        cache.expire(key, window * 2)   # old windows clean themselves up
    return count <= limit

boolean allow(String clientId, long limit, Duration window) {
    long bucket = Instant.now().getEpochSecond() / window.toSeconds();
    String key = "rate:" + clientId + ":" + bucket;
    long count = cache.incr(key);
    if (count == 1) {
        cache.expire(key, window.multipliedBy(2));  // old windows clean themselves up
    }
    return count <= limit;
}

function allow(clientId: string, limit = 100, windowSeconds = 60): boolean {
  const bucket = Math.floor(Date.now() / 1000 / windowSeconds);
  const key = `rate:${clientId}:${bucket}`;
  const count = Number(cache.incr(key));
  if (count === 1) {
    cache.expire(key, windowSeconds * 2);   // old windows clean themselves up
  }
  return count <= limit;
}

func allow(clientID string, limit int64, window time.Duration) (bool, error) {
    bucket := time.Now().Unix() / int64(window.Seconds())
    key := fmt.Sprintf("rate:%s:%d", clientID, bucket)
    count, err := cache.Incr(key, 1)
    if err != nil {
        return false, err
    }
    if count == 1 {
        cache.Expire(key, 2*window) // old windows clean themselves up
    }
    return count <= limit, nil
}

function allow(LyteCache $cache, string $clientId, int $limit = 100, int $window = 60): bool
{
    $bucket = intdiv(time(), $window);
    $key = "rate:{$clientId}:{$bucket}";
    $count = $cache->incr($key);
    if ($count === 1) {
        $cache->expire($key, $window * 2);   // old windows clean themselves up
    }
    return $count <= $limit;
}

DAY = 24 * 3600

def charge(request_id, amount):
    key = f"idem:{request_id}"
    if not cache.add(key, {"status": "processing"}, ttl=DAY):
        previous = cache.get(key)
        if previous and previous["status"] == "done":
            return previous["receipt"]           # replay the first response
        raise Conflict("still processing")       # 409: tell the client to retry later
    try:
        receipt = payments.charge(amount, idempotency_key=request_id)
    except Exception:
        cache.delete(key)                        # failed: let a retry try again
        raise
    cache.set(key, {"status": "done", "receipt": receipt}, ttl=DAY)
    return receipt

record Claim(String status, Receipt receipt) {}

Receipt charge(String requestId, long amount) {
    String key = "idem:" + requestId;
    if (!cache.add(key, new Claim("processing", null), Duration.ofDays(1))) {
        Claim previous = cache.get(key, Claim.class);
        if (previous != null && previous.status().equals("done")) {
            return previous.receipt();               // replay the first response
        }
        throw new ConflictException("still processing");  // 409
    }
    Receipt receipt;
    try {
        receipt = payments.charge(amount, requestId);
    } catch (RuntimeException e) {
        cache.delete(key);                           // failed: let a retry try again
        throw e;
    }
    cache.set(key, new Claim("done", receipt), Duration.ofDays(1));
    return receipt;
}

const DAY = 24 * 3600;

async function charge(requestId: string, amount: number): Promise<Receipt> {
  const key = `idem:${requestId}`;
  if (!cache.add(key, { status: "processing" }, { ttl: DAY })) {
    const previous = cache.get<{ status: string; receipt?: Receipt }>(key);
    if (previous?.status === "done") return previous.receipt!; // replay
    throw new ConflictError("still processing");               // 409
  }
  let receipt: Receipt;
  try {
    receipt = await payments.charge(amount, { idempotencyKey: requestId });
  } catch (err) {
    cache.delete(key);                     // failed: let a retry try again
    throw err;
  }
  cache.set(key, { status: "done", receipt }, { ttl: DAY });
  return receipt;
}

type claim struct {
    Status  string   `json:"status"`
    Receipt *Receipt `json:"receipt,omitempty"`
}

func charge(requestID string, amount int64) (*Receipt, error) {
    key := "idem:" + requestID
    won, err := cache.Add(key, claim{Status: "processing"}, lytecache.TTL(24*time.Hour))
    if err != nil {
        return nil, err
    }
    if !won {
        var prev claim
        if found, _ := cache.Get(key, &prev); found && prev.Status == "done" {
            return prev.Receipt, nil // replay the first response
        }
        return nil, ErrStillProcessing // 409
    }
    receipt, err := payments.Charge(amount, requestID)
    if err != nil {
        cache.Delete(key) // failed: let a retry try again
        return nil, err
    }
    return receipt, cache.Set(key, claim{Status: "done", Receipt: receipt}, lytecache.TTL(24*time.Hour))
}

function charge(LyteCache $cache, string $requestId, int $amount): array
{
    $key = "idem:{$requestId}";
    $day = 24 * 3600;
    if (!$cache->add($key, ["status" => "processing"], ttl: $day)) {
        $previous = $cache->get($key);
        if (($previous["status"] ?? null) === "done") {
            return $previous["receipt"];              // replay the first response
        }
        throw new ConflictException("still processing");  // 409
    }
    try {
        $receipt = Payments::charge($amount, idempotencyKey: $requestId);
    } catch (Throwable $e) {
        $cache->delete($key);                         // failed: let a retry try again
        throw $e;
    }
    $cache->set($key, ["status" => "done", "receipt" => $receipt], ttl: $day);
    return $receipt;
}

# One worker at a time:
with cache.lock("inventory-sync", timeout=120):
    sync_inventory()

# Once per day, however many workers fire at midnight:
today = datetime.date.today().isoformat()
if cache.add(f"job:nightly-export:{today}", os.getpid(), ttl=2 * 86400):
    run_export()

// One worker at a time:
try (CacheLock lock = cache.lock("inventory-sync", Duration.ofMinutes(2))) {
    syncInventory();
}

// Once per day, however many workers fire at midnight:
String today = LocalDate.now().toString();
if (cache.add("job:nightly-export:" + today, ProcessHandle.current().pid(), Duration.ofDays(2))) {
    runExport();
}

// One worker at a time:
{
  using lock = cache.lock("inventory-sync", { timeoutMs: 120_000 });
  syncInventory();
}

// Once per day, however many workers fire at midnight:
const today = new Date().toISOString().slice(0, 10);
if (cache.add(`job:nightly-export:${today}`, process.pid, { ttl: 2 * 86400 })) {
  runExport();
}

// One worker at a time:
lock, err := cache.Lock("inventory-sync", 2*time.Minute)
if err != nil {
    return err
}
syncInventory()
lock.Release()

// Once per day, however many workers fire at midnight:
today := time.Now().Format("2006-01-02")
if won, _ := cache.Add("job:nightly-export:"+today, os.Getpid(), lytecache.TTL(48*time.Hour)); won {
    runExport()
}

// One worker at a time:
$cache->lock("inventory-sync", timeout: 120.0)->block(function () {
    syncInventory();
});

// Once per day, however many workers fire at midnight:
$today = date("Y-m-d");
if ($cache->add("job:nightly-export:{$today}", getmypid(), ttl: 2 * 86400)) {
    runExport();
}

def rename_user(user_id, name):
    with db.transaction():
        db.execute("UPDATE users SET name = ? WHERE id = ?", (name, user_id))
    cache.delete(f"user:{user_id}")   # after the commit, never inside it

void renameUser(long userId, String name) {
    jdbc.inTransaction(tx -> tx.update("UPDATE users SET name = ? WHERE id = ?", name, userId));
    cache.delete("user:" + userId);   // after the commit, never inside it
}

async function renameUser(userId: number, name: string) {
  await db.transaction(async (tx) => {
    await tx.query("UPDATE users SET name = $1 WHERE id = $2", [name, userId]);
  });
  cache.delete(`user:${userId}`);    // after the commit, never inside it
}

func renameUser(ctx context.Context, userID int64, name string) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()
    if _, err := tx.ExecContext(ctx, "UPDATE users SET name = $1 WHERE id = $2", name, userID); err != nil {
        return err
    }
    if err := tx.Commit(); err != nil {
        return err
    }
    _, err = cache.Delete(fmt.Sprintf("user:%d", userID)) // after the commit
    return err
}

function renameUser(PDO $db, LyteCache $cache, int $userId, string $name): void
{
    $db->beginTransaction();
    $db->prepare("UPDATE users SET name = ? WHERE id = ?")->execute([$name, $userId]);
    $db->commit();
    $cache->delete("user:{$userId}");   // after the commit, never inside it
}

# the writer, after its transaction commits
cache.delete("pricing-rules")
cache.notify("invalidate", {"key": "pricing-rules"})

# every worker, at startup
def listen():
    with cache.watch("invalidate") as sub:
        for event in sub:
            local_memo.pop(event.payload["key"], None)

threading.Thread(target=listen, daemon=True).start()

// the writer, after its transaction commits
cache.delete("pricing-rules");
cache.notify("invalidate", Map.of("key", "pricing-rules"));

// every worker, at startup
Thread listener = new Thread(() -> {
    try (Subscription sub = cache.watch("invalidate")) {
        for (Event e : sub) {
            localMemo.remove(e.payload(Map.class).get("key"));
        }
    }
}, "lytecache-invalidate");
listener.setDaemon(true);
listener.start();

// the writer, after its transaction commits
cache.delete("pricing-rules");
cache.notify("invalidate", { key: "pricing-rules" });

// every worker, at startup
(async () => {
  using sub = cache.watch("invalidate");
  for await (const event of sub) localMemo.delete(event.payload.key);
})();

// the writer, after its transaction commits
cache.Delete("pricing-rules")
cache.Notify("invalidate", map[string]any{"key": "pricing-rules"})

// every worker, at startup
go func() {
    sub, err := cache.Watch([]string{"invalidate"})
    if err != nil {
        log.Fatal(err)
    }
    defer sub.Close()
    for ev := range sub.Events() {
        var p struct{ Key string `json:"key"` }
        if ev.Decode(&p) == nil {
            localMemo.Delete(p.Key) // a sync.Map: other goroutines read it
        }
    }
}()

// the writer, after its transaction commits
$cache->delete("pricing-rules");
$cache->notify("invalidate", ["key" => "pricing-rules"]);

// a long-running worker (queue worker, Octane, Swoole). PHP has no
// threads, so the worker polls inside this loop.
foreach ($cache->watch("invalidate") as $event) {
    unset($localMemo[$event->payload()["key"]]);
}

Guides

Coming from Redis

Most of what you use Redis for as a cache maps across one to one. The method names below are the Python ones. Node.js, Java and PHP use camelCase (setMany), and Go uses exported names (SetMany). Every method is on the toggle in the method reference.

What has no equivalent

It's better to find this out now than on day three. If any of these is central to what you're building, keep Redis.

Guides

Framework integration

Laravel has a real cache driver. The other frameworks below don't have an adapter yet, so these sections show how to wire the plain library in by hand. Each snippet is for one framework, so the language toggle doesn't apply to them.

Spring Boot

No adapter yet. There's no Spring CacheManager for lytecache, so @Cacheable won't use it. Register one LyteCache as a singleton bean and inject it. One instance per application is right. It's thread-safe, and each extra instance on the same file only adds connections and another sweeper thread.

@Configuration
public class CacheConfig {
    @Bean(destroyMethod = "close")
    public LyteCache lyteCache(@Value("${app.cache-path}") Path path) {
        return LyteCache.builder().path(path).namespace("orders").build();
    }
}

@Service
public class RatesService {
    private final LyteCache cache;
    private final RatesClient client;

    public RatesService(LyteCache cache, RatesClient client) {
        this.cache = cache;
        this.client = client;
    }

    public Rates rates(String base) {
        return cache.memoize("rates:" + base, Duration.ofMinutes(5), () -> client.fetch(base));
    }
}

destroyMethod = "close" stops the sweeper and flushes buffered state when the context shuts down. Set app.cache-path to a directory on a volume in production; see Troubleshooting for what happens if you don't.

Django

No adapter yet. There's no CACHES backend, so Django's own cache framework won't use lytecache. Create the cache in a module and import it where you need it.

# myproject/cache.py
from django.conf import settings
from lytecache import LyteCache

cache = LyteCache(settings.BASE_DIR / "var" / "cache.db", namespace="myproject")


# anywhere
from myproject.cache import cache

def product_view(request, pk):
    product = cache.get(f"product:{pk}")
    if product is None:
        product = serialize(Product.objects.get(pk=pk))
        cache.set(f"product:{pk}", product, ttl=600)
    return JsonResponse(product)

Create the cache in each worker, not before Gunicorn forks. The library opens its SQLite connection when you construct it and doesn't detect a fork(), so a cache built in the master process under --preload would hand every worker a copy of the same connection. Without --preload, each worker imports the module itself and gets its own.

Flask

No adapter yet. Attach one cache to the app and close it at exit.

import atexit
from flask import Flask, current_app
from lytecache import LyteCache

def create_app():
    app = Flask(__name__)
    app.extensions["lytecache"] = cache = LyteCache(app.instance_path + "/cache.db")
    atexit.register(cache.close)

    @app.get("/rates/<base>")
    def rates(base):
        cache = current_app.extensions["lytecache"]
        return cache.get(f"rates:{base}") or refresh_rates(base)

    return app

The same fork rule applies as for Django: build the cache inside create_app() in each worker, not at import time in a preloaded master.

Express

No adapter yet. Export one cache from a module, use it in routes or middleware, and close it on shutdown.

// cache.ts
import { LyteCache } from "lytecache";
export const cache = new LyteCache({ path: process.env.LYTECACHE_PATH ?? "./var/cache.db" });

// app.ts
import express from "express";
import { cache } from "./cache.js";

const app = express();

app.get("/rates/:base", async (req, res) => {
  const rates = await cache.memoizeAsync(`rates:${req.params.base}`, 300,
    () => fetchRates(req.params.base));
  res.json(rates);
});

const server = app.listen(3000);
process.on("SIGTERM", () => server.close(() => cache.close()));

Under the cluster module or PM2, each worker process opens its own handle to the same file. That's the intended setup, and they all see each other's writes.

Laravel

A real driver ships with the PHP package. The service provider is auto-discovered, so installing the package and setting one environment variable is the whole setup. Cache::remember(), Cache::lock() and the rest of the facade then use lytecache.

composer require lytecache/lytecache
echo "CACHE_STORE=lytecache" >> .env

use Illuminate\Support\Facades\Cache;

$user = Cache::remember("user:42", 300, fn () => User::find(42));

Cache::lock("import:products", 60)->block(30, function () {
    // one worker at a time, across every PHP-FPM process on this host
});

The file defaults to storage_path('framework/cache/lytecache.db'). To change it, or set a namespace, cap or eviction policy, publish the config with php artisan vendor:publish --tag=lytecache-config. PHP has no background thread, so schedule the maintenance command to keep a quiet cache swept:

// routes/console.php
Schedule::command("lytecache:maintain")->everyMinute();

Guides

Troubleshooting

Find the symptom you're seeing. Each entry gives one way to confirm the cause, then the fix.

“My key is there when I write it and gone when I read it.”

Work down this list in order. The first check finds the problem most of the time.

1. Compare the key strings character by character. Print them with quotes around them, at both sites. The usual culprit is something interpolated into the key: user:None or user:undefined because an ID wasn't loaded yet, 42 at one site and "42 " at the other, or a UUID in upper case in one place and lower case in another.
2. Check the TTL right after the write. If ttl(key) prints 0.3 when you meant five minutes, the key really did expire. See the units entry at the end of this section.
3. Check exists(key) at the read site. If it's false while the writer's own check is true, the two sites aren't looking at the same file or namespace. The next entry covers that.

print(repr(key), cache.ttl(key))       # at the write site, straight after set()
print(repr(key), cache.exists(key))    # at the read site

“stats shows zero keys, but my app is definitely caching.”

Almost always a namespace mismatch. Your app opened the cache with a namespace, and the CLI looks in default unless you tell it otherwise. Both are reading the right file, just different partitions of it. Nothing errors. The CLI just sees an empty namespace, which makes this the most confusing failure in the product.

Look at how your app opens the cache, then pass the same namespace to the CLI:

To see every namespace in a file and how many keys each holds, open it in the Admin UI, whose sidebar lists them with counts. Or ask SQLite directly:

sqlite3 "$(lytecache which | head -1)" "SELECT namespace, COUNT(*) FROM cache GROUP BY namespace"

Two more things that look like this problem but aren't. A LYTECACHE_NAMESPACE environment variable does nothing, because no implementation reads one; set the namespace in code. And the hits and misses lines in lytecache stats always read 0. They count the CLI's own reads, not your app's. The line that tells you whether you're looking at the right namespace is keys.

“The cache is empty after every deploy or restart.”

The file is living in the container's writable layer, which is thrown away whenever the container is recreated. Confirm it by looking for a volume at the cache path: if docker inspect shows nothing mounted there, that's the cause.

Mount a named volume on the cache directory and point LYTECACHE_PATH into it:

services:
  app:
    environment:
      LYTECACHE_PATH: /var/cache/lytecache/app.db
    volumes:
      - lytecache-data:/var/cache/lytecache

volumes:
  lytecache-data:

Mount the directory, not the .db file, because SQLite creates app.db-wal and app.db-shm next to it.

“SQLITE_CANTOPEN / unable to open database file”

The cache directory doesn't exist, or it exists but is owned by root while your app runs as a non-root user. Confirm it from inside the container with ls -ld /var/cache/lytecache and id.

Create the directory and hand it to your app's user in the Dockerfile, before the USER line:

RUN mkdir -p /var/cache/lytecache && chown app:app /var/cache/lytecache
USER app

When Docker mounts an empty named volume for the first time, it copies that directory's ownership from the image. So getting it right in the image fixes the volume too. A volume that was already created with root ownership keeps it, though. Fix that one with a one-off chown, or remove the volume and let it be recreated.

“The CLI says the database file doesn't exist, and Docker logs Volume … Created.”

You're running the CLI in a different Compose project from your app. Compose names volumes after the project (myapp_lytecache-data), and it takes the project name from the directory you run it in unless something sets it explicitly. Run the CLI service from another directory and Compose looks for otherdir_lytecache-data, doesn't find it, and creates a new, empty one.

Compose creating a volume or network when you only meant to run the CLI is the tell. It means you're not in the app's project. Check which projects exist and run the CLI in the right one:

docker compose ls                                     # the real project names
docker compose -p myapp run --rm lytecache-cli stats  # run inside the app's project
docker volume rm otherdir_lytecache-data               # tidy up the stray volume

“The Admin UI starts, but the dashboard is empty.”

The UI container mounts a different volume from the one your app writes to. The container starts fine either way, so nothing tells you. Compare the mounts of the two containers:

docker inspect myapp-app-1 --format '{{range .Mounts}}{{.Name}} -> {{.Destination}}{{println}}{{end}}'
docker inspect myapp-lytecache-ui-1 --format '{{range .Mounts}}{{.Name}} -> {{.Destination}}{{println}}{{end}}'

The volume names must match. If they don't, mount the app's volume in the UI service. Multiple app services, one Admin UI covers setups with several services.

“Writes seem to be getting lost under load.”

SQLite allows one writer at a time. A process that finds the file locked waits up to five seconds (busy_timeout=5000) for its turn. If it still can't write, it gets a "database is locked" error. It doesn't silently drop the write. So a lost write means either an error that something swallowed, or a bug.

Look for a try or catch around cache writes that discards the error. While you investigate, turn on strict mode too: by default a failing read is logged and returned as a miss, which can look like a write that never happened. Read-modify-write code (get, change, set) loses updates whenever two writers overlap. Use incr, the hash operations or lock() instead.

If you've ruled those out, please open an issue and include the library and version (pip show lytecache, npm ls lytecache, the Maven/Composer version or the Go module version), the SQLite version, how many processes write concurrently, and whether the file sits on a network filesystem. NFS and Kubernetes ReadWriteMany volumes aren't supported, because SQLite's locking doesn't work reliably on them.

“PHP: installed fine, but crashes with a fatal error.”

lytecache for PHP needs PHP 8.2 or newer, and Composer refuses to install it on anything older. If the install went through anyway, something bypassed that check, and the library now stops at startup with this message instead of crashing mid-request:

RuntimeException: lytecache requires PHP 8.2 or newer; this process is running PHP 8.1.34.
Composer should have refused this install, so it was most likely installed with
--ignore-platform-reqs or --ignore-platform-req=php, or the root composer.json sets
config.platform.php.

Check the three ways a bypass happens:

1. An install flag. Look for --ignore-platform-reqs or --ignore-platform-req=php in your Dockerfile, CI workflow or deploy script, and remove it. If one build genuinely needs it, narrow it to the one extension involved (--ignore-platform-req=ext-something).
2. config.platform.php in your app's composer.json. It makes Composer resolve for a PHP you aren't running. composer config platform.php prints it if it's set. Composer's own startup check usually reports this one first, as “Composer detected issues in your platform”.
3. A composer.lock resolved on a different PHP. Run composer check-platform-reqs on the machine that runs the app. It lists every requirement this PHP doesn't meet.

The fix is a supported PHP. Don't silence the error: below 8.2 the library can't run.

“My keys expire sooner or later than I expected.”

In Python, Node.js and PHP, ttl is in seconds. Passing milliseconds out of habit, like ttl=5000, gives you 83 minutes instead of 5 seconds. Going the other way, ttl=0.3 is 300 milliseconds. Java and Go take a typed duration, so they can't get this wrong.

Check what you actually stored straight after the write:

cache.set("otp:42", code, ttl=5000)
cache.ttl("otp:42")    # 4999.9 -> you meant ttl=5

If the TTL is right but the row is still in the file after it expired, that's the sweep interval. Reads already treat it as gone; see Lazy and active expiration.

Guides

TTL & expiration

TTLs work the same way for every value type: strings, numbers, dataclasses, dicts, POJOs, records. Storing an object changes nothing.

cache.set("session", {"user_id": 42}, ttl=300)   # expires in 300s (5 min)
cache.set("otp", "123456", ttl=0.5)              # expires in 500ms

cache.ttl("session")        # seconds remaining, e.g. 298.7
cache.ttl("permanent_key")  # -1 if no TTL was set
cache.ttl("missing")        # None if the key doesn't exist

cache.expire("session", 60)   # overwrite the TTL: now expires in 60s
cache.persist("session")      # remove the TTL entirely
cache.touch("session", 300)   # sliding expiration: refresh back to 300s

cache.set("session", "42", Duration.ofMinutes(5));
cache.set("otp", "123456", Duration.ofMillis(500));

cache.ttl("session");     // Duration remaining
cache.ttl("permanent");   // Duration.ofSeconds(-1) if no TTL
cache.ttl("missing");     // null if the key doesn't exist

cache.expire("session", Duration.ofSeconds(60));  // overwrite the TTL
cache.persist("session");                          // remove the TTL entirely
cache.touch("session", Duration.ofMinutes(5));     // sliding expiration

cache.set("session", { userId: 42 }, { ttl: 300 });  // expires in 300s (5 min)
cache.set("otp", "123456", { ttl: 0.5 });            // expires in 500ms

cache.ttl("session");        // seconds remaining, e.g. 298.7
cache.ttl("permanentKey");   // -1 if no TTL was set
cache.ttl("missing");        // undefined if the key doesn't exist

cache.expire("session", 60);   // overwrite the TTL: now expires in 60s
cache.persist("session");      // remove the TTL entirely
cache.touch("session", 300);   // sliding expiration: refresh back to 300s

cache.Set("session", 42, lytecache.TTL(5*time.Minute))   // expires in 5 min
cache.Set("otp", "123456", lytecache.TTL(500*time.Millisecond))

_, hasExpiry, found, _ := cache.TTLOf("session")   // remaining time.Duration
_, hasExpiry, found, _ = cache.TTLOf("permanent")  // hasExpiry=false if no TTL
_, _, found, _ = cache.TTLOf("missing")            // found=false if the key doesn't exist

cache.Expire("session", 60*time.Second)  // overwrite the TTL
cache.Persist("session")                 // remove the TTL entirely
cache.Touch("session", 5*time.Minute)    // sliding expiration: refresh back to 5 min

$cache->set("session", ["user_id" => 42], ttl: 300);   // expires in 300s (5 min)
$cache->set("otp", "123456", ttl: 0.5);                // expires in 500ms

$cache->ttl("session");        // seconds remaining, e.g. 298.7
$cache->ttl("permanent_key");  // -1 if no TTL was set
$cache->ttl("missing");        // null if the key doesn't exist

$cache->expire("session", 60);   // overwrite the TTL: now expires in 60s
$cache->persist("session");      // remove the TTL entirely
$cache->touch("session", 300);   // sliding expiration: refresh back to 300s

Lazy and active expiration

Every implementation expires keys in two ways:

• Lazily, on every read (get / exists / getAll / getMany / TTLOf): the read treats an expired row as a miss and deletes it on the spot, even with the background sweeper disabled.
• Actively, by a background sweeper (a thread in Python/Java, a setInterval timer in Node.js, a goroutine in Go) that runs every sweep_interval / sweepInterval / WithSweepInterval (default 60s). It deletes expired rows in batches, so dead keys don't hold disk space even if nothing reads them again. PHP has no background threads. Instead it runs short maintenance passes opportunistically (roughly every 100 operations, throttled by sweepInterval). In a Laravel app, also schedule the lytecache:maintain artisan command so a quiet cache still gets swept.

Open the file in a SQLite browser right after a key expires and you may still see the row. The sweeper hasn't reached it yet. get() and exists() already treat it as gone. To remove expired rows right away, lower the sweep interval or run lytecache maintain (Maintain() in Go, maintain() in PHP). To shrink the file afterwards, call vacuum().

Guides

Flush & delete

cache.delete("key1", "key2")   # delete specific keys; returns how many existed
cache.flush()                  # delete EVERYTHING in the current namespace

cache.delete("key1", "key2");   // delete specific keys; returns how many existed
cache.flush();                  // delete EVERYTHING in the current namespace

cache.delete("key1", "key2");   // delete specific keys; returns how many existed
cache.flush();                  // delete EVERYTHING in the current namespace

cache.Delete("key1", "key2")   // delete specific keys; returns how many existed
cache.Flush()                  // delete EVERYTHING in the current namespace

$cache->delete("key1", "key2");   // delete specific keys; returns how many existed
$cache->flush();                  // delete EVERYTHING in the current namespace

flush() always clears the whole namespace: default, unless you configured another. It takes no key or pattern. To clear part of a namespace, delete by key or by pattern:

for key in list(cache.keys("session:*")):
    cache.delete(key)

cache.keys("session:*").forEach(cache::delete);

for (const key of cache.keys("session:*")) cache.delete(key);

for key, _ := range cache.Keys("session:*") {
    cache.Delete(key)
}

foreach ($cache->keys("session:*") as $key) {
    $cache->delete($key);
}

Reference

Configuration

Every option has a sane default; nothing here is required to get started.

LyteCache(
    path=None,             # explicit file path; default: LyteCache.default_path()
    namespace="default",   # logical partition within the database file
    max_keys=None,         # evict when the namespace exceeds this many keys
    max_bytes=None,        # evict when the namespace exceeds this many bytes
    eviction="lru",        # "lru" | "ttl" | "random" | "noeviction"
    sweep_interval=60.0,   # seconds between maintenance passes; None disables
                           # the thread and sweeps opportunistically instead
    serializer="auto",     # "auto" | "json" (strict) | "pickle"
    strict=False,          # True: raise on internal read errors
    allow_pickle=False,    # "auto" mode only: allow reading pickled values
)

LyteCache cache = LyteCache.builder()
    .path(Path.of("/data/my-cache.db"))    // optional; platform cache dir if omitted
    .namespace("sessions")                  // isolate multiple caches in one file
    .maxKeys(100_000)                       // evict when exceeded (default: 1M)
    .maxBytes(256L * 1024 * 1024)           // evict when exceeded (default: 1 GB)
    .eviction(Eviction.LRU)                 // LRU (default), TTL, RANDOM, NOEVICTION
    .sweepInterval(Duration.ofSeconds(60))  // background cleanup frequency
    .strict(false)                          // on read error: log+miss, or throw
    .build();

new LyteCache({
  path: undefined,       // explicit file path; default: LyteCache.defaultPath()
  namespace: "default",  // logical partition within the database file
  maxKeys: undefined,    // evict when the namespace exceeds this many keys
  maxBytes: undefined,   // evict when the namespace exceeds this many bytes
  eviction: "lru",       // "lru" | "ttl" | "random" | "noeviction"
  sweepInterval: 60,     // seconds between maintenance passes; null disables
                         // the timer and sweeps opportunistically instead
  strict: false,         // true: throw on internal read errors instead of
                         // degrading to a miss
  logger: console.warn,  // called on a non-strict degraded read
});

cache, err := lytecache.New(
    lytecache.WithPath("/data/cache.db"),        // optional; default: lytecache.DefaultPath()
    lytecache.WithNamespace("sessions"),          // isolate multiple caches in one file
    lytecache.WithMaxKeys(100_000),               // evict when exceeded (default: no limit)
    lytecache.WithMaxBytes(256<<20),              // evict when exceeded (default: no limit)
    lytecache.WithEviction(lytecache.LRU),        // LRU (default), TTLPolicy, Random, NoEviction
    lytecache.WithSweepInterval(60*time.Second),  // 0 disables the goroutine -> opportunistic mode
    lytecache.WithStrict(false),                  // true: return read errors instead of a miss
)

new LyteCache(
    path: null,               // explicit file path; default: LyteCache::defaultPath()
    namespace: "default",     // logical partition within the database file
    maxKeys: null,            // evict when the namespace exceeds this many keys
    maxBytes: null,           // evict when the namespace exceeds this many bytes
    eviction: Eviction::LRU,  // LRU (default), TTL, Random, NoEviction
    sweepInterval: 60.0,      // minimum seconds between opportunistic maintenance passes
    strict: false,            // true: throw on internal read errors instead of a miss
);

Eviction policies: lru (default, evicts least-recently-used), ttl (soonest-to-expire first), random, and noeviction (rejects the write instead of evicting). LFU is not available yet in any implementation. The glossary expands LRU and the other abbreviations.

One default differs between languages. Java caps a cache at 1,000,000 keys and 1 GB unless you say otherwise. The other four languages have no cap until you set max_keys or max_bytes.

Reference

Method reference

Grouped by what you're trying to do. Every group shows all five languages. Pick one on the toggle and the whole page follows.

cache.set("key", "value")
cache.set("key", "value", ttl=300)
cache.get("key")                 # None if missing or expired
cache.get("key", "default")      # custom default on miss
cache.delete("key1", "key2")     # returns count actually deleted
cache.exists("key")

cache.set("key", "value");
cache.set("key", "value", Duration.ofMinutes(5));
String val = cache.getString("key");   // null if missing or expired
Long n = cache.getLong("key");
Double d = cache.getDouble("key");
byte[] b = cache.getBytes("key");
cache.delete("key1", "key2");          // returns count actually deleted
cache.exists("key");

cache.set("key", "value");
cache.set("key", "value", { ttl: 300 });
cache.get("key");                // undefined if missing or expired
cache.get("key", "default");     // custom default on miss
cache.delete("key1", "key2");    // returns count actually deleted
cache.exists("key");

cache.Set("key", "value")
cache.Set("key", "value", lytecache.TTL(5*time.Minute))
var v string
found, _ := cache.Get("key", &v)      // found=false if missing or expired
s, found, _ := cache.GetString("key")  // typed convenience wrapper
cache.Delete("key1", "key2")           // returns count actually deleted
cache.Exists("key")

$cache->set("key", "value");
$cache->set("key", "value", ttl: 300);
$cache->get("key");                 // null if missing or expired
$cache->get("key", "default");      // custom default on miss
$cache->delete("key1", "key2");     // returns count actually deleted
$cache->has("key");

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int

cache.set("p:1", Person("Samson", 30))
cache.get("p:1")                # plain dict by default
cache.get("p:1", cls=Person)    # typed: Person(name="Samson", age=30)

record Person(String name, int age) {}

cache.set("p:1", new Person("Samson", 30));
cache.get("p:1", Person.class);

// Generic types a raw Class can't express:
Map<String, Long> scores = cache.get("scores",
    new TypeReference<Map<String, Long>>() {});

class Person {
  constructor(public name: string, public age: number) {}
}

cache.set("p:1", new Person("Samson", 30));
cache.get("p:1");                             // plain object by default
cache.get("p:1", undefined, { into: Person }); // typed: instanceof Person

type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

cache.Set("p:1", Person{Name: "Samson", Age: 30})
var p Person
found, _ := cache.Get("p:1", &p) // typed: struct fields via encoding/json tags

final class Person {
    public function __construct(
        public string $name,
        public int $age,
    ) {}
}

$cache->set("p:1", new Person("Samson", 30));
$cache->get("p:1");                        // plain array by default
$cache->get("p:1", class: Person::class);  // typed: Person(name: "Samson", age: 30)

cache.add("key", "value", ttl=60)      # set only if absent (SET NX)
cache.replace("key", "value", ttl=60)  # set only if present (SET XX)
cache.get_set("key", "new")            # atomic swap, returns the old value

cache.add("key", "value", ttl);      // set only if absent (SET NX)
cache.replace("key", "value", ttl);  // set only if present (SET XX)
cache.getSet("key", "new");          // atomic swap, returns the old value

cache.add("key", "value", { ttl: 60 });      // set only if absent (SET NX)
cache.replace("key", "value", { ttl: 60 });  // set only if present (SET XX)
cache.getSet("key", "new");                  // atomic swap, returns the old value

cache.Add("key", "value", lytecache.TTL(60*time.Second))      // set only if absent (SET NX)
cache.Replace("key", "value", lytecache.TTL(60*time.Second))  // set only if present (SET XX)
var old string
cache.GetSet("key", "new", &old) // atomic swap, decodes the old value into old

$cache->add("key", "value", ttl: 60);      // set only if absent (SET NX)
$cache->replace("key", "value", ttl: 60);  // set only if present (SET XX)
$cache->getSet("key", "new");              // atomic swap, returns the old value

cache.set_many({"a": "1", "b": "2"}, ttl=60)   # single transaction
cache.get_many(["a", "b", "missing"])           # {"a": "1", "b": "2"}

cache.setAll(Map.of("a", "1", "b", "2"), ttl);   // single transaction
cache.getAll(List.of("a", "b", "missing"));       // {a=1, b=2}

cache.setMany({ a: "1", b: "2" }, { ttl: 60 });   // single transaction
cache.getMany(["a", "b", "missing"]);              // Map(2) {'a' => '1', 'b' => '2'}

cache.SetMany(map[string]any{"a": "1", "b": "2"}, lytecache.TTL(60*time.Second))
results, _ := cache.GetMany([]string{"a", "b", "missing"}) // map[string]RawValue, decode per key

$cache->setMany(["a" => "1", "b" => "2"], ttl: 60);   // single transaction
$cache->getMany(["a", "b", "missing"]);                // ["a" => "1", "b" => "2"]

cache.incr("hits")             # +1
cache.incr("hits", 5)          # +5
cache.decr("hits")             # -1
cache.incr_float("ratio", 0.5)

cache.incr("hits");              // +1
cache.incr("hits", 5);           // +5
cache.decr("hits");              // -1
cache.incrDouble("ratio", 0.5);

cache.incr("hits");              // +1
cache.incr("hits", 5);           // +5
cache.decr("hits");              // -1
cache.incrFloat("ratio", 0.5);

cache.Incr("hits", 1)          // +1
cache.Incr("hits", 5)          // +5
cache.Decr("hits", 1)          // -1
cache.IncrFloat("ratio", 0.5)

$cache->incr("hits");             // +1
$cache->incr("hits", 5);          // +5
$cache->decr("hits");             // -1
$cache->incrFloat("ratio", 0.5);

for key in cache.keys("session:*"):   # lazy iterator, GLOB syntax
    print(key)

cache.keys("session:*")                // lazy Stream<String>, GLOB syntax
    .forEach(System.out::println);

for (const key of cache.keys("session:*")) {  // lazy generator, GLOB syntax
  console.log(key);
}

for key, err := range cache.Keys("session:*") { // iter.Seq2, GLOB syntax
    fmt.Println(key, err)
}

foreach ($cache->keys("session:*") as $key) {  // lazy Generator, GLOB syntax
    echo $key;
}

cache.stats()
# {'hits': 42, 'misses': 3, 'hit_rate': 0.93, 'key_count': 12,
#  'size_bytes': 8291, 'evictions': 0, 'path': '...'}
cache.vacuum()   # reclaim disk space
cache.close()    # shut down cleanly

CacheStats stats = cache.stats();
stats.hitRate();     // percentage
stats.keyCount();
stats.sizeBytes();
stats.path();
cache.vacuum();      // reclaim disk space
cache.close();       // shut down cleanly (or use try-with-resources)

cache.stats();
// { hits: 42, misses: 3, hitRate: 0.93, keyCount: 12,
//   sizeBytes: 8291, evictions: 0, path: '...' }
cache.vacuum();   // reclaim disk space
cache.close();    // shut down cleanly (or use Symbol.dispose)

stats, _ := cache.Stats()
// {Hits:42 Misses:3 HitRate:0.93 KeyCount:12 SizeBytes:8291 Evictions:0 Path:"..."}
cache.Vacuum()  // reclaim disk space
cache.Close()   // shut down cleanly (idempotent)

$cache->stats();
// CacheStats(hits: 42, misses: 3, hitRate: 0.93, keyCount: 12,
//   sizeBytes: 8291, evictions: 0, path: "...")
$cache->vacuum();   // reclaim disk space
$cache->close();    // shut down cleanly (idempotent; __destruct() also calls it)

with cache.lock("resource", timeout=30):
    do_critical_work()

try (CacheLock lock = cache.lock("resource", Duration.ofSeconds(30))) {
    doCriticalWork();
}

using lock = cache.lock("resource", { timeoutMs: 30_000 });
doCriticalWork();

lock, err := cache.Lock("resource", 30*time.Second)
defer lock.Release()
doCriticalWork()

$cache->lock("resource", timeout: 30.0)->block(function () {
    doCriticalWork();
});

@cache.memoize(ttl=3600)
def expensive(x):
    return compute(x)

String result = cache.memoize("expensive:" + x, Duration.ofHours(1),
    () -> compute(x));

const result = cache.memoize(`expensive:${x}`, 3600, () => compute(x));

result, err := lytecache.Memoize(cache, fmt.Sprintf("expensive:%v", x), time.Hour,
    func() (T, error) { return compute(x) })

$result = $cache->remember("expensive:{$x}", 3600, fn () => compute($x));

cache.hset("user:101", "status", "active")   # True: the field was new
cache.hset("user:101", "status", "paused")   # False: it replaced a value
cache.hincrby("user:101", "logins")          # 1 -- an atomic counter inside the document
cache.hget("user:101", "status")             # "paused"
cache.hmget("user:101", ["status", "plan"])  # ["paused", None]
cache.hgetall("user:101")                    # {"status": "paused", "logins": 1}
cache.hdel("user:101", "plan")               # 0 -- it wasn't there
cache.get("user:101")                        # the whole document: a hash is just JSON

cache.hset("user:101", "status", "active");             // true: the field was new
cache.hset("user:101", "status", "paused");             // false: it replaced a value
cache.hincrBy("user:101", "logins", 1);                 // 1 -- an atomic counter inside the document
String status = cache.hgetString("user:101", "status"); // "paused"
List<Object> some = cache.hmget("user:101", List.of("status", "plan")); // ["paused", null]
Map<String, Object> all = cache.hgetAll("user:101");    // {status=paused, logins=1}
cache.hdel("user:101", "plan");                         // 0 -- it wasn't there

cache.hset("user:101", "status", "active");   // true: the field was new
cache.hset("user:101", "status", "paused");   // false: it replaced a value
cache.hincrby("user:101", "logins");          // 1 -- an atomic counter inside the document
cache.hget("user:101", "status");             // "paused"
cache.hmget("user:101", ["status", "plan"]);  // ["paused", undefined]
cache.hgetAll("user:101");                    // { status: "paused", logins: 1 }
cache.hdel("user:101", "plan");               // 0 -- it wasn't there

created, err := cache.HSet("user:101", "status", "active") // true: the field was new
logins, err := cache.HIncrBy("user:101", "logins", 1)      // 1 -- an atomic counter inside the document
status, found, err := cache.HGetString("user:101", "status")

var plan Plan
found, err = cache.HGet("user:101", "plan", &plan)          // decode one field into any type
vals, err := cache.HMGet("user:101", []string{"status", "plan"}) // []json.RawMessage, nil if missing
all, err := cache.HGetAll("user:101")                       // map[string]json.RawMessage
n, err := cache.HDel("user:101", "plan")

$cache->hset("user:101", "status", "active");   // true: the field was new
$cache->hset("user:101", "status", "paused");   // false: it replaced a value
$cache->hincrBy("user:101", "logins");          // 1 -- an atomic counter inside the document
$cache->hget("user:101", "status");             // "paused"
$cache->hmget("user:101", ["status", "plan"]);  // ["paused", null]
$cache->hgetAll("user:101");                    // ["status" => "paused", "logins" => 1]
$cache->hdel("user:101", "plan");               // 0 -- it wasn't there

# worker A, after committing a DB change
cache.delete("balance:42")
cache.notify("invalidate", {"key": "balance:42"})

# workers B..N, on the same host
with cache.watch("invalidate") as sub:
    for event in sub:
        local_memo.pop(event.payload["key"], None)

// worker A, after committing a DB change
cache.delete("balance:42");
cache.notify("invalidate", Map.of("key", "balance:42"));

// workers B..N, on the same host
try (Subscription sub = cache.watch("invalidate")) {
    for (Event e : sub) {
        localMemo.remove(e.payload(Map.class).get("key"));
    }
}

// worker A, after committing a DB change
cache.delete("balance:42");
cache.notify("invalidate", { key: "balance:42" });

// workers B..N, on the same host
using sub = cache.watch("invalidate");
for await (const event of sub) {
  localMemo.delete(event.payload.key);
}

// worker A, after committing a DB change
cache.Delete("balance:42")
cache.Notify("invalidate", map[string]any{"key": "balance:42"})

// workers B..N, on the same host
sub, err := cache.Watch([]string{"invalidate"})
defer sub.Close()
for ev := range sub.Events() {
    var p struct{ Key string `json:"key"` }
    ev.Decode(&p)
    delete(localMemo, p.Key)
}

// worker A, after committing a DB change
$cache->delete("balance:42");
$cache->notify("invalidate", ["key" => "balance:42"]);

// a CLI worker on the same host (PHP polls inside the foreach)
foreach ($cache->watch("invalidate") as $event) {
    unset($localMemo[$event->payload()["key"]]);
}

from lytecache import GapError

try:
    with cache.watch("jobs", from_seq=cache.load_cursor("worker-b")) as sub:
        for event in sub:
            handle(event)                              # must be idempotent
            cache.save_cursor("worker-b", event.seq)
except GapError as err:                            # events past retention are gone
    resync()
    cache.save_cursor("worker-b", err.resume_seq)  # accept the loss explicitly

OptionalLong cursor = cache.loadCursor("worker-b");
WatchOptions opts = cursor.isPresent()
        ? WatchOptions.defaults().fromSeq(cursor.getAsLong())
        : WatchOptions.defaults();
try (Subscription sub = cache.watch(opts, "jobs")) {
    for (Event e : sub) {
        handle(e);                                   // must be idempotent
        cache.saveCursor("worker-b", e.seq());
    }
} catch (GapException err) {                         // events past retention are gone
    resync();
    cache.saveCursor("worker-b", err.resumeSeq());   // accept the loss explicitly
}

import { GapError } from "lytecache";

try {
  using sub = cache.watch("jobs", { fromSeq: cache.loadCursor("worker-b") });
  for await (const event of sub) {
    handle(event);                                 // must be idempotent
    cache.saveCursor("worker-b", event.seq);
  }
} catch (err) {
  if (!(err instanceof GapError)) throw err;       // events past retention are gone
  resync();
  cache.saveCursor("worker-b", err.resumeSeq);     // accept the loss explicitly
}

var opts []lytecache.WatchOption
if seq, ok, _ := cache.LoadCursor("worker-b"); ok {
    opts = append(opts, lytecache.FromSeq(seq))
}
sub, err := cache.Watch([]string{"jobs"}, opts...)
defer sub.Close()
for ev := range sub.Events() {
    handle(ev)                                     // must be idempotent
    cache.SaveCursor("worker-b", ev.Seq)
}
var gap *lytecache.GapError
if errors.As(sub.Err(), &gap) {                    // events past retention are gone
    resync()
    cache.SaveCursor("worker-b", gap.ResumeSeq)    // accept the loss explicitly
}

use Lytecache\Exceptions\GapException;

try {
    foreach ($cache->watch("jobs", fromSeq: $cache->loadCursor("worker-b")) as $event) {
        handle($event);                                // must be idempotent
        $cache->saveCursor("worker-b", $event->seq);
    }
} catch (GapException $err) {                          // events past retention are gone
    resync();
    $cache->saveCursor("worker-b", $err->resumeSeq);   // accept the loss explicitly
}

def drop(rec):                       # a ChangeRecord: op, namespace, keys, count, truncated
    if rec.truncated:
        memo.clear()                 # a bulk change: refetch by namespace or prefix
    else:
        for key in rec.keys:
            memo.pop(key, None)

unsubscribe = cache.on_change(drop, events={"set", "delete", "flush"})
cache.set_many(rows)                 # 1,000 keys -> ONE record: count=1000, truncated=True

# cross-process alternative: also publish deletes/flushes to "__cache__"
cache = LyteCache(publish_changes={"delete", "flush"})

Runnable unsubscribe = cache.onChange(rec -> {
    if (rec.truncated()) {
        memo.clear();                // a bulk change: refetch by namespace or prefix
    } else {
        rec.keys().forEach(memo::remove);
    }
}, EnumSet.of(ChangeOp.SET, ChangeOp.DELETE, ChangeOp.FLUSH));

// cross-process alternative: also publish deletes/flushes to "__cache__"
LyteCache cache = LyteCache.builder().publishChanges(ChangeOp.DELETE, ChangeOp.FLUSH).build();

const unsubscribe = cache.onChange((rec) => {
  if (rec.truncated) memo.clear();   // a bulk change: refetch by namespace or prefix
  else for (const key of rec.keys!) memo.delete(key);
}, { events: ["set", "delete", "flush"] });

// cross-process alternative: also publish deletes/flushes to "__cache__"
const cache = new LyteCache({ publishChanges: ["delete", "flush"] });

unsubscribe, err := cache.OnChange(func(rec lytecache.ChangeRecord) {
    if rec.Truncated {
        clear(memo)                  // a bulk change: refetch by namespace or prefix
        return
    }
    for _, k := range rec.Keys {
        delete(memo, k)
    }
}, lytecache.OpSet, lytecache.OpDelete, lytecache.OpFlush)
defer unsubscribe()

// cross-process alternative: also publish deletes/flushes to "__cache__"
cache, err := lytecache.New(lytecache.WithPublishChanges(lytecache.OpDelete, lytecache.OpFlush))

$unsubscribe = $cache->onChange(function (ChangeRecord $rec) use (&$memo) {
    if ($rec->truncated) {
        $memo = [];                  // a bulk change: refetch by namespace or prefix
    } else {
        foreach ($rec->keys as $key) {
            unset($memo[$key]);
        }
    }
}, ["set", "delete", "flush"]);

// cross-process alternative: also publish deletes/flushes to "__cache__"
$cache = new LyteCache(publishChanges: ["delete", "flush"]);

Reference

Storage spec & type codes

Every implementation reads and writes the same schema: one SQLite file in WAL mode, with PRAGMA busy_timeout=5000 so a process that finds the file locked waits instead of failing. Every value carries a value_type code:

Node.js has a single number type rather than Python's int/float or Java's long/double, so its implementation picks type code 2 vs. 3 by shape (Number.isInteger()) rather than by caller intent, using bigint for integers beyond Number.MAX_SAFE_INTEGER. See lytecache-node/SPEC.md for the full rules.

Go, like Python and Java, has distinct integer and floating-point types, so it decides type codes by the value's actual Go type rather than by shape: any Go integer type stores as code 2, float32/float64 as code 3. A uint64 beyond what signed 64-bit integers can hold is rejected outright rather than silently truncated. See lytecache-go/SPEC.md for the full rules.

PHP strings are ambiguous between "raw bytes" and "text," unlike the other languages' distinct byte-array types, so lytecache uses a Bytes wrapper class to mean code 0 explicitly. A plain PHP string always stores as code 1. Objects serialize via JsonSerializable when implemented, else their public properties; a DateTimeInterface serializes to an RFC 3339 string and a BackedEnum to its backing value, matching the conventions above. See lytecache-php/SPEC.md for the full rules.

The zero-config default path derivation (<project-id> = SHA-256 of the resolved working directory) is byte-for-byte identical across every implementation, so all of them land on the same file for the same project directory. See Where is my data? above.

Reference

Glossary

This page uses a handful of abbreviations without expanding them inline. Here's what each one means.

Tools

Command-line interface

Inspect and manipulate any lytecache database file from a shell, the way redis-cli does for a server. It's built entirely on lytecache-go's public API, so it can read and write a file created by any of the five languages above.

Install

brew install lytecache/tap/lytecache
# or, without Homebrew:
curl -fsSL https://raw.githubusercontent.com/lytecache/lytecache-cli/main/install.sh | sh

scoop bucket add lytecache https://github.com/lytecache/scoop-bucket
scoop install lytecache

go install github.com/lytecache/lytecache-cli/cmd/lytecache@latest

Prebuilt binaries, SHA-256 checksums, and .deb/.rpm packages are attached to every GitHub release; a winget manifest ships the same way, pending submission to microsoft/winget-pkgs.

Docker

The CLI is also published as a multi-arch container image (linux/amd64, linux/arm64). It's about 7 MB, built on scratch with nothing in it but the static binary, so you can inspect a cache file without installing anything. lytecache has no server mode: a CLI container runs one command and exits. (The Admin UI does serve a web page, but it isn't a cache server either.)

Mount the same volume your application uses at /var/cache/lytecache and set LYTECACHE_PATH to the value the app already uses, and the CLI needs no --db flag. It reads that variable exactly the way every library on this page does:

docker run --rm -v myapp-cache:/var/cache/lytecache \
  -e LYTECACHE_PATH=/var/cache/lytecache/cache.db \
  ghcr.io/lytecache/lytecache:latest stats

With Compose, add a service like this next to your app. It uses the same LYTECACHE_PATH and mounts the same named volume, which is why it needs no --db:

services:
  # ... your existing app service ...

  lytecache-cli:
    image: ghcr.io/lytecache/lytecache:latest
    profiles: ["tools"]     # keeps it out of `docker compose up`
    environment:
      LYTECACHE_PATH: /var/cache/lytecache/cache.db   # same value your app sets
    volumes:
      - lytecache-data:/var/cache/lytecache            # same volume your app mounts

volumes:
  lytecache-data:

Then docker compose run --rm lytecache-cli stats works (or keys, or no command for the REPL). run reaches a profiled service even though up skips it. Mount the volume on the directory, not on the .db file: WAL mode creates cache.db-wal and cache.db-shm next to it. You can also copy the binary into your own image. It's fully static, so any base image works:

COPY --from=ghcr.io/lytecache/lytecache:latest /lytecache /usr/local/bin/lytecache

lytecache-cli's README has the rest: the --db one-liner for any file on the host, the interactive REPL, a shell alias, and the Compose profile pattern. It also explains why sharing one .db file over NFS or a Kubernetes ReadWriteMany volume isn't supported: SQLite's locking relies on guarantees that network filesystems don't reliably provide.

A session

One-shot commands (script-friendly, shown above) and the interactive REPL share the exact same command tree. The REPL just opens the database once for the whole session instead of reopening it per command. Command names are case-insensitive there, and Ctrl-C cancels the current line without leaving.

Commands

Exit codes

Scripts can rely on these without parsing output:

Cross-language example

Since every implementation shares one on-disk format (see Storage spec above), the CLI can inspect a cache file written by any of them. A Python process wrote this:

cache.set("config", {"theme": "dark", "timeout": 30})

$ lytecache --db ~/.cache/lytecache/abc123.db get config
{
  "theme": "dark",
  "timeout": 30
}

The CLI didn't need Python, a server or an export step. It read the same SQLite file. Two type codes can't be decoded outside their own language: 5 (Python pickle) and 6 (Java serialization). The CLI shows them as (non-portable value: python-pickle, N bytes) instead of failing or printing garbage.

Tools

Admin UI

A local web console for the same database files the CLI reads, like RedisInsight or pgAdmin. It isn't a cache server: it speaks no cache protocol and no application connects to it. It's lytecache-go's public API with a browser on top, started with lytecache ui --port 7070.

It ships in the same binary as the CLI, so there's nothing extra to install. If you haven't installed lytecache yet, see Install in the CLI section, or jump straight to Docker below if you'd rather not install anything locally at all.

Install and run it, step by step

1. Install lytecache

   The CLI and the Admin UI are one binary, so this one install covers both.

   Terminal Copy

   brew install lytecache/tap/lytecache

   On Linux/Windows/from source, or want the Docker image instead? See Install in the CLI section above.

2. Point it at a database (optional)

   If you know the path, name it with --db. If you don't, skip this step. With no flags at all, the UI scans the standard cache locations for you (details below).

3. Run it

   Start it in the foreground first. Ctrl+C stops it, and nothing is left running:

   Terminal Copy

   lytecache ui

   To keep it running across logouts and reboots, install it as a background service.

4. Open it and log in

   Visit http://127.0.0.1:7070 and log in with admin/admin. You land on the fleet dashboard.

5. Change the password before exposing it anywhere

   This only matters if you'll reach the UI from beyond 127.0.0.1, and there it's enforced: the UI refuses to bind anywhere else while the password is still admin. Run lytecache ui passwd to change it.

Quickstart

Open http://127.0.0.1:7070, log in with admin/admin, and you're at the fleet dashboard. Passing --allow-delete turns on delete/flush/maintain; without it, those routes return 403 whether or not the browser shows a button for them.

With no --db, --scan or config file, lytecache ui scans two standard locations. One is <platform cache dir>/lytecache, where the library puts files when your app doesn't set a path. The other is /var/cache/lytecache, the volume-mount convention used in the Docker examples. So the same zero-flag start works on a laptop and in a container. Configure any database explicitly and the scan is skipped.

Using it

Click a database row to open its key browser. The sidebar lists every namespace with its key count. A mismatched namespace is the most common reason a key seems to be missing, and this makes it hard to overlook. Click a key to open the value viewer. JSON is pretty-printed and collapsible, and every value stays hidden until you click "Reveal value". With --allow-delete you also get a delete button, bulk delete, and a flush-namespace control that makes you type the namespace name, so a stray click can't wipe anything.

/ focuses the search box from anywhere (it searches every configured database, not just the one you're in); arrow keys move through a key list, Esc clears the current selection or search.

Docker

The image includes the ui subcommand. Inside the container, bind 0.0.0.0: Docker can't forward a published port to a listener that only accepts loopback. Then restrict it to 127.0.0.1 on the host side:

docker run --rm -p 127.0.0.1:7070:7070 \
  -v myapp-cache:/var/cache/lytecache \
  -v lytecache-ui-config:/home/lytecache/.config/lytecache \
  -e LYTECACHE_UI_PASSWORD=change-me \
  ghcr.io/lytecache/lytecache:latest \
  ui --host 0.0.0.0 --insecure --no-metrics --db orders=/var/cache/lytecache/orders.db

Mount the config volume as well as the cache volume. ui.yaml holds the credentials and the session secret. If it isn't on a volume, the password goes back to admin/admin every time the container is recreated.

With Compose, add it as a profiled service next to your app. As with the CLI service above, using the app's LYTECACHE_PATH and volume is what makes --db unnecessary:

services:
  # ... your existing app service ...

  lytecache-ui:
    image: ghcr.io/lytecache/lytecache:latest
    pull_policy: always    # always check for a newer :latest before (re)creating
    profiles: ["tools"]     # keeps it out of `docker compose up`
    command: ["ui", "--host", "0.0.0.0", "--port", "7070", "--allow-delete", "--insecure", "--no-metrics"]
    environment:
      LYTECACHE_PATH: /var/cache/lytecache/cache.db   # same value your app sets
      LYTECACHE_UI_PASSWORD: ${LYTECACHE_UI_PASSWORD:?set a real admin password first}
    volumes:
      - lytecache-data:/var/cache/lytecache            # same volume your app mounts
      - lytecache-ui-config:/home/lytecache/.config/lytecache
    ports:
      - "7070:7070"

volumes:
  lytecache-data:
  lytecache-ui-config:

Run docker compose --profile tools up -d lytecache-ui, then open http://127.0.0.1:7070. Be aware that this ports: mapping publishes on every network interface the host has, not only loopback. Anyone who can reach the host's IP can reach the UI. To keep it on the host, use "127.0.0.1:7070:7070". --insecure is only reasonable while nothing untrusted shares that network. Once the UI is reachable beyond one machine, replace it with --tls-cert/--tls-key. lytecache-cli's examples/docker-compose.yml has the full example, including a --scan fleet view across several services' caches on one volume.

Pulling a newer image

Docker doesn't fetch a newer :latest on its own. If the image is already on your machine, docker compose up keeps using it. Two ways to get the new one:

# pull, then recreate the container so it actually uses what was just pulled
docker compose pull lytecache-ui
docker compose up -d --force-recreate lytecache-ui

# or do both in one command
docker compose up -d --pull always lytecache-ui

To make that the default, add pull_policy: always to the service, as the snippet above does. Then a plain docker compose up -d lytecache-ui checks for a newer :latest first.

Multiple app services, one Admin UI

This is the most common setup mistake. lytecache-ui has to mount the same volumes your app services write to. Point it at a leftover or unrelated volume and the container still starts. It just shows an empty dashboard, because it's looking somewhere your app isn't.

Two patterns handle this correctly, trading a bit of setup for a bit of isolation:

A third option also works: a separate volume per service. Mount each one into lytecache-ui at its own subdirectory and use repeatable --db name=path flags instead of --scan. Each new service needs more wiring, but a lock or corruption problem in one file can't touch the others.

Running as a background service

lytecache service install --db orders=/data/orders.db --allow-delete
lytecache service start
lytecache service status

service install accepts every flag lytecache ui does and saves them, so the service starts the same way every time. It installs a user LaunchAgent on macOS and a user systemd unit on Linux (--system for a system-wide unit). On Windows it uses the Service Control Manager from an elevated shell, and a Scheduled Task at logon otherwise. To change the flags, for example to add a --db, run service install again. You don't need to uninstall first.

lytecache-cli's docs/ui.md covers the rest: masking sensitive values, the audit log, a paste-ready Prometheus scrape_config with alert rules, reading subscriber lag, and the full default-credential guardrails.