Skip to content

Caching Specification

Version: 1.31 Status: Describes the code as it is Audience: Database architects, schema designers, API developers, operations engineers


1. Overview

fraiseql.caching is a result cache you wire into your own code. Nothing in create_fraiseql_app turns it on, and no FraiseQLConfig setting or environment variable configures it: you build the cache in Python and call it.

from fraiseql.caching import (
    CacheBackend,         # protocol: get / set / delete / delete_pattern
    CacheConfig,          # enabled, default_ttl, max_ttl, cache_errors, key_prefix
    CacheKeyBuilder,      # deterministic keys, tenant id second
    CacheStats,           # hits / misses / errors, hit_rate
    CachedRepository,     # FraiseQLRepository wrapper caching find / find_one (see 2.6)
    CascadeRule,          # source_domain -> target_domain
    PostgresCache,        # backend: a PostgreSQL UNLOGGED table
    PostgresCacheError,
    ResultCache,          # get_or_set, invalidate, invalidate_pattern, stats
    SchemaAnalyzer,       # derives CascadeRules from a GraphQL schema
    cached_query,         # decorator over ResultCache.get_or_set
    setup_auto_cascade_rules,
)

What it gives you:

  • A shared cache: PostgresCache stores entries in an UNLOGGED table, so every instance using the same database sees them.
  • TTL expiry: each entry has an expires_at; expired entries are never returned.
  • Explicit invalidation: by key, or by a * pattern.

What it doesn't do: it doesn't cache whole GraphQL responses (CachedRepository caches each find / find_one), it doesn't invalidate anything when a class mutation runs (CachedRepository.execute_function does), and the CASCADE rules it can derive from the schema don't invalidate ResultCache entries (see Section 4).


2. Query Result Caching

2.1 CacheConfig

from dataclasses import dataclass


@dataclass
class CacheConfig:
    enabled: bool = True       # False: get_or_set always runs the function
    default_ttl: int = 300     # seconds, when the call gives no ttl
    max_ttl: int = 3600        # every ttl is capped to this
    cache_errors: bool = False # see below
    key_prefix: str = "fraiseql"

cache_errors doesn't cache exceptions (a function that raises is never cached). It decides what happens when the backend fails on a read: False runs the function and returns its result without storing it; True runs it and still tries to store the result.

2.2 ResultCache

from psycopg_pool import AsyncConnectionPool

from fraiseql.caching import CacheConfig, PostgresCache, ResultCache

pool = AsyncConnectionPool("postgresql://localhost/mydb", open=False)
await pool.open()

cache = ResultCache(
    backend=PostgresCache(connection_pool=pool),
    config=CacheConfig(default_ttl=300, max_ttl=3600),
)


async def load_top_sellers() -> list[dict]:
    async with pool.connection() as conn:
        cur = await conn.execute("SELECT data FROM v_top_seller ORDER BY rank LIMIT 10")
        return [row[0] for row in await cur.fetchall()]


top = await cache.get_or_set("fraiseql:top_sellers", load_top_sellers, ttl=600)

get_or_set(key, func, ttl=None) returns the stored value when there is one, and otherwise awaits func(), stores its result for min(ttl or default_ttl, max_ttl) seconds and returns it. A result of None is stored but reads back as a miss, so it's recomputed every time. Backend errors are logged (fraiseql.caching.result_cache, WARNING), counted in stats.errors, and never raised.

The value must be JSON-serializable for PostgresCache: it's stored as JSONB and read back as JSON. A value json.dumps can't encode (a datetime, a UUID, a dataclass) isn't stored: the failure is logged and counted as an error, and the next call runs the function again.

2.3 cached_query

from fraiseql.caching import cached_query


@cached_query(cache, ttl=600)
async def top_sellers(region: str) -> list[dict]:
    async with pool.connection() as conn:
        cur = await conn.execute(
            "SELECT data FROM v_top_seller WHERE region = %s ORDER BY rank LIMIT 10", (region,)
        )
        return [row[0] for row in await cur.fetchall()]


await top_sellers(region="emea")                   # computed and stored
await top_sellers(region="emea")                   # from the cache
await top_sellers(region="emea", skip_cache=True)  # computed, not stored

The key is the function name followed by its positional arguments and its sorted keyword arguments: top_sellers:region:emea. It has no prefix and no tenant id; pass key_func= (called with the keyword arguments) to build your own, e.g. with a tenant:

@cached_query(cache, ttl=600, key_func=lambda tenant_id, region: f"fraiseql:{tenant_id}:top_sellers:{region}")
async def tenant_top_sellers(tenant_id: str, region: str) -> list[dict]: ...

2.4 Cache Keys (CacheKeyBuilder)

from fraiseql.caching import CacheKeyBuilder

