feat: PostgreSQL-backed cross-replica Data Cache handler (P2)

[Zheaoli]

Summary

Delivers instant cross-replica consistency for the public Data Cache — the core of multi-replica readiness. PicImpact memoises its public read path with unstable_cache + revalidateTag (server/lib/cache.ts), but Next's default cache handler keeps that data per-instance, so a revalidateTag on the replica handling an admin write doesn't reach the others; they serve stale data until the safety-net TTL expires. This routes the Data Cache through Postgres so an invalidation on one replica is seen by all.

No application-layer changes: server/lib/cache.ts is untouched — wiring a custom cacheHandler is enough for the existing unstable_cache calls to flow through it.

How it works

• server/lib/pg-cache-handler.cjs — a custom Next cacheHandler:
  • L2 = Postgres (next_cache_entries + next_cache_tags, auto-created), shared by all replicas; L1 = a bounded, module-level in-memory cache for hot reads (the handler is instantiated per request, so shared state lives at module scope).
  • Cross-instance invalidation = get() returns a miss when any of an entry's tags was invalidated after the entry was written. Next's own in-process tag manifest can't be fed from another replica, but it only runs when get() returns data — so get() is made the decision point, consulting the shared manifest.
  • Postgres-authoritative manifest: refreshed on a short TTL (so a missed NOTIFY, or a transaction-pooled connection that can't LISTEN, still converges within ~1s) and busted instantly via LISTEN/NOTIFY when a direct connection is available (uses DIRECT_URL for the listener, since LISTEN needs a persistent session).
  • Clock-skew safe: both an entry's write time and a tag's invalidation time are stamped by the Postgres server clock, so the "written before invalidated?" comparison can't be fooled by skew between replicas.
  • Instant consistency: a revalidateTag forces a recompute on the next read on every replica. Cross-instance stale-while-revalidate is intentionally not implemented (it would let a replica serve one stale read after an admin change); per-entry safety-net TTLs (revalidate seconds) are still honored by Next.
• next.config.mjs — wires the handler and sets cacheMaxMemorySize: 0 so Next's per-instance memory cache doesn't mask it.
• server/lib/cache-cleanup.ts — a long-unused-entry sweep, driven by the same single external cron as the preprocess tick (/api/v1/preprocess-tasks/tick), so it never runs as a per-replica timer.
• Adds pg + @types/pg (pg was already declared in serverExternalPackages).
• Documents the shared cache, DIRECT_URL usage, and CACHE_HANDLER_DEBUG in docs/multi-replica.md and .env.example.

Notes

• Instant model trade-off: after an invalidation, each replica recomputes independently on its next read. For PicImpact's deterministic DB-query cache functions every replica recomputes the same current-DB value, so there's no divergence — just a little redundant work on a hot key right after a write (negligible at this scale; a per-key single-flight could be added later if any key gets hot and expensive).
• Only unstable_cache (FETCH-kind) entries currently flow through the handler; PicImpact's routes are all dynamic (no ISR) and image optimization keeps its own cache. The handler stores any kind generically and never throws into the request path.

Test plan

• tsc --noEmit clean for the changed files; next build passes with the handler wired.
• 2-instance build against Postgres (next start x2, one database):
  • read on instance A then B returns the same cached value (shared L2);
  • revalidateTag on A → next read on B recomputes (cross-replica invalidation);
  • kill B, revalidateTag on A (B misses the NOTIFY), restart B → B recomputes (cold-start reload makes Postgres authoritative);
  • repeated reads without a write stay stable (no over-invalidation).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
picimpact	Ready	Preview, Comment	Jun 22, 2026 3:06pm