postgres-cache

Postgres Cache is a single purpose library to cover a need of a distributed cache and not willing to use Redis/Valkey/Memcached or other external caching systems.

Idea of the library is to store persisted cache in Postgres, and utilize couple of specific optimizations to make it behave comparable with other caching solutions. Local in-memory cache with invalidation via LISTEN/NOTIFY are among those optimizations.

Features

• Pure Postgres backend – no bespoke services, just a single table plus triggers and LISTEN/NOTIFY for invalidations.

• TTL + forced invalidation – each entry stores an optional expires_at, and clients can delete rows explicitly.

• Dogpile protection – get_or_set uses PostgreSQL advisory locks so only one client recomputes missing items.

• Local in-memory cache – every client keeps a bounded TTL cache that is updated/evicted via database notifications.

• Configurable Postgres objects – notify_channel controls the LISTEN/NOTIFY channel, and schema_prefix namespaces every table/function created by the library.

• Optional notifications – set disable_notiffy=True to skip LISTEN/NOTIFY when Postgres connection budgets are tight.

• Load harness – runnable script that spins up many clients to assert read consistency and provide latency stats.

Usage

Install the library from PyPI:

pip install postgres-cache

PostgreSQL-backed cache

import asyncio
from postgres_cache import CacheSettings, PostgresCache

async def main():
    dsn = "postgresql://cache_user:cache_pass@localhost:5432/cache_proto"
    settings = CacheSettings(
        dsn=dsn,
        notify_channel="cache_events_marketing",
        schema_prefix="marketing_",
    )
    await PostgresCache.init_db(settings)
    async with PostgresCache(settings) as cache:
        await cache.set("profile:123", {"name": "Ava"}, ttl_seconds=300)
        user = await cache.get_or_set(
            "profile:456",
            loader=lambda: {"name": "Nova"},
            ttl_seconds=120,
        )
        print(user)

asyncio.run(main())

The clients automatically:

• Maintain a bounded local cache.
• Listen on notify_channel so updates/deletes on any node evict stale entries everywhere.
• Use advisory locks on get_or_set to avoid thundering herds.

Null cache

Need a drop-in implementation that always hits the loader (for local dev or tests)?

from postgres_cache import NullCache

async with NullCache() as cache:
    await cache.set("noop", "value")  # does nothing
    assert await cache.get("noop") is None

Development setup

Python 3.11+ and uv are required for local development.

• make tests – run the pytest suite (requires Postgres running via docker compose up).
• make lint-and-format – format & lint code
• make harness-load-test – launch the load harness against a local Postgres.
• make examples-basic-usage / make examples-fastapi-api-cache – run example scripts.

Load testing

See harness/README.md for the load-test instructions and make harness-load-test helper.

Benchmarking

See benchmarks/README.md for installation steps, CLI flags, and instructions for adding more backends to the report. Note that these numbers come from an intentionally narrow, unrealistic benchmark that ignores network latency to focus purely on cache/DB interactions on the same host.

Benchmark summary

postgres-no-local-cache disables the client-side cache (local_max_entries=0), so the benchmark issues direct Postgres reads without invalidating values pulled from the backend. postgres-no-notify turns off LISTEN/NOTIFY fan-out (disable_notiffy=True), which means no backend invalidations occur and only the local TTL policy expires entries. Interpretation: "optimizations" implemented in this libray, does not provide any advantage.

License

Released under the MIT License.