CacheKeyBuilder().build_key(
    "v_user",
    tenant_id="org_123",
    filters={"status": "active"},
    order_by=[("name", "asc")],
    limit=20,
    offset=0,
)
# 'fraiseql:org_123:v_user:status:active:order:name:asc:limit:20:offset:0'

The parts are joined with :: the prefix, the tenant id (when given), the query name, each filter sorted by field (field:value, or field:op:value for an operator dict), order:field:direction, limit:N, offset:N, then any extra keyword arguments. A list of strings is sorted and joined with commas; another list becomes an 8-character hash. build_mutation_pattern("user") returns fraiseql:user:*.

Put the tenant id in every key of tenant data: two tenants then never read each other's entries. Nothing adds it for you outside CachedRepository.

2.5 Invalidation

await cache.invalidate("fraiseql:top_sellers")           # one key
await cache.invalidate_pattern("fraiseql:org_123:*")      # every key of a tenant

invalidate_pattern turns * into SQL LIKE's % (so _ in a pattern also matches any one character). Call them where your code writes, e.g. after the mutation resolver's SQL function returns. Errors are logged, not raised.

2.6 CachedRepository

CachedRepository(base_repository, cache) wraps a FraiseQLRepository. find and find_one take the wrapped repository's arguments (view_name, field_name, info, **kwargs) plus keyword-only skip_cache=False and cache_ttl=None, go through get_or_set, and return what the wrapped method returns: on a hit, a RustResponseBytes with the bytes of the response that was cached (stored as its JSON text, so key order is kept). A find_one that finds nothing (None) isn't cached. Other methods are delegated.

The key is <prefix>:<tenant_id>:<view>:q:<hash> (<prefix>:<view>:q:<hash> when the repository context has no tenant_id; <view>:one for find_one). The hash covers field_name, the keyword arguments and, with info, the GraphQL selection (fields, aliases, fragments, variables), so { users { id } } and { users { id name } } don't share an entry.

from fraiseql.caching import CachedRepository, PostgresCache, ResultCache
from fraiseql.db import FraiseQLRepository

cache = ResultCache(PostgresCache(pool))


async def context_getter(request, user=None):
    repo = FraiseQLRepository(pool, context={"tenant_id": request.headers["x-tenant"]})
    return {"db": CachedRepository(repo, cache), "user": user}


@fraiseql.query
async def users(info) -> list[User]:
    return await info.context["db"].find("v_user", "users", info, cache_ttl=60)

execute_function(name, input) and execute_function_with_context(...) invalidate, for every tenant, the keys of the entity the function writes: fn_update_user (or update_user, app.fn_update_user) those of user, users, v_user, v_users, tv_user and tv_users, in any schema; a multi-word entity (fn_create_blog_post) also those of its last word (post). invalidate_view("v_user", all_tenants=True) does it for one view.

A class mutation (@fraiseql.mutation class CreateUser) calls its SQL function without going through the repository, so it invalidates nothing: rely on the TTL, or call invalidate_view("v_user") on the CachedRepository from your code after the write.

2.7 Backends

A backend implements the CacheBackend protocol:

from typing import Any, Protocol


class CacheBackend(Protocol):
    async def get(self, key: str) -> Any | None: ...
    async def set(self, key: str, value: Any, ttl: int) -> None: ...
    async def delete(self, key: str) -> bool: ...
    async def delete_pattern(self, pattern: str) -> int: ...

PostgresCache(connection_pool, table_name="fraiseql_cache", auto_initialize=True) creates its table on first use (table_name may be schema-qualified, e.g. "app.fraiseql_cache"). With auto_initialize=False it doesn't: create the table yourself, or call await backend.initialize() once (which always creates it):

