fix: invalidate stale predicate-scoped cache entries on manual-sync writes #1497
main fromrefs/pull/1497/head·opened Manual-sync writes in on-demand Query Collections now preserve predicate-, order-, and pagination-scoped Query cache results. Active queries revalidate from their source, while inactive or disabled entries are removed so later subscriptions fetch fresh data.
Root cause#
Each on-demand Query cache entry belongs to one queryFn result and may encode a distinct where, orderBy, limit, or offset. Manual writes replaced every entry under the collection's base key with the full normalized collection snapshot. That changed the shape and membership of scoped cache entries.
An inactive poisoned entry could later be treated as a valid cache hit. Its rows would be reconciled through the wrong query ownership scope, which surfaced in production as “not found” results for rows that still existed in Postgres. Active limited or ordered queries had the same flaw: patching them from the normalized snapshot could widen the cache or fail to replenish a deleted row.
Approach#
- Keep eager behavior unchanged: eager collections patch their full-result cache in place.
- Never write the full normalized snapshot into on-demand cache entries.
- Refetch active, fetchable observers directly. This also revalidates queries with
staleTime: 'static'. - Remove inactive and disabled entries in one cache operation so their next subscription runs
queryFn. - Ignore success notifications that still carry the exact pre-write
dataUpdateCount, then accept the next authoritative result. - Clear the notification marker on observer cleanup and Query reset or recreation paths.
- Wait for an optimistic transaction's deferred-refresh barrier before refetching, and revalidate after either barrier outcome.
Key invariants#
- An on-demand Query cache entry only contains data shaped by its own
queryFn. - A direct write remains visible in the synced store immediately.
- Fetch and invalidation notifications cannot replace that write with unchanged cached data.
- A later authoritative result always reconciles the collection, including after Query state resets.
Non-goals and trade-offs#
This does not change eager cache updates or the direct-write API. Active on-demand queries now incur a network refetch after a manual write; that cost is required because a normalized collection snapshot cannot reconstruct ordered, limited, paginated, or predicate-scoped results.
Verification#
pnpm exec vitest run --config packages/query-db-collection/vitest.config.ts packages/query-db-collection/tests/query.test.ts --maxWorkers=2
pnpm exec tsc --noEmit -p packages/query-db-collection/tsconfig.json
pnpm --filter @tanstack/query-db-collection build
pnpm exec eslint packages/query-db-collection/src/query.ts packages/query-db-collection/tests/query.test.ts
pnpm test:docs
The package suite passes all 146 tests. New regressions cover inactive cache hits, overlapping scopes, active limited and static queries, disabled entries, in-flight initial loads, Query resets, and rejected deferred-refresh barriers.
Files changed#
packages/query-db-collection/src/query.ts: revalidate or remove on-demand cache entries and guard stale notifications.packages/query-db-collection/tests/query.test.ts: add red/green coverage for scoped-cache and lifecycle cases.docs/collections/query-collection.md: document eager and on-demand direct-write behavior.docs/reference/query-db-collection/interfaces/QueryCollectionUtils.md: update generated API reference text..changeset/fix-cache-poisoning-on-manual-writes.md: add the patch release note.
Release impact#
- This change affects published code and includes a changeset.
Summary by CodeRabbit#
Bug Fixes
- Fixed manual writes in on-demand collections so they no longer overwrite filtered, sorted, or paginated cache results with a full snapshot.
- Active queries now refresh with current data, while inactive or disabled entries are removed.
- Prevented stale or incorrect results after direct inserts, updates, and deletes.
Documentation
- Clarified cache behavior for direct writes across eager and on-demand collections.
- Added guidance for scoped queries, persistence handlers, and deferred refreshes.
- 1
any news on this? we hit the same bug :( — for now we are avoiding the
write*utils entirely on on-demand collections and reconciling withrefetch()instead, so it would be great to see this land📝 Walkthrough
Walkthrough#
Direct writes now patch eager caches but revalidate active scoped on-demand queries and remove inactive or disabled entries. Query observer tracking prevents duplicate reconciliation, while tests cover query-key variants, predicates, pagination, deferred refreshes, and preload behavior.
Changes#
Manual-write cache invalidation
Layer / File(s) Summary Cache behavior contracts
.changeset/...,docs/collections/query-collection.md,docs/reference/query-db-collection/interfaces/QueryCollectionUtils.md,packages/query-db-collection/src/query.tsDocumentation and release notes describe sync-mode-specific direct-write behavior and scoped on-demand revalidation. Scoped cache update flow
packages/query-db-collection/src/query.tsOn-demand writes refetch active observers, remove non-refetching entries, and track observer update counts; eager writes retain full-cache updates. Invalidation behavior validation
packages/query-db-collection/tests/query.test.tsTests cover refetching, predicate-scoped cache behavior, disabled entries, limited queries, deferred refreshes, and in-flight preloads. Estimated code review effort: 4 (Complex) | ~45 minutes
Sequence Diagram(s)#
sequenceDiagram participant DirectWrite participant updateCacheData participant QueryObserver participant queryFn DirectWrite->>updateCacheData: update cache after synced-store write updateCacheData->>QueryObserver: refetch active scoped observers QueryObserver->>queryFn: request scoped results queryFn-->>QueryObserver: return refreshed dataPossibly related PRs
- TanStack/db#1655: Adds related tests for refetch and cache invalidation behavior in
query.test.ts.
Suggested reviewers:
kyleamathews,kevin-dp🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request. Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request. Title check ✅ Passed The title is concise and directly matches the main fix: preventing stale predicate-scoped cache entries from manual-sync writes. Description check ✅ Passed The description covers the change, rationale, verification, files changed, and release impact, even though it doesn't follow the template headings exactly. ✨ Finishing Touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment `@coderabbitai help` to get the list of available commands.- TanStack/db#1655: Adds related tests for refetch and cache invalidation behavior in
@marbemac @andyfelder16 could you test this against my latest pushes? I merged in origin/main & did a few fixes
🧹 Nitpick comments (1)
packages/query-db-collection/tests/query.test.ts (1)
8676-8677: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueClarify the double
setQueryDatawith an identity updater.Two back-to-back identity
setQueryDatacalls are non-obvious; they appear intended to advancedataUpdateCountso the laterresetQueriesexercises the stale-count path. A one-line comment explaining why the count is bumped twice would help future readers.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/query-db-collection/tests/query.test.ts` around lines 8676 - 8677, Add a concise comment immediately before the duplicate customQueryClient.setQueryData calls explaining that the identity updates intentionally increment dataUpdateCount twice so the subsequent resetQueries test covers the stale-count path; leave both calls unchanged.🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Nitpick comments: In `@packages/query-db-collection/tests/query.test.ts`: - Around line 8676-8677: Add a concise comment immediately before the duplicate customQueryClient.setQueryData calls explaining that the identity updates intentionally increment dataUpdateCount twice so the subsequent resetQueries test covers the stale-count path; leave both calls unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
abffe3a9-0247-453a-9e5c-a6a3fe9b8dcc📥 Commits
Reviewing files that changed from the base of the PR and between f42db5cacbb559b8cf31e6cc376c13044a45ff58 and f55784a0b0954fa73a33e2cbcfcc820ba1e2f823.
📒 Files selected for processing (5)
.changeset/fix-cache-poisoning-on-manual-writes.mddocs/collections/query-collection.mddocs/reference/query-db-collection/interfaces/QueryCollectionUtils.mdpackages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts
Superseded by #1826, which rebases the work onto current main and includes the additional cache-ownership and lifecycle fixes found through oracle testing and review.
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit:
f55784a