fix(db-sqlite-persistence-core): persisted preload() hangs when upstream sync never calls markReady #1615
main fromrefs/pull/1615/head·opened 🎯 Changes#
collection.preload() and toArrayWhenReady() hung forever when the upstream sync never called markReady(). This happens in when TanStack Query's networkMode: 'offlineFirst' pauses a query because the device is offline, paused queries never reach isSuccess or isError, so markReady() is never called, and consumers block indefinitely even though SQLite has local data available.
Fix#
After ensureStarted() resolves (SQLite hydration complete), params.markReady() is now called directly in createWrappedSyncConfig, independent of the upstream sync. This is skipped in on-demand mode because no rows load at startup there, the upstream sync owns readiness in that case. If the upstream sync also calls markReady(), the second call is safely ignored by the lifecycle layer.
✅ Checklist#
- I have tested this code locally with
pnpm test.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
Bug Fixes
- Fixed a case where
preload()could hang if upstream synchronization never signaled readiness. - Improved persisted sync readiness so loading completes on success or startup failure, while preventing late readiness signals after cleanup (including correct behavior for
on-demandmode).
- Fixed a case where
Tests
- Added regression coverage for
preload()resolving without upstream readiness, plus additional readiness/cleanup race-condition tests to ensure readiness is signaled correctly and only once.
- Added regression coverage for
- 1
PHILLIPS71(GitHub profile, opens in a new tab) changed the title
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/db-sqlite-persistence-core/src/persisted.ts`: - Around line 2563-2570: The loopback startup flow in ensureStarted() still calls params.markReady() unconditionally in the finally block, which can race with cleanup() and re-mark a cleaned-up collection ready. Update the persisted loopback path to mirror the guarded wrapped path by checking startupState.cleanedUp before calling params.markReady(). Keep the fix localized around the runtime.ensureStarted().catch(...).finally(...) chain in persisted.ts so the lifecycle transition stays valid even when startup finishes late.🪄 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:
b90cf813-03a8-4896-9265-35c0a866016b📥 Commits
Reviewing files that changed from the base of the PR and between 45617c45b761ee32d6cacc1a4ee9e653a27680dd and e17122d13b216dc9384e88f6e3b3203e4c8f61e1.
📒 Files selected for processing (3)
.changeset/free-rivers-like.mdpackages/db-sqlite-persistence-core/src/persisted.tspackages/db-sqlite-persistence-core/tests/persisted.test.ts
@@ -2542,10 +2562,9 @@2542256225432563 void runtime25442564 .ensureStarted()2545- .then(() => {2546- params.markReady()2547- })25482565 .catch((error) => {25492566 console.warn(`Failed persisted loopback startup:`, error)2567+ })2568+ .finally(() => {25502569 params.markReady()25512570 })🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Guard loopback
markReady()after cleanup.Line 2568 always calls
params.markReady()even ifcleanup()already ran. The wrapped path added astartupState.cleanedUpcheck for this exact race; loopback needs the same guard or a slowensureStarted()can mark a cleaned-up collection ready again (or trip lifecycle transition validation).Suggested fix
return { sync: (params) => { + const startupState = { cleanedUp: false } runtime.setSyncControls({ begin: params.begin, write: params.write as SyncControlFns<T, TKey>[`write`], commit: params.commit, truncate: params.truncate, @@ void runtime .ensureStarted() .catch((error) => { console.warn(`Failed persisted loopback startup:`, error) }) .finally(() => { - params.markReady() + if (!startupState.cleanedUp) { + params.markReady() + } }) return { cleanup: () => { + startupState.cleanedUp = true runtime.cleanup() runtime.clearSyncControls() },📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
const startupState = { cleanedUp: false } void runtime .ensureStarted() .catch((error) => { console.warn(`Failed persisted loopback startup:`, error) }) .finally(() => { if (!startupState.cleanedUp) { params.markReady() } }) return { cleanup: () => { startupState.cleanedUp = true runtime.cleanup() runtime.clearSyncControls() },🤖 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/db-sqlite-persistence-core/src/persisted.ts` around lines 2563 - 2570, The loopback startup flow in ensureStarted() still calls params.markReady() unconditionally in the finally block, which can race with cleanup() and re-mark a cleaned-up collection ready. Update the persisted loopback path to mirror the guarded wrapped path by checking startupState.cleanedUp before calling params.markReady(). Keep the fix localized around the runtime.ensureStarted().catch(...).finally(...) chain in persisted.ts so the lifecycle transition stays valid even when startup finishes late.✅ Addressed in commit 6bb2bfd
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1615@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1615@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1615@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1615@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1615@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1615@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1615@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1615@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1615@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1615@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1615@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1615@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1615@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1615@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1615@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1615@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1615@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1615@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1615@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1615@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1615@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1615commit:
4486d4bClosing unmerged as superseded by #1955 and its #1960 follow-up. This PR would call markReady() after local hydration, which changes Collection readiness for every persisted collection. The chosen contract instead keeps Collection readiness upstream-gated, exposes separate persisted readiness across framework integrations, and lets applications opt into network-first initial rendering with a persisted fallback. Thank you for identifying the offline-rendering gap and contributing the proposed fix; the replacement addresses that use case without adopting this PR's readiness behavior.
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
f81acf01-897f-4f54-990e-67a190cbfbca📥 Commits
Reviewing files that changed from the base of the PR and between 6bb2bfd067bdcdf3fb2292b2edb401ee5123dad1 and 4486d4b12353fcc439d8ee5fc275c126e93b2c3c.
📒 Files selected for processing (2)
packages/db-sqlite-persistence-core/src/persisted.tspackages/db-sqlite-persistence-core/tests/persisted.test.ts🚧 Files skipped from review as they are similar to previous changes (1)
📝 Walkthrough
Walkthrough#
Persisted SQLite sync startup now signals readiness when upstream sync omits
markReady, while preventing duplicate or late signals after cleanup. Tests cover preload completion, on-demand behavior, startup failures, readiness races, and cleanup.Changes#
Persisted preload readiness
packages/db-sqlite-persistence-core/src/persisted.tssyncModeis exposed to wrapper logic, and wrapped startup now signals readiness once after success or failure while respecting cleanup andon-demandmode.packages/db-sqlite-persistence-core/src/persisted.ts,packages/db-sqlite-persistence-core/tests/persisted.test.ts,.changeset/free-rivers-like.mdensureStarted()settles; tests cover missing upstream readiness, failures, races, and cleanup, and the changeset records the patch release.Estimated code review effort: 3 (Moderate) | ~25 minutes
Suggested reviewers:
kevin-dp,kyleamathews🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ Finishing Touches
🧪 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