CREATE UNLOGGED TABLE IF NOT EXISTS fraiseql_cache (
    cache_key TEXT PRIMARY KEY,
    cache_value JSONB NOT NULL,
    expires_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX IF NOT EXISTS fraiseql_cache_expires_idx ON fraiseql_cache (expires_at);

An UNLOGGED table skips the write-ahead log: writes are cheaper, and PostgreSQL empties the table after a crash, which a cache can afford. It isn't replicated to standbys either.

Besides the protocol methods, it has exists(key), ping(), get_stats() ( total_entries, expired_entries, active_entries, table_size_bytes), cleanup_expired() (deletes the expired rows, returns how many) and clear_all(). Expired rows aren't returned but stay in the table until cleanup_expired() runs; schedule it:

import asyncio


async def purge_cache(backend: PostgresCache) -> None:
    while True:
        await backend.cleanup_expired()
        await asyncio.sleep(600)

Any other object with the four protocol methods works as a backend, e.g. one on Redis (SET key value EX ttl, SCAN + DEL for patterns).

2.8 Monitoring

stats = cache.get_stats()            # CacheStats(hits=..., misses=..., errors=...)
print(f"hit rate: {stats.hit_rate:.1f}%")  # 0-100
cache.reset_stats()

print(await cache.backend.get_stats())  # PostgresCache: entries and table size

CacheStats counts this process's calls only. A growing errors count usually means values that can't be stored (not JSON) or a backend that can't be reached.

-- Occupancy, from any instance
SELECT
    COUNT(*)                                    AS total_entries,
    COUNT(*) FILTER (WHERE expires_at <= NOW()) AS expired_entries,
    pg_size_pretty(pg_total_relation_size('fraiseql_cache')) AS table_size
FROM fraiseql_cache;

3. What Isn't Cached

  • GraphQL responses: no layer caches them. APQ (apq_cache_responses=True) can store responses of persisted queries; see Persisted Queries.
  • Mutations: nothing invalidates on its own when a mutation runs.

4. CASCADE Rules

SchemaAnalyzer(schema).analyze_relationships() returns a CascadeRule per object field that references another object type: for Post.author: User, the rule user → post ("when a user changes, posts are stale"). Type names become snake_case domains; self-references and Query / Mutation / Subscription are skipped; a list field gets confidence=0.9, others 1.0.

from fraiseql.caching import SchemaAnalyzer, setup_auto_cascade_rules

rules = SchemaAnalyzer(schema).analyze_relationships()  # [CascadeRule('user', 'post', ...)]
await setup_auto_cascade_rules(postgres_cache, schema)

setup_auto_cascade_rules(cache, schema, verbose=False) passes each rule to PostgresCache.register_cascade_rule, which stores it in the fraiseql_cache.cascade_rules table of the pg_fraiseql_cache PostgreSQL extension (a separate project; see PostgreSQL Extensions). Without the extension, register_cascade_rule logs a warning, does nothing and returns False, and setup_auto_cascade_rules returns 0 (it counts the rules registered).

PostgresCache detects the extension (has_domain_versioning, extension_version) on its first operation, whichever it is (register_cascade_rule, setup_table_trigger and ping() included), or on initialize().

Even with the extension, ResultCache, cached_query and CachedRepository don't check domain versions: the rules invalidate none of their entries. Only the RBAC permission cache (fraiseql.enterprise.rbac) reads them. For query results, rely on TTLs and on invalidate / invalidate_pattern where you write.


5. Configuration

There is no cache setting in FraiseQLConfig and no FRAISEQL_CACHE_* variable for this cache. (FraiseQLConfig.cache_ttl, read from FRAISEQL_CACHE_TTL, is deprecated and has no effect.) Read your own settings and pass them in:

import os

from fraiseql.caching import CacheConfig, PostgresCache, ResultCache

cache = ResultCache(
    backend=PostgresCache(connection_pool=pool),
    config=CacheConfig(
        enabled=os.environ.get("APP_CACHE_ENABLED", "true") == "true",
        default_ttl=int(os.environ.get("APP_CACHE_TTL", "300")),
        max_ttl=int(os.environ.get("APP_CACHE_MAX_TTL", "3600")),
    ),
)

5.1 TTL Guidelines

Data Changes TTL
Reference data (countries, currencies) Rarely up to max_ttl
Catalogs, profiles Hours 600-1800 s
Aggregates, rankings Minutes 60-300 s
Real-time data Seconds don't cache, or 5-30 s

Raise max_ttl for data that may live longer than an hour: it caps every TTL.


6. Troubleshooting

Nothing is cached (stats.misses grows, stats.errors too): the values aren't JSON-serializable (look for Cache set error warnings). Cache JSON data (dicts, lists, strings, numbers); CachedRepository stores find's RustResponseBytes as JSON text for you.

Low hit rate: keys differ between calls that should share one (argument order doesn't matter for keyword arguments, but values do: normalize them), or the TTL is short.

Stale data after a write: nothing invalidates automatically; call invalidate_pattern with a pattern that matches the keys you built.

Table growing: cleanup_expired() isn't running, or keys have unbounded cardinality (one per user input).


7. Security

  • Tenant isolation depends on the keys: put the tenant id (from the authenticated context, never from a client argument) in every key of tenant data. CacheKeyBuilder.build_key(tenant_id=...) puts it second.
  • Sensitive data: entries are plain JSONB in a table every role with access to it can read. Don't cache what that role shouldn't see.

Glossary

Term Definition
Cache Hit get_or_set found a stored, unexpired value
Cache Miss No value (or None): the function ran
TTL Seconds an entry stays valid (expires_at)
Invalidation Deleting entries by key or * pattern
CascadeRule A source_domain → target_domain relationship derived from the schema, used by the pg_fraiseql_cache extension
UNLOGGED Table A PostgreSQL table without write-ahead logging: faster writes, emptied after a crash