fix(query-db): clean up empty ownership sets #1672
main fromrefs/pull/1672/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Summary#
Cleans up Query DB ownership bookkeeping so empty row/query ownership sets are not retained, while preserving the semantic distinction between an unresolved query and a resolved query with an empty result.
This keeps ownership state bounded across subset unloads, cache expiry, persisted-row hydration, and empty revalidation without deleting rows that are still shared by another query.
Design#
Root cause#
rowToQueries and queryToRows used empty Sets both as stale bookkeeping and as a marker that a query's ownership had been resolved. Removing those empty entries directly would lose the resolved-empty baseline and could cause hydration or revalidation to infer ownership again incorrectly.
Approach#
- Delete reverse and forward ownership-map entries as soon as their sets become empty.
- Track authoritative query ownership separately in
resolvedOwnershipQueries, including valid empty results. - Clear that marker when retained ownership expires or the query/collection is cleaned up.
- Add test-only ownership inspection and lifecycle coverage for overlapping subsets, cache GC, persisted hydration, empty revalidation, and retained ownership expiry.
Invariants#
- Ownership maps contain only non-empty sets.
- A row is removed only after its final query owner is removed.
- A resolved empty result remains authoritative until its query lifecycle ends.
- Persisted retention markers and in-memory ownership markers expire together.
Non-goals and tradeoffs#
- No public API or persistence-format changes.
- The separate resolved-query set adds a small amount of state, but avoids overloading empty map entries and is explicitly bounded by existing cleanup paths.
- Internal ownership-map inspection is exposed only in test environments.
Verification#
pnpm --filter @tanstack/query-db-collection test -- query.test.ts- 232 tests passed and type assertions reported no errors in the target suite.
- Command exits non-zero because Vitest also type-checks
db-collection-e2esources that cannot resolve@tanstack/electric-db-collectionin this worktree (3 unrelated source errors).
Files#
packages/query-db-collection/src/query.ts— compact ownership maps and preserve resolved-empty semantics with bounded lifecycle tracking.packages/query-db-collection/tests/query.test.ts— characterize and verify ownership cleanup, hydration, shared rows, cache expiry, and retained-query cleanup.
Summary by CodeRabbit#
Bug Fixes
- Improved cleanup and synchronization of query↔row ownership when data is unloaded, expires, revalidates, or hydrates from persisted metadata.
- Empty query results now establish an authoritative ownership baseline without incorrectly deleting shared/retained rows.
- Retained-row ownership is cleared reliably after retention ends and when an explicit collection cleanup runs.
Tests
- Added deeper lifecycle coverage for ownership mapping across overlapping subsets, cache expiry, persisted hydration, empty-result revalidation, and retention cleanup.
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1672@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1672@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1672@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1672@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1672@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1672@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1672@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1672@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1672@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1672@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1672@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1672@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1672@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1672@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1672@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1672@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1672@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1672@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1672@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1672@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1672@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1672commit:
b9a204fSize Change: 0 B
Total Size: 125 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.43 kB packages/db/dist/esm/collection/changes.js1.38 kB packages/db/dist/esm/collection/cleanup-queue.js810 B packages/db/dist/esm/collection/events.js434 B packages/db/dist/esm/collection/index.js3.62 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.69 kB packages/db/dist/esm/collection/mutations.js2.47 kB packages/db/dist/esm/collection/state.js5.48 kB packages/db/dist/esm/collection/subscription.js3.74 kB packages/db/dist/esm/collection/sync.js2.88 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.1 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/index.js3.16 kB packages/db/dist/esm/indexes/auto-index.js829 B packages/db/dist/esm/indexes/base-index.js767 B packages/db/dist/esm/indexes/basic-index.js2.06 kB packages/db/dist/esm/indexes/btree-index.js2.19 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js557 B packages/db/dist/esm/live-query-adapter.js318 B packages/db/dist/esm/local-only.js916 B packages/db/dist/esm/local-storage.js2.12 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js496 B packages/db/dist/esm/proxy.js3.75 kB packages/db/dist/esm/query/builder/functions.js1.47 kB packages/db/dist/esm/query/builder/index.js5.84 kB packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB packages/db/dist/esm/query/compiler/evaluators.js1.89 kB packages/db/dist/esm/query/compiler/expressions.js430 B packages/db/dist/esm/query/compiler/group-by.js3.56 kB packages/db/dist/esm/query/compiler/index.js6.67 kB packages/db/dist/esm/query/compiler/joins.js2.5 kB packages/db/dist/esm/query/compiler/lazy-targets.js923 B packages/db/dist/esm/query/compiler/order-by.js1.74 kB packages/db/dist/esm/query/compiler/select.js1.53 kB packages/db/dist/esm/query/effect.js4.77 kB packages/db/dist/esm/query/expression-helpers.js1.43 kB packages/db/dist/esm/query/ir.js1.25 kB packages/db/dist/esm/query/live-query-collection.js360 B packages/db/dist/esm/query/live/collection-config-builder.js9.1 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js1.93 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/utils.js1.81 kB packages/db/dist/esm/query/optimizer.js2.92 kB packages/db/dist/esm/query/predicate-utils.js2.97 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/subset-dedupe.js960 B packages/db/dist/esm/scheduler.js1.3 kB packages/db/dist/esm/SortedMap.js1.3 kB packages/db/dist/esm/strategies/debounceStrategy.js247 B packages/db/dist/esm/strategies/queueStrategy.js428 B packages/db/dist/esm/strategies/throttleStrategy.js246 B packages/db/dist/esm/transactions.js3.04 kB packages/db/dist/esm/utils.js927 B packages/db/dist/esm/utils/array-utils.js273 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js5.61 kB packages/db/dist/esm/utils/comparison.js1.11 kB packages/db/dist/esm/utils/cursor.js457 B packages/db/dist/esm/utils/index-optimization.js2.39 kB packages/db/dist/esm/utils/type-guards.js157 B packages/db/dist/esm/utils/uuid.js449 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 4.22 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/index.js249 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.32 kB packages/react-db/dist/esm/useLiveQuery.js1.33 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B Actionable comments posted: 1
🤖 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. Inline comments: In `@packages/query-db-collection/src/query.ts`: - Line 1656: Update collection cleanup to build its key set from state.observers, queryToRows, and resolvedOwnershipQueries so retained ownership queries are removed before TTL expiry or revalidation; preserve deletion of queryToRows, rowToQueries, and resolvedOwnershipQueries for every collected key. Add a regression test covering collection.cleanup() while a retained placeholder is pending, asserting all three structures are empty.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
225651f4-0c6e-4d6d-b6cc-a51d4b9b8966📥 Commits
Reviewing files that changed from the base of the PR and between 09d7d677b43b0c5f33f13f0c05bfbb4afa88905b and 29eefca1e9d84b3e2f1623488ef0fa939caf0a6c.
📒 Files selected for processing (4)
.changeset/clean-query-ownership.md.superpowers/sdd/task-2-report.mdpackages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts
packages/query-db-collection/src/query.ts line 1656Outdated@@ -1636,3 +1653,4 @@1636165316371654 state.observers.delete(hashedQueryKey)16381655 queryToRows.delete(hashedQueryKey)1656+ resolvedOwnershipQueries.delete(hashedQueryKey)🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Include retained ownership keys in explicit collection cleanup.
Line 1656 is never reached for retained queries removed from
state.observersat Line 1726. Sincecleanup()only iterates observer keys, cleanup before TTL expiry/revalidation leavesqueryToRows,rowToQueries, andresolvedOwnershipQueriesretained.Build the cleanup key set from
state.observers,queryToRows, andresolvedOwnershipQueries. Add a regression test that callscollection.cleanup()while a retained placeholder is still pending and asserts all three structures are empty.As per coding guidelines, “Always add unit tests that reproduce a bug before fixing it to ensure the bug is fixed and prevent regression.”
🤖 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/src/query.ts` at line 1656, Update collection cleanup to build its key set from state.observers, queryToRows, and resolvedOwnershipQueries so retained ownership queries are removed before TTL expiry or revalidation; preserve deletion of queryToRows, rowToQueries, and resolvedOwnershipQueries for every collected key. Add a regression test covering collection.cleanup() while a retained placeholder is pending, asserting all three structures are empty.Source: Coding guidelines
kevin-dp(GitHub profile, opens in a new tab) requested changes
The lifecycle fix (deleting stale entries at the right points) looks right to me. I'd like to suggest a simplification before this lands, though: I don't think we need
resolvedOwnershipQueriesas a separate structure.The marker is only ever consulted as
knownRows || resolvedOwnershipQueries.has(k), i.e. a non-emptyqueryToRowsentry already counts as authoritative on its own. The new set only carries information when the row set is empty — which means we can encode "resolved" as entry presence inqueryToRowsitself, with an emptySetallowed:- present entry (possibly empty) = ownership resolved
- absent entry = unresolved
Concretely:
- At the resolution point, replace
resolvedOwnershipQueries.add(k)withqueryToRows.set(k, queryToRows.get(k) ?? new Set()). - In
removeRowOwner, keep the drainedqueryToRowsentry instead of deleting it — a query whose rows are diffed away during revalidation is still resolved and now legitimately owns nothing. (The delete-when-empty stays correct forrowToQueries, since a row with no owners has no "resolved" meaning.) - The two teardown paths (
cleanupPersistedPlaceholderand query cleanup) then just delete the one entry instead of clearing two structures.
The read side reverts to the simpler pre-PR shape (
if (knownRows)), and the compound(knownRows || resolvedOwnershipQueries.has(k)) && Array.from(knownRows ?? [])check goes away. More importantly, there's one source of truth: right now three separate mutation sites have to keepresolvedOwnershipQueriesin sync with the map's lifecycle, and a missed site in a future change becomes a silent drift bug.The trade-off is that the invariant becomes implicit — an accidental get-or-create on
queryToRows(like the existingaddRowOwnerpattern) would silently mark an unresolved query as resolved-empty. I think that's addressable by funneling writes through a couple of small helpers, documenting the presence-means-resolved invariant on the map declaration, and asserting it via the test-only inspection hook this PR already adds.Memory-wise it's equivalent, so this is purely about keeping the bookkeeping in one place. WDYT?
Actionable comments posted: 1
🤖 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. Inline comments: In `@packages/query-db-collection/src/query.ts`: - Around line 740-741: Update cleanup() to build its query-key set from both state.observers.keys() and queryToRows keys, then use that combined set when removing ownership data so retained queries are fully cleared from queryToRows and rowToQueries during explicit collection cleanup.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
4a3e7916-3963-40c6-9263-cbd68dc9b5ae📥 Commits
Reviewing files that changed from the base of the PR and between 29eefca1e9d84b3e2f1623488ef0fa939caf0a6c and d2d5f8efdfc74482a5e6ee344bba5c857180f8a2.
📒 Files selected for processing (2)
packages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/query-db-collection/tests/query.test.ts
@@ -737,4 +737,5 @@737737 // hashedQueryKey → queryKey738738 const hashToQueryKey = new Map<string, QueryKey>()739739740- // queryKey → Set<RowKey>740+ // queryKey → Set<RowKey>. Entry presence means ownership is resolved;741+ // an empty set represents a resolved query that currently owns no rows.🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Include retained ownership keys in explicit collection cleanup.
As flagged in a previous review,
queryToRowsretains ownership keys for queries removed fromstate.observersduring retention. Thecleanup()method still only iteratesstate.observers.keys(), leavingqueryToRowsandrowToQueriespopulated for retained queries when an explicit collection cleanup occurs.Build the cleanup key set by combining
state.observersandqueryToRowsto ensure retained queries are properly cleaned up.🤖 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/src/query.ts` around lines 740 - 741, Update cleanup() to build its query-key set from both state.observers.keys() and queryToRows keys, then use that combined set when removing ownership data so retained queries are fully cleared from queryToRows and rowToQueries during explicit collection cleanup.✅ Addressed in commit b9a204f
kevin-dp(GitHub profile, opens in a new tab) approved these changes
🧹 Nitpick comments (1)
packages/query-db-collection/tests/query.test.ts (1)
5974-5977: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueSpread
originalSyncto preserve allSyncPluginproperties.When intercepting the
syncmethod of theoriginalSyncplugin, it's safer to spread the rest of theoriginalSyncproperties into the new object. Although core lifecycle methods likecleanupandloadSubsetmay be returned dynamically in theSyncResult, spreading the plugin object ensures any top-level properties (likeidor future plugin hooks) are not inadvertently lost.♻️ Proposed refactor
sync: { + ...originalSync, sync: (params: Parameters<typeof originalSync.sync>[0]) => originalSync.sync({ ...params, metadata: metadataHarness.api }), },🤖 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 5974 - 5977, Update the intercepted originalSync plugin object to spread all properties from originalSync before overriding its sync method, preserving top-level SyncPlugin fields such as id and future hooks while retaining the metadata injection behavior.🤖 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 5974-5977: Update the intercepted originalSync plugin object to spread all properties from originalSync before overriding its sync method, preserving top-level SyncPlugin fields such as id and future hooks while retaining the metadata injection behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
3b61115a-4091-4b21-9a11-d4033311eb60📥 Commits
Reviewing files that changed from the base of the PR and between d2d5f8efdfc74482a5e6ee344bba5c857180f8a2 and b9a204fba733b72c8eceb3493b1c3e77dc564279.
📒 Files selected for processing (2)
packages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/query-db-collection/src/query.ts
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
📝 Walkthrough
Walkthrough#
Query ownership bookkeeping now preserves authoritative empty results, removes empty ownership relationships, clears persisted markers, and validates unloading, expiry, revalidation, retention, and collection cleanup.
Changes#
Query ownership lifecycle
packages/query-db-collection/src/query.tspackages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts,.changeset/clean-query-ownership.mdEstimated code review effort: 3 (Moderate) | ~20 minutes
Possibly related issues
query.ts, including ownership refresh and cleanup behavior.Possibly related PRs
query.tsownership helper semantics and query lifecycle cleanup.Suggested reviewers:
kevin-dp🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ Finishing Touches
📝 Generate docstrings
🧪 Generate unit tests (beta)
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.
❤️ Share