psycache

A Psycopg-backed PostgreSQL cache

A key-value cache that stores JSON in PostgreSQL through Psycopg 3, with TTL-based expiration and pluggable instrumentation.

• Sync and async ✔︎
• Type-safe ✔︎
• Adapters for SQLAlchemy and psycopg-pool ✔︎

psycache uses an unlogged table for performance and stores values as JSONB for versatility.

It's a great fit when you already have PostgreSQL and need a fast cache without introducing another piece of infrastructure like Redis. For example, you can safely share a SQLAlchemy Engine (or AsyncEngine) with psycache.

Quick Start

Let's hitch-hike on a SQLAlchemy engine as a quick example!

First, install psycache from PyPI with the sqlalchemy extra:

$ uv pip install "psycache[sqlalchemy]"

Initialize the cache table once¹ then store and retrieve JSON with a TTL:

import psycopg

from sqlalchemy import create_engine

import psycache

from psycache import PostgresCache
from psycache.sqlalchemy import SQLAlchemyCachePool


with psycopg.connect(
    "postgresql://psycache@127.0.0.1/psycache", autocommit=True
) as conn:
    psycache.init_db(conn)

engine = create_engine("postgresql+psycopg://psycache@127.0.0.1/psycache")
cache = PostgresCache(SQLAlchemyCachePool(engine))

cache.put_raw("user:alice", {"score": 42}, ttl=300)
value = cache.get_raw("user:alice")
# {"score": 42}

engine.dispose()

Documentation

Full documentation lives at https://psycache.hynek.me/.

Release Information

Changed

• psycache is now considered stable and the usual backwards-compatibility promises apply.

• The schema parameters of init_db(), PostgresCache, and AsyncPostgresCache and the --schema option of init-db have been replaced by table and --table. They take the name of the cache table, optionally schema-qualified with a dot (for example, app_cache.psycache).

Fixed

• sqlalchemy: Imports from sqlalchemy.ext.asyncio are now protected using if TYPE_CHECKING:. This fixes the runtime dependency on greenlet on SQLALchemy 2.1+, even if psycache.sqlalchemy.AsyncSQLAlchemyCachePool is not used. #11

Full Changelog →

Credits

psycache is written by Hynek Schlawack and distributed under the terms of the MIT license.

The development is kindly supported by my employer Variomedia AG and all my fabulous GitHub Sponsors.