psycache 26.1.0__tar.gz → 26.2.0__tar.gz

psycache-26.2.0/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

psycache-26.2.0/.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt export-subst

{psycache-26.1.0 → psycache-26.2.0}/.github/workflows/ci.yml

@@ -189,6 +189,27 @@ jobs:
           uvx --with tox-uv
           tox run -e docs-doctests
 
+  docs-build:
+    name: Build the documentation site
+    needs: build-package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download pre-built packages
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: Packages
+          path: dist
+      - run: tar xf dist/*.tar.gz --strip-components=1
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          # Keep in sync with tox.ini's base_python_file.
+          python-version-file: .python-version
+      - uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0
+
+      - run: >
+          uvx --with tox-uv
+          tox run -e docs-build -- --strict
+
   install-dev:
     name: Verify dev env
     runs-on: ubuntu-latest
@@ -216,6 +237,7 @@ jobs:
       - install-dev
       - typing
       - docs
+      - docs-build
 
     runs-on: ubuntu-latest
 

{psycache-26.1.0 → psycache-26.2.0}/.gitignore

@@ -10,3 +10,4 @@
 *.py[co]
 dist
 htmlcov
+site

psycache-26.2.0/.readthedocs.yaml

@@ -0,0 +1,26 @@
+---
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    # Keep in sync with .python-version and tox.ini's docs base_python.
+    python: "3.14"
+  jobs:
+    create_environment:
+      # Need the tags to calculate the version.
+      - git fetch --tags
+
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+
+    build:
+      html:
+        # Set canonical URL
+        - sed -i "s|https://psycache.hynek.me/|$READTHEDOCS_CANONICAL_URL|g" zensical.toml
+        - uvx --with tox-uv tox run -e docs-build
+        # Zensical builds into site/; hand it to Read the Docs.
+        # https://docs.readthedocs.com/platform/latest/intro/zensical.html
+        - mkdir -p $READTHEDOCS_OUTPUT/html/
+        - cp --recursive site/* $READTHEDOCS_OUTPUT/html/

psycache-26.2.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Calendar Versioning](https://calver.org/).
+
+The **first number** of the version is the year.
+The **second number** is incremented with each release, starting at 1 for each year.
+The **third number** is for emergencies when we need to start branches for older releases.
+
+> [!IMPORTANT]
+> This package is currently in beta and looks forward to your feedback.
+> The code is battle-tested, but APIs may change.
+
+<!-- changelog follows -->
+
+## [26.2.0](https://github.com/hynek/psycache/compare/26.1.0...26.2.0) - 2026-06-25
+
+### Added
+
+- Proper docs at <https://psycache.hynek.me/>.
+  [#2](https://github.com/hynek/psycache/pull/2)
+
+
+## Changed
+
+- Replaced *attrs* by hand-written classes.
+  Sadly, the documentation ecosystem is not ready and *dataclasses* are not fit for public APIs.
+  This means *psycopg* is the **only** dependency.
+  [#3](https://github.com/hynek/psycache/pull/3)
+
+
+## [26.1.0](https://github.com/hynek/psycache/tree/26.1.0) - 2026-06-24
+
+Initial release.

psycache-26.2.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: psycache
+Version: 26.2.0
+Summary: A psycopg-Backed PostgreSQL Cache
+Project-URL: Documentation, https://psycache.hynek.me/
+Project-URL: Changelog, https://github.com/hynek/psycache/blob/main/CHANGELOG.md
+Project-URL: GitHub, https://github.com/hynek/psycache
+Project-URL: Funding, https://github.com/sponsors/hynek
+Project-URL: Tidelift, https://tidelift.com?utm_source=lifter&utm_medium=referral&utm_campaign=hynek
+Project-URL: Mastodon, https://mastodon.social/@hynek
+Project-URL: Bluesky, https://bsky.app/profile/hynek.me
+Project-URL: Twitter, https://twitter.com/hynek
+Author-email: Hynek Schlawack <hs@ox.cx>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,postgres,postgresql,psycopg
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: psycopg
+Provides-Extra: pool
+Requires-Dist: psycopg-pool; extra == 'pool'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client; extra == 'prometheus'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk; extra == 'sentry'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy; extra == 'sqlalchemy'
+Provides-Extra: sqlalchemy-asyncio
+Requires-Dist: sqlalchemy[asyncio]; extra == 'sqlalchemy-asyncio'
+Description-Content-Type: text/markdown
+
+# *psycache*: *psycopg*-Backed PostgreSQL Cache
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-C06524)](https://github.com/hynek/psycache/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/Docs-Read%20the%20Docs-black)](https://psycache.hynek.me/)
+[![PyPI version](https://img.shields.io/pypi/v/psycache)](https://pypi.org/project/psycache/)
+[![No AI slop inside.](https://img.shields.io/badge/no-slop-purple)](https://github.com/hynek/psycache/blob/main/.github/AI_POLICY.md)
+
+
+A simple key-value cache that stores JSON in PostgreSQL through [*psycopg*](https://www.psycopg.org/) 3, with TTL-based expiration and pluggable instrumentation.
+
+- Sync and async ✔︎
+- Type-safe ✔︎
+- Adapters for [SQLAlchemy](https://www.sqlalchemy.org) and [*psycopg-pool*](https://www.psycopg.org/psycopg3/docs/api/pool.html) ✔︎
+
+---
+
+*psycache* uses an [unlogged table](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-UNLOGGED) for performance and stores values as [JSONB](https://www.postgresql.org/docs/current/datatype-json.html) 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`](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine) (or [`AsyncEngine`](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#sqlalchemy.ext.asyncio.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:
+
+```console
+$ uv pip install "psycache[sqlalchemy]"
+```
+
+Initialize the cache table once (`python -Im psycache init-db <dsn>` does the same from the shell), then store and retrieve JSON with a TTL:
+
+```python
+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/>**.
+
+
+<!-- --8<-- [start:credits] -->
+## Credits
+
+*psycache* is written by [Hynek Schlawack](https://hynek.me/) and distributed under the terms of the [MIT license](https://choosealicense.com/licenses/mit/).
+
+The development is kindly supported by my employer [Variomedia AG](https://www.variomedia.de/) and all my fabulous [GitHub Sponsors](https://github.com/sponsors/hynek).
+<!-- --8<-- [end:credits] -->

psycache-26.2.0/README.md

@@ -0,0 +1,72 @@
+# *psycache*: *psycopg*-Backed PostgreSQL Cache
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-C06524)](https://github.com/hynek/psycache/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/Docs-Read%20the%20Docs-black)](https://psycache.hynek.me/)
+[![PyPI version](https://img.shields.io/pypi/v/psycache)](https://pypi.org/project/psycache/)
+[![No AI slop inside.](https://img.shields.io/badge/no-slop-purple)](https://github.com/hynek/psycache/blob/main/.github/AI_POLICY.md)
+
+
+A simple key-value cache that stores JSON in PostgreSQL through [*psycopg*](https://www.psycopg.org/) 3, with TTL-based expiration and pluggable instrumentation.
+
+- Sync and async ✔︎
+- Type-safe ✔︎
+- Adapters for [SQLAlchemy](https://www.sqlalchemy.org) and [*psycopg-pool*](https://www.psycopg.org/psycopg3/docs/api/pool.html) ✔︎
+
+---
+
+*psycache* uses an [unlogged table](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-UNLOGGED) for performance and stores values as [JSONB](https://www.postgresql.org/docs/current/datatype-json.html) 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`](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine) (or [`AsyncEngine`](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#sqlalchemy.ext.asyncio.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:
+
+```console
+$ uv pip install "psycache[sqlalchemy]"
+```
+
+Initialize the cache table once (`python -Im psycache init-db <dsn>` does the same from the shell), then store and retrieve JSON with a TTL:
+
+```python
+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/>**.
+
+
+<!-- --8<-- [start:credits] -->
+## Credits
+
+*psycache* is written by [Hynek Schlawack](https://hynek.me/) and distributed under the terms of the [MIT license](https://choosealicense.com/licenses/mit/).
+
+The development is kindly supported by my employer [Variomedia AG](https://www.variomedia.de/) and all my fabulous [GitHub Sponsors](https://github.com/sponsors/hynek).
+<!-- --8<-- [end:credits] -->

{psycache-26.1.0 → psycache-26.2.0}/conftest.py

@@ -6,14 +6,14 @@ import importlib.util
 
 from collections.abc import AsyncIterator, Iterator
 from contextlib import asynccontextmanager, contextmanager
+from dataclasses import dataclass
 from doctest import ELLIPSIS
 
-import attrs
 import psycopg
 import pytest
 
 from sybil import Sybil
-from sybil.parsers import myst
+from sybil.parsers import markdown
 
 from psycache import AsyncPostgresCache, PostgresCache, init_db
 from psycache.instrumentation.prometheus import PrometheusInstrumentation
@@ -26,11 +26,13 @@ collect_ignore = [
     if importlib.util.find_spec(name) is None
 ]
 
+# The docs are CommonMark/Material (Zensical), so use the Markdown parsers.
+# Executable examples use plain ```python fences; illustrative snippets are
+# preceded by an HTML comment <!-- skip: next -->.
 pytest_collect_file = Sybil(
     parsers=[
-        myst.DocTestDirectiveParser(optionflags=ELLIPSIS),
-        myst.PythonCodeBlockParser(doctest_optionflags=ELLIPSIS),
-        myst.SkipParser(),
+        markdown.PythonCodeBlockParser(doctest_optionflags=ELLIPSIS),
+        markdown.SkipParser(),
     ],
     patterns=["*.md"],
     fixtures=["psycache_database"],
@@ -77,7 +79,7 @@ _INSTRUMENTATIONS = [
 ]
 
 
-@attrs.frozen
+@dataclass
 class _RawCachePool:
     """
     A minimal CachePool that opens a psycopg connection per checkout.
@@ -106,7 +108,7 @@ def _cache(request: pytest.FixtureRequest, db_dsn: str):
     return PostgresCache(_RawCachePool(db_dsn), instrumentations=request.param)
 
 
-@attrs.frozen
+@dataclass
 class _RawAsyncCachePool:
     """
     A minimal AsyncCachePool that opens a psycopg connection per checkout.

psycache-26.2.0/docs/api-types.md

@@ -0,0 +1,9 @@
+---
+icon: material/api
+---
+
+# Types & Protocols
+
+Most parts of *psycache* can be replaced by implementing the appropriate protocols.
+
+::: psycache.typing

psycache-26.2.0/docs/api.md

@@ -0,0 +1,58 @@
+---
+icon: material/api
+---
+
+# API Reference
+
+## Core
+
+::: psycache
+    options:
+      members:
+        - init_db
+        - PostgresCache
+        - AsyncPostgresCache
+        - CleanupService
+        - AsyncCleanupService
+
+
+## Pool adapters
+
+### *psycopg_pool*
+
+::: psycache.psycopg_pool.PsycopgCachePool
+    options:
+      show_root_heading: true
+      members: false
+      heading_level: 4
+
+::: psycache.psycopg_pool.AsyncPsycopgCachePool
+    options:
+      show_root_heading: true
+      members: false
+      heading_level: 4
+
+### SQLAlchemy
+
+::: psycache.sqlalchemy.SQLAlchemyCachePool
+    options:
+      show_root_heading: true
+      members: false
+
+::: psycache.sqlalchemy.AsyncSQLAlchemyCachePool
+    options:
+      show_root_heading: true
+      members: false
+
+
+## Instrumentation
+
+::: psycache.instrumentation.prometheus.PrometheusInstrumentation
+    options:
+      show_root_heading: true
+      members: false
+
+::: psycache.instrumentation.sentry.SentryInstrumentation
+    options:
+      show_root_heading: true
+      members: false

psycache-26.2.0/docs/assets/javascript/readthedocs.js

@@ -0,0 +1,8 @@
+document.addEventListener("DOMContentLoaded", function(event) {
+    // Trigger Read the Docs' search addon instead of Zensical default
+    document.querySelector(".md-search").addEventListener("click", (e) => {
+        e.preventDefault();
+        const event = new CustomEvent("readthedocs-search-show");
+        document.dispatchEvent(event);
+    });
+});

psycache-26.2.0/docs/async.md

@@ -0,0 +1,64 @@
+# Async
+
+*psycache* ships asyncio-native API that mirror the synchronous ones.
+
+So, [`AsyncPostgresCache`][psycache.AsyncPostgresCache] exposes `get_raw`, `put_raw`, `remove`, `cleanup_expired`, and `flush` – all async methods with the same signatures as their synchronous counterparts.
+It needs an [`AsyncCachePool`][psycache.typing.AsyncCachePool]: anything with an async `connect()` that yields a [`psycopg.AsyncConnection`][].
+
+Two adapters are included, again, mirroring their synchronous counterparts.
+
+
+## SQLAlchemy
+
+[`AsyncSQLAlchemyCachePool`][psycache.sqlalchemy.AsyncSQLAlchemyCachePool] wraps a SQLAlchemy [`AsyncEngine`][sqlalchemy.ext.asyncio.AsyncEngine] (requires `psycache[sqlalchemy-asyncio]`):
+
+```python
+import asyncio
+
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from psycache import AsyncPostgresCache
+from psycache.sqlalchemy import AsyncSQLAlchemyCachePool
+
+
+async def main() -> None:
+    engine = create_async_engine(
+        "postgresql+psycopg://psycache@127.0.0.1/psycache"
+    )
+    cache = AsyncPostgresCache(AsyncSQLAlchemyCachePool(engine))
+
+    await cache.put_raw("my-key", {"user": "alice"}, ttl=300)
+    value = await cache.get_raw("my-key")
+
+    await engine.dispose()
+
+
+asyncio.run(main())
+```
+
+
+## psycopg-pool
+
+[`AsyncPsycopgCachePool`][psycache.psycopg_pool.AsyncPsycopgCachePool] wraps a [`psycopg_pool.AsyncConnectionPool`][psycopg_pool.AsyncConnectionPool] (requires `psycache[pool]`):
+
+```python
+import asyncio
+
+from psycopg_pool import AsyncConnectionPool
+
+from psycache import AsyncPostgresCache
+from psycache.psycopg_pool import AsyncPsycopgCachePool
+
+
+async def main() -> None:
+    async with AsyncConnectionPool(
+        "postgresql://psycache@127.0.0.1/psycache", open=False
+    ) as pool:
+        cache = AsyncPostgresCache(AsyncPsycopgCachePool(pool))
+
+        await cache.put_raw("my-key", {"user": "alice"}, ttl=300)
+        value = await cache.get_raw("my-key")
+
+
+asyncio.run(main())
+```

psycache-26.2.0/docs/cleanup.md

@@ -0,0 +1,69 @@
+# Background Cleanup
+
+*psycache* ignores expired keys when reading, but their rows stick around until something deletes them.
+You can call [`PostgresCache.cleanup_expired()`][psycache.PostgresCache.cleanup_expired] yourself, or let *psycache* do it for you in the background.
+
+
+## A cleanup thread
+
+For synchronous pools, [`PostgresCache.start_cleanup_thread()`][psycache.PostgresCache.start_cleanup_thread] starts a daemon thread that periodically deletes expired entries.
+Use it as a context manager to stop the thread automatically:
+
+```python
+from sqlalchemy import create_engine
+
+from psycache import PostgresCache
+from psycache.sqlalchemy import SQLAlchemyCachePool
+
+
+engine = create_engine("postgresql+psycopg://psycache@127.0.0.1/psycache")
+cache = PostgresCache(SQLAlchemyCachePool(engine))
+
+
+with cache.start_cleanup_thread(interval=60):
+    ...  # your application runs here
+```
+
+Or manage its lifecycle manually through the returned [`CleanupService`][psycache.CleanupService]:
+
+```python
+svc = cache.start_cleanup_thread(interval=60)
+try:
+    ...  # your application runs here
+finally:
+    svc.stop()
+
+engine.dispose()
+```
+
+## ... or a cleanup task
+
+For async pools, use [`AsyncPostgresCache.start_cleanup_task()`][psycache.AsyncPostgresCache.start_cleanup_task] inside a running event loop.
+It starts an [`asyncio.Task`][] that periodically deletes expired entries and can be used as an async context manager.
+
+Otherwise, it mirrors the behavior of [`PostgresCache.start_cleanup_thread()`][psycache.PostgresCache.start_cleanup_thread]:
+
+```python
+import asyncio
+
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from psycache import AsyncPostgresCache
+from psycache.sqlalchemy import AsyncSQLAlchemyCachePool
+
+
+aengine = create_async_engine("postgresql+psycopg://psycache@127.0.0.1/psycache")
+acache = AsyncPostgresCache(AsyncSQLAlchemyCachePool(aengine))
+
+async def main():
+    async with acache.start_cleanup_task(interval=60):
+        ...  # your application runs here
+
+    svc = acache.start_cleanup_task(interval=60)
+    try:
+        ...  # your application runs here
+    finally:
+        await svc.stop()
+
+asyncio.run(main())
+```

psycache-26.2.0/docs/getting-started.md

@@ -0,0 +1,86 @@
+---
+icon: material/rocket-launch
+---
+
+# Getting Started
+
+!!! note
+
+    This documentation uses [*uv*](https://docs.astral.sh/uv/) for package management and so should you.
+    It's trivial, though, to translate the commands to your package manager of choice.
+
+
+## Installation
+
+*psycache* is published on [PyPI](https://pypi.org/project/psycache/), so install it with your favorite package manager:
+
+```console
+$ uv pip install psycache
+```
+
+The core package depends only on [*psycopg*](https://www.psycopg.org/).
+The pool adapters are optional and each lives behind an extra.
+The examples here use SQLAlchemy, so install the `sqlalchemy` extra too:
+
+```console
+$ uv pip install "psycache[sqlalchemy]"
+```
+
+!!! tip
+
+    See [Connection Pool Adapters][] for the full list of extras and how to bring your own pool.
+
+
+## Initialize the database
+
+*psycache* keeps everything in a single [unlogged table](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-UNLOGGED).
+Create it once – either from Python using [`init_db()`][psycache.init_db]:
+
+```python
+import psycopg
+
+import psycache
+
+
+with psycopg.connect(
+    "postgresql://psycache@127.0.0.1/psycache", autocommit=True
+) as conn:
+    psycache.init_db(conn)
+```
+
+…or from the command line:
+
+```console
+$ python -Im psycache init-db postgresql://psycache@127.0.0.1/psycache
+```
+
+This creates the `psycache` unlogged table and an index on `expires_at`.
+[`init_db()`][psycache.init_db] is idempotent, so running it again leaves existing data untouched.
+
+
+## Store and retrieve
+
+Assuming you already have a SQLAlchemy [`Engine`][sqlalchemy.engine.Engine] in your application, wrap it in a [`SQLAlchemyCachePool`][psycache.sqlalchemy.SQLAlchemyCachePool] and hand it to [`PostgresCache`][psycache.PostgresCache]:
+
+```python
+from sqlalchemy import create_engine
+
+from psycache import PostgresCache
+from psycache.sqlalchemy import SQLAlchemyCachePool
+
+
+engine = create_engine("postgresql+psycopg://psycache@127.0.0.1/psycache")
+cache = PostgresCache(SQLAlchemyCachePool(engine))
+
+# Store a value with a TTL of 300 seconds.
+cache.put_raw("user:alice", {"score": 42}, ttl=300)
+
+# Retrieve it (returns None if missing or expired).
+value = cache.get_raw("user:alice")
+# {"score": 42}
+
+engine.dispose()
+```
+
+That's it!
+You've got a working cache.

psycache-26.2.0/docs/index.md

@@ -0,0 +1,39 @@
+# psycache
+
+*A psycopg-backed PostgreSQL cache.*
+
+---
+
+**psycache** is a simple key-value cache that stores JSON in PostgreSQL through [*psycopg*](https://www.psycopg.org/psycopg3/docs/) 3, with TTL-based expiration, and pluggable instrumentation.
+
+- **Sync and async**: [`PostgresCache`][psycache.PostgresCache] and a fully async [`AsyncPostgresCache`][psycache.AsyncPostgresCache] that mirrors its API.
+
+- **Type-safe**: fully typed, checked using Mypy, *ty*, Pyrefly, and Pyright.
+
+- **Bring your own pool**: first-class adapters for [SQLAlchemy](https://www.sqlalchemy.org) and [*psycopg-pool*](https://www.psycopg.org/psycopg3/docs/api/pool.html), or implement a tiny protocol (*one* method!) yourself.
+
+
+## Why PostgreSQL?
+
+Modern PostgreSQL on modern servers is fast enough for almost everyone's use cases.
+
+*psycache* stores values as [JSONB](https://www.postgresql.org/docs/current/datatype-json.html) in an [unlogged table](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-UNLOGGED).
+Unlogged tables skip the [write-ahead log](https://www.postgresql.org/docs/current/wal.html) for speed, while JSONB keeps values flexible and queryable.
+
+It's a great fit when you **already run PostgreSQL** and want a fast cache without operating another piece of infrastructure like Redis.
+You can even share an existing SQLAlchemy [`Engine`][sqlalchemy.engine.Engine] (or [`AsyncEngine`][sqlalchemy.ext.asyncio.AsyncEngine]) with *psycache*, so the cache rides on the connections you already have.
+
+
+## Get started
+
+<div class="grid cards" markdown>
+
+- :material-rocket-launch: **[Getting Started](getting-started.md)**: install *psycache*, initialize the table, and store your first value.
+- :material-book-open-variant: **[Raw Queries][]**: Our low-level API: `get_raw`, `put_raw`, TTLs, and instrumentation span names.
+- :material-cog: **[Connection Pool Adapters][]**: wire up SQLAlchemy, *psycopg-pool*, or your own pool.
+- :material-beach: **[Quality of Life][]**: embrace the simple life.
+
+</div>
+
+
+--8<-- "README.md:credits"