fix(sqlite): avoid writer-lock inversion during live Electric recovery #1910
main fromrefs/pull/1910/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Why this matters#
Live Electric recovery can stall if an ordinary source commit requests the shared OPFS writer lock before it enters the persistence scheduler. Another Collection can then hold the scheduler while it waits for that lock. This PR makes ordinary source commits enter the scheduler before they request the writer lock.
Issue #1589 reported cross-Collection schema resets and a stale Electric resume marker. Earlier changes on main protect those paths. This PR adds a live two-tab witness for that behavior and repairs the lock inversion exposed during the test.
How it works#
The persisted source-commit path no longer passes a hydration-scoped adapter to the coordinator. The coordinator can therefore schedule an ordinary commit before it requests the database-wide writer lock. Hydration work still passes its scoped adapter because it already owns that scheduler scope.
The new Chromium test runs two tabs with OPFS, Web Locks, PostgreSQL, and the installed Electric SDK. The Collections use different schema versions. The test checks exact public and durable rows when a follower opens and after it takes leadership. It then removes either one row or all rows from a legacy baseline while it preserves a stale resume marker. On reopen, Collection A must request a fresh snapshot from offset -1 and recover the PostgreSQL rows. Collection B must retain its rows.
A controlled coordinator test checks scheduler entry before the writer-lock request. A temporary restoration of the old bypass failed at that exact assertion. The test fixture also preserves the primary failure when diagnostic or cleanup work fails.
These tests cover the stated Chromium histories. They do not test React Native, Firefox or Zen, React rendering, large datasets, or exclusive OPFS ownership. This PR does not close #1589.
Verification#
- Browser coordinator suite: 154 tests passed.
- Live Chromium suite: all four tests passed in four repeat runs each.
- TypeScript, changed-file ESLint, Prettier, and
git diff --checkpassed. ESLint reported warnings only on unchanged lines.
Checklist#
- I have tested this code locally with
pnpm test. Targeted suites passed as listed above. - 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
- Ordinary persisted commits are scheduled before the database writer lock is acquired, helping prevent coordination issues across browser tabs.
- Recovery now requests a fresh snapshot when persisted rows are missing, rather than resuming from stale progress.
- Tests
- Added coverage for two-tab live data recovery, leadership transfers, and persistence behavior.
- Documentation
- Documented test coverage and its limitations.
- 1
More templates
- offline-first-electron
- offline-transactions-react-native
- shopping-list-react-native
- @tanstack/db-example-react-next-ssr-e2e
- tanstack-start-example-basic
- @tanstack/db-example-paced-mutations-demo
- tanstack-start-db-projects-example
- @tanstack/db-example-react-start-ssr-e2e
- @tanstack/db-example-react-todo
- @tanstack/db-example-solid-todo
- todos
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1910@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1910@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1910@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1910@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1910@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1910@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1910@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1910@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1910@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1910@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1910@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1910@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1910@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1910@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1910@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1910@tanstack/react-router-with-db
npm i https://pkg.pr.new/@tanstack/react-router-with-db@1910@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1910@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1910@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1910@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1910@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1910@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1910commit:
697d978Size Change: 0 B
Total Size: 174 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/client.js3.7 kB packages/db/dist/esm/collection-options.js236 B packages/db/dist/esm/collection/change-events.js1.44 kB packages/db/dist/esm/collection/changes.js2.4 kB packages/db/dist/esm/collection/cleanup-queue.js794 B packages/db/dist/esm/collection/events.js481 B packages/db/dist/esm/collection/index.js4.46 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js2.69 kB packages/db/dist/esm/collection/mutations.js2.61 kB packages/db/dist/esm/collection/state.js8.32 kB packages/db/dist/esm/collection/subscription.js8.81 kB packages/db/dist/esm/collection/sync.js5.09 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.34 kB packages/db/dist/esm/event-emitter.js964 B packages/db/dist/esm/index.js3.82 kB packages/db/dist/esm/indexes/auto-index.js829 B packages/db/dist/esm/indexes/base-index.js1.18 kB packages/db/dist/esm/indexes/basic-index.js2.07 kB packages/db/dist/esm/indexes/btree-index.js2.26 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js376 B packages/db/dist/esm/live-query-adapter.js318 B packages/db/dist/esm/live-query-observer.js3.69 kB packages/db/dist/esm/live-query-options.js731 B packages/db/dist/esm/live-query-window-controller.js4.36 kB packages/db/dist/esm/local-only.js989 B packages/db/dist/esm/local-storage.js2.17 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js496 B packages/db/dist/esm/proxy.js3.32 kB packages/db/dist/esm/query/builder/clone-query.js748 B packages/db/dist/esm/query/builder/functions.js1.47 kB packages/db/dist/esm/query/builder/index.js6.76 kB packages/db/dist/esm/query/builder/query-ir.js116 B packages/db/dist/esm/query/builder/ref-proxy.js1.28 kB packages/db/dist/esm/query/compiler/evaluators.js2.04 kB packages/db/dist/esm/query/compiler/expressions.js603 B packages/db/dist/esm/query/compiler/group-by.js4.14 kB packages/db/dist/esm/query/compiler/index.js9.11 kB packages/db/dist/esm/query/compiler/joins.js2.99 kB packages/db/dist/esm/query/compiler/lazy-targets.js1.12 kB packages/db/dist/esm/query/compiler/order-by.js1.93 kB packages/db/dist/esm/query/compiler/parent-routes.js319 B packages/db/dist/esm/query/compiler/query-equivalence.js455 B packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB packages/db/dist/esm/query/compiler/select.js1.59 kB packages/db/dist/esm/query/effect.js5.22 kB packages/db/dist/esm/query/equality-value-identity.js591 B packages/db/dist/esm/query/expression-helpers.js1.45 kB packages/db/dist/esm/query/ir-stable-identity.js4.21 kB packages/db/dist/esm/query/ir.js1.74 kB packages/db/dist/esm/query/live-query-collection.js391 B packages/db/dist/esm/query/live/bucket-facade-adapter.js2.73 kB packages/db/dist/esm/query/live/collection-config-builder.js7.11 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js2.31 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/materialized-pipeline.js2.32 kB packages/db/dist/esm/query/live/ordered-source-loader.js4.32 kB packages/db/dist/esm/query/live/subset-demand-controller.js1.57 kB packages/db/dist/esm/query/live/utils.js1.19 kB packages/db/dist/esm/query/optimizer.js3.11 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/runtime-reference-identity.js630 B packages/db/dist/esm/query/subset-dedupe.js497 B packages/db/dist/esm/scheduler.js1.34 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/sync-persistence.js530 B packages/db/dist/esm/transactions.js3.71 kB packages/db/dist/esm/utils.js1.21 kB packages/db/dist/esm/utils/array-utils.js270 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js4.51 kB packages/db/dist/esm/utils/callbacks.js174 B packages/db/dist/esm/utils/comparison.js1.5 kB packages/db/dist/esm/utils/cursor.js677 B packages/db/dist/esm/utils/error.js167 B packages/db/dist/esm/utils/get-or-create.js155 B packages/db/dist/esm/utils/index-optimization.js2.42 kB packages/db/dist/esm/utils/type-guards.js230 B packages/db/dist/esm/utils/uuid.js449 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 7.97 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/DbProvider.js317 B packages/react-db/dist/esm/HydrationBoundary.js263 B packages/react-db/dist/esm/index.js330 B packages/react-db/dist/esm/live-query-internals.js282 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.9 kB packages/react-db/dist/esm/useLiveQuery.js3.3 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js820 B packages/react-db/dist/esm/usePacedMutations.js401 B KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
Navigate logical layers of code changes, visualize relationships, and explore their blast radius.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Advanced
Run ID:
47680cf6-e4d7-4102-aa14-171e2bee1957📥 Commits
Reviewing files that changed from the base of the PR and between 8df353a68b841ce55f76230b1197c3bf580d43fe and 697d9789df7a1db17909740298289f2c2618696c.
📒 Files selected for processing (13)
.changeset/fix-live-electric-opfs-resume-lock-order.md.github/workflows/e2e-tests.ymldocs/contributing/oracle-coverage.mddocs/contributing/oracle-reviews/issue-1589-live-electric-opfs.mdpackages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.htmlpackages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.spec.tspackages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.tspackages/browser-db-sqlite-persistence/package.jsonpackages/browser-db-sqlite-persistence/playwright.opfs-electric.config.tspackages/browser-db-sqlite-persistence/tests/browser-coordinator.test.tspackages/browser-db-sqlite-persistence/tsconfig.jsonpackages/browser-db-sqlite-persistence/vite.opfs.config.tspackages/db-sqlite-persistence-core/src/persisted.tsIncluded review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 3 remain after this review.
📝 Walkthrough
Walkthrough#
The persistence coordinator now schedules ordinary source commits before acquiring the database writer lock. New browser tests exercise two-tab OPFS/live Electric histories, including leadership changes and recovery after legacy row loss with a stale resume marker. The E2E workflow and package configuration can run these tests.
Changes#
Electric OPFS recovery
packages/db-sqlite-persistence-core/src/persisted.ts,packages/browser-db-sqlite-persistence/tests/browser-coordinator.test.ts,.changeset/fix-live-electric-opfs-resume-lock-order.mdpackages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.ts,packages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.htmlpackages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.spec.ts,docs/contributing/oracle-coverage.md,docs/contributing/oracle-reviews/issue-1589-live-electric-opfs.md-1with no handle and cover cleanup and diagnostic failure paths. The review records describe the checks and their limits..github/workflows/e2e-tests.yml,packages/browser-db-sqlite-persistence/package.json,packages/browser-db-sqlite-persistence/playwright.opfs-electric.config.ts,packages/browser-db-sqlite-persistence/tsconfig.json,packages/browser-db-sqlite-persistence/vite.opfs.config.ts/electricrequests to that URL or its local default.Priority: ➖ Normal
Estimated code review effort: 4 (Complex) | ~45 minutes
Change: Bug fix · Severity of issue fixed: Medium
Merge Risk: ⚪ Minimal · up to
697d9The change is mergeable after normal checks; the supplied evidence identifies no remaining issue that should block it.
Security Architecture Review#
Security architecture risk: 🔵 Low · up to
697d9The revised lock order addresses a cross-collection stall without an identified new security exposure. The accompanying recovery test is confined to the browser test setup, but other runtimes and custom coordinators remain outside the demonstrated coverage.
Retained concerns No architecture-level concerns identified.
Security review details
Security Blast Radius
Trust Boundaries and Controls
Resilience and Maintainability Implications
Hardening Proposals
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
setAdapterForCollection, which prevents schema-version cross-wiring in#1589. The new live OPFS test covers both legacy partial-row …Full details: Docstring Coverage
Explanation
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 6 files. (7 skipped: 7 unsupported.)
✨ Finishing Touches 💡 1
📝 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