Skip to content

Server-Side Cache Invalidation

Note: This document describes server-side cache invalidation, not the GraphQL Cascade client-side update feature.

FraiseQL's result cache (fraiseql.caching, see the Caching Specification) expires entries by TTL and deletes them when you call invalidate / invalidate_pattern. It can also derive CASCADE rules from your GraphQL schema ("when a User changes, cached Posts are stale") and register them with the pg_fraiseql_cache PostgreSQL extension. This page covers both, and what each one invalidates.


What Invalidates What

Mechanism Invalidates
TTL (CacheConfig.default_ttl, ttl=) Every entry, when it expires
cache.invalidate(key) / cache.invalidate_pattern("prefix:*") The entries you name, when you call it
CASCADE rules (setup_auto_cascade_rules) Nothing in ResultCache: they are stored in the pg_fraiseql_cache extension, whose domain versions only the RBAC permission cache (fraiseql.enterprise.rbac) checks

So for cached query results: pick TTLs that match how stale the data may be, and invalidate explicitly where your code writes.


Invalidating After a Write

Key your entries so one pattern covers what a write makes stale, and invalidate that pattern after the write:

from contextlib import asynccontextmanager

import fraiseql
from fraiseql.caching import CacheConfig, PostgresCache, ResultCache
from fraiseql.fastapi import create_fraiseql_app
from fraiseql.fastapi.dependencies import get_db_pool

cache: ResultCache | None = None


@fraiseql.type(sql_source="v_user")
class User:
    id: int
    name: str


async def user_names(tenant_id: str) -> list[str]:
    async def load() -> list[str]:
        async with get_db_pool().connection() as conn:
            cur = await conn.execute("SELECT data->>'name' FROM v_user ORDER BY id")
            return [row[0] for row in await cur.fetchall()]

    return await cache.get_or_set(f"fraiseql:{tenant_id}:user:names", load, ttl=300)


@fraiseql.query
async def names(info) -> list[str]:
    return await user_names(str(info.context.get("tenant_id", "public")))


@fraiseql.mutation
async def rename_user(info, id: int, name: str) -> bool:
    db = info.context["db"]
    await db.execute_function("fn_rename_user", {"id": id, "name": name})
    tenant_id = str(info.context.get("tenant_id", "public"))
    await cache.invalidate_pattern(f"fraiseql:{tenant_id}:user:*")
    return True


@asynccontextmanager
async def lifespan(app):
    global cache
    cache = ResultCache(backend=PostgresCache(connection_pool=get_db_pool()), config=CacheConfig())
    yield


app = create_fraiseql_app(
    database_url="postgresql://localhost/mydb",
    types=[User],
    queries=[names],
    mutations=[rename_user],
    lifespan=lifespan,  # runs once fraiseql has opened the pool
)

Writes that don't go through your code (another service, a migration, psql) invalidate nothing: their entries stay until they expire.


CASCADE Rules

Relationship Detection

SchemaAnalyzer walks the schema's object types and makes one rule per field that references another object type, from the referenced type to the referencing one:

type User {
  id: ID!
  name: String!
}

type Post {
  id: ID!
  author: User!        # rule: user → post
  comments: [Comment!]!  # rule: comment → post (confidence 0.9, a list)
}

type Comment {
  id: ID!
  author: User!        # rule: user → comment
}

Type names become snake_case domains (BlogPost → blog_post). Self-references (parent: User on User), Query, Mutation, Subscription and introspection types are skipped. A field that only holds an id (author_id: ID!) isn't a relationship.

from fraiseql.caching import SchemaAnalyzer

analyzer = SchemaAnalyzer(app.state.graphql_schema)
for rule in analyzer.analyze_relationships():
    print(rule)                         # user → post
print(analyzer.get_domain_dependencies())  # {'post': {'user', 'comment'}, 'comment': {'user'}}

SchemaAnalyzer(schema, type_to_domain_fn=..., exclude_types=...) takes your own type-to-domain mapping and types to leave out (the default excludes the root and introspection types; a set you pass replaces it).

Registering Rules at Startup

from contextlib import asynccontextmanager

from fraiseql.caching import PostgresCache, setup_auto_cascade_rules
from fraiseql.fastapi import create_fraiseql_app
from fraiseql.fastapi.dependencies import get_db_pool


@asynccontextmanager
async def lifespan(app):
    backend = PostgresCache(connection_pool=get_db_pool())
    await backend.get_stats()  # first use: creates the cache table, detects the extension
    count = await setup_auto_cascade_rules(backend, app.state.graphql_schema, verbose=True)
    yield


app = create_fraiseql_app(
    database_url="postgresql://localhost/mydb",
    types=[User, Post, Comment],
    queries=[posts],
    lifespan=lifespan,
)

verbose=True logs the rules and the dependency graph on the fraiseql.caching.schema_analyzer logger at INFO. Each rule goes to PostgresCache.register_cascade_rule(source_domain, target_domain, rule_type="invalidate"), which inserts it into the extension's fraiseql_cache.cascade_rules table. Call it yourself for a rule the schema doesn't show:

await backend.register_cascade_rule("user", "feed")
await backend.setup_table_trigger("tb_user", domain_name="user")  # the extension's trigger
await backend.clear_cascade_rules("user")

The backend detects the extension on its first use (a get, set or get_stats), not when it's created: before that, and without the pg_fraiseql_cache extension (backend.has_domain_versioning is False), these methods log a warning and do nothing, and setup_auto_cascade_rules still returns the number of rules it tried. The extension is a separate project: see PostgreSQL Extensions.


Troubleshooting

Stale data after a mutation: the write didn't invalidate a pattern matching the entries' keys. Print the keys (SELECT cache_key FROM fraiseql_cache) and the pattern; * becomes SQL LIKE's %, and _ matches any one character.

"CASCADE rules require pg_fraiseql_cache extension" warnings: the extension isn't installed in this database; the rules weren't registered.

Too much invalidated: the pattern is too broad (fraiseql:* clears every entry); put the tenant and the domain in the key so the pattern can name them.


See Also


Last Updated: 2026-10-25 FraiseQL Version: 1.31.0