Skip to content
Source
Sign inSign up
TanStack/db

fix(sqlite): avoid writer-lock inversion during live Electric recovery #1910

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 3 commits intomain fromrefs/pull/1910/headmerged 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 --check passed. 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. Review in Change Stack →

      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.yml
      • docs/contributing/oracle-coverage.md
      • docs/contributing/oracle-reviews/issue-1589-live-electric-opfs.md
      • packages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.html
      • packages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.spec.ts
      • packages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.ts
      • packages/browser-db-sqlite-persistence/package.json
      • packages/browser-db-sqlite-persistence/playwright.opfs-electric.config.ts
      • packages/browser-db-sqlite-persistence/tests/browser-coordinator.test.ts
      • packages/browser-db-sqlite-persistence/tsconfig.json
      • packages/browser-db-sqlite-persistence/vite.opfs.config.ts
      • packages/db-sqlite-persistence-core/src/persisted.ts

      Included 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

      Layer / File(s)Summary
      Schedule ordinary commits before writer lock
      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.md
      External commits can omit a scoped adapter so the coordinator schedules ordinary source commits before requesting the writer lock. The integration test checks scheduler, lock, and apply order, then verifies the persisted and public row.
      Build the browser probe and legacy-data maintenance path
      packages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.ts, packages/browser-db-sqlite-persistence/e2e/electric-resume-two-tab.opfs.html
      The browser driver reports collection state, captures Electric shape requests, and supports maintenance operations that remove selected durable rows and key-evidence data while checking the resume marker.
      Exercise two-tab recovery and failure cleanup
      packages/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
      The histories check schema versions, follower opening, leadership transfer, and recovery after partial or total row loss. They verify a fresh request at offset -1 with no handle and cover cleanup and diagnostic failure paths. The review records describe the checks and their limits.
      Configure and record the OPFS Electric oracle
      .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
      The package and E2E workflow run the new Playwright suite with an Electric URL. The Vite development server proxies /electric requests 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 697d9

      The 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 697d9

      The 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

      • inferred — The production ordering change can affect collections sharing a browser database's writer lock, but the inspected path retains coordinator-owned durable writes and leader fencing. The new destructive capability is in a loopback-served test page rather than the declared published package files.

      Trust Boundaries and Controls

      • observed — An ordinary commit does not gain a scoped adapter through the changed call. The coordinator routes persistence through its registered adapter, checks leadership, and validates leader state again before applying under the writer lock; hydration's scoped adapter remains on its existing path.

      Resilience and Maintainability Implications

      • observed — The scoped-adapter branch deliberately skips regular-scope entry because hydration already owns that scope. An adapter without regular-scope support retains the direct writer-lock fallback, so the scheduling guarantee is not demonstrated for every adapter implementation.

      Hardening Proposals

      • proposed — Keep the maintenance page restricted to isolated test origins and out of application deployments: if served on an application's origin, its URL-selected database and destructive probe would have access to that origin's OPFS state.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring 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…Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely describes the main change: preventing writer-lock inversion during live Electric recovery.
      Description check✅ PassedThe description explains the motivation, implementation, tests, limitations, and release impact. It includes the required checklist and confirms that a changeset was generated. Although it uses custom…
      Linked Issues check✅ PassedThe reviewed code already assigns adapters per collection through setAdapterForCollection, which prevents schema-version cross-wiring in #1589. The new live OPFS test covers both legacy partial-row …
      Out of Scope Changes check✅ PassedThe workflow entry, Playwright configuration, Vite proxy, browser fixtures, coordinator test, documentation, and changeset support the live OPFS regression coverage or the writer-lock ordering fix. No…
      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.)

      • Fix all pre-merge checks with AI
      ✨ Finishing Touches 💡 1
      📝 Generate docstrings 💡
      • Commit to this branch
      • Create a new PR
      🧪 Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR

      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
      Comment `@coderabbitai help` to get the list of available commands.
    2. More templates

      @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@1910

      commit: 697d978

    3. Size Change: 0 B

      Total Size: 174 kB

      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 7.97 kB

      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::react-db-package-size

Sign in to join this conversation.