feat(sqlite-persistence): render completed progressive snapshots on startup #2203
main fromrefs/pull/2203/head·opened Fixes #2202
Electric progressive collections use core's on-demand sync mode, so initialRender currently rejects them. Allow local initial rendering only when the adapter can certify a previously completed full snapshot, with matching durable row-set evidence. Network synchronization continues in the background.
initialRender: {
strategy: 'network-first',
networkTimeoutMs: 0,
}
No caller-supplied progressive flag is required. A completed empty snapshot is eligible; an empty cold cache is not. Partial, legacy, reset, mismatched-shape, tag-dependent, and inconsistent-row-set caches cannot release initial rendering. Explicitly configured cursors cannot certify unseen rows as a full snapshot.
Changes across the monorepo:
@tanstack/db: add an adapter-ownedisPersistedSnapshotCompletecapability and an unavailable persisted-readiness state. Failed network loads reject rather than hanging when no eligible snapshot exists.@tanstack/electric-db-collection: record completion with the rows and resume metadata when progressive full synchronization completes; expose the capability only for progressive collections. Resume legacy progressive caches conservatively with a fresh full sync.@tanstack/db-sqlite-persistence-core: hydrate a progressive startup baseline only after checking completion metadata and key-set evidence from the same atomic SQLite snapshot.- Add regression coverage, documentation, and a changeset for all three runtime packages. React receiving tests cover Suspense waiting when the cache is unavailable.
Validation:
- Full Electric suite: 30 test files passed; Vitest reports 1,135 passed and 1 skipped, with no type errors.
- Persistence readiness oracle: 42 runtime and 29 type cases passed, including a 64-case outcome model, empty/nonempty progressive hydration before query demand, joins, restart, and unavailable-cache network failures.
- Electric SQLite receiving suite (included above): 40 runtime and 20 type cases passed. Completed and rejected cache cases use real SQLite with controlled SDK delivery. Full snapshots are saved and reopened without network delivery, including completed empty snapshots.
- Core observer/readiness regression suites: 82 tests passed. React Suspense suite: 31 tests passed.
- Additional persistence lifecycle, readiness exposure, and oracle suites passed.
- Calibration: bypassing completion certification makes partial, cold, and legacy receiving cases fail because they become wrongly eligible. The mutation was restored.
- DB core and both affected adapter/persistence package builds passed. ESLint reports no errors (20 existing warnings); formatting and
git diff --checkpassed.
Tradeoffs and scope:
- Older progressive caches lack completion evidence and require one fresh full sync before local fallback becomes eligible.
- Startup restores the full cached collection, so local I/O, CPU, and memory costs still apply. A completed snapshot can be stale until background synchronization catches up.
- This changes the initial-render fallback contract; ordinary collection reads and
useLiveQueryare not gated by it. Genuine on-demand collections remain unsupported. - The adapter capability is a proposed public API for maintainer review. This does not claim full-monorepo, live Electric server, browser OPFS, multi-tab, or cache-rotation validation.
- 1
Thank you for this PR, @Jose10go, and for the report that started this work.
We merged #2263 instead. It fixes #2202 without a new adapter API. With
initialRender: { strategy: 'network-first' }, an on-demand persisted Collection, including Electricprogressive, now works offline:- A query whose exact demand settled online in an earlier session renders from SQLite after
networkTimeoutMs. It renders at once if its upstream load fails. - After a progressive full sync completes, a query that never ran is also ready offline, because Electric settles each later load at once from its complete rows. A shared-model history in the Electric receiving test checks this case.
Because of this,
isPersistedSnapshotCompleteis not necessary, so I am closing this PR. One limit stays open: an eager Collection that is legitimately empty still stays loading offline. That is a separate law, and we will track it apart from #2263.This comment was written by Isaac.
- A query whose exact demand settled online in an earlier session renders from SQLite after
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
Important
Draft PR not reviewed#
Draft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration:
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