Skip to content
Source
Sign inSign up
TanStack/db

test(browser-sqlite): cover Electric insert across immediate reload #1914

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 4 commits intomain fromrefs/pull/1914/headmerged by KyleAMathews(GitHub profile, opens in a new tab)

Summary

Adds a live Chromium/OPFS/Electric check for the insert → awaitTxId → immediate-refresh history in #1456. The test uses the reporter-style onInsert handler, commits the row in PostgreSQL, then holds the browser adapter's row write. It verifies the transaction is acknowledged and visible while OPFS still has no row, closes the page without releasing the write, and verifies a new page recovers the exact row from Electric and persists it.

Clarifies in the Electric collection guide that awaitTxId is stream evidence, not a local SQLite durability acknowledgment. No production behavior changes.

Verification

  • Live Chromium/OPFS/Electric lane: 9 passed.
  • Focused immediate-reload check: 5 repeated runs passed.
  • Browser package TypeScript, ESLint, Prettier, and git diff --check passed.

Limits

This does not reproduce the reporter's Windows 11/Edge environment or older package versions, and it does not establish offline recovery after closing before local durability. #1456 was closed on current-main evidence; a current-version Edge reproduction can reopen it. This PR does not choose a durable pending-mutation policy.

Refs #1456.

Summary by CodeRabbit

  • Documentation

    • Clarified that seeing a transaction in the Electric stream does not confirm its local SQLite write is durable. Closing the page before that write completes may require the row to be recovered.
    • Documented a bounded Chromium/OPFS scenario where a row is recovered after the page closes during a pending local write, along with the limits of what the scenario demonstrates.
  • Tests

    • Added end-to-end coverage verifying that a committed row is recovered and persisted after an immediate page close, without a duplicate insert.
    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: d1f42d7d-8f6f-494a-a843-9de6a2638b1e

      📥 Commits

      Reviewing files that changed from the base of the PR and between 595697ab7da30d59ddb4d97f82626757ca2653a0 and f9aae2da4aa0a386464fb17771e34b78bcc9bd34.

      📒 Files selected for processing (4)
      • docs/contributing/oracle-coverage.md
      • docs/contributing/oracle-reviews/pr-1914-immediate-reload-follow-up.md
      • packages/browser-db-sqlite-persistence/e2e/electric-immediate-reload.opfs.spec.ts
      • packages/browser-db-sqlite-persistence/e2e/electric-immediate-reload.opfs.ts
      🚧 Files skipped from review as they are similar to previous changes (1)
      • docs/contributing/oracle-coverage.md

      Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.


      📝 Walkthrough

      Walkthrough

      Adds a Chromium/OPFS browser probe and Playwright test for an insert acknowledged before its local SQLite write completes. The test closes the page while the write is held, then checks that the row appears in public and durable data after reopening. Documentation describes the acknowledgment boundary and the tested limits.

      Changes

      Electric immediate-reload witness

      Layer / File(s)Summary
      Probe behavior and acknowledgment boundary
      packages/browser-db-sqlite-persistence/e2e/electric-immediate-reload.opfs.ts, docs/collections/electric-collection.md
      The probe creates a persisted Electric collection and can hold non-delete adapter writes in hold mode. The collection documentation states that awaitTxId does not confirm local SQLite durability.
      Playwright immediate-reload witness
      packages/browser-db-sqlite-persistence/e2e/electric-immediate-reload.opfs.spec.ts, packages/browser-db-sqlite-persistence/e2e/electric-immediate-reload.opfs.html, packages/browser-db-sqlite-persistence/playwright.opfs-electric.config.ts, docs/contributing/oracle-coverage.md, docs/contributing/oracle-reviews/pr-1914-immediate-reload-follow-up.md
      The test checks PostgreSQL acknowledgment while the source write is held, closes the first page, and verifies public and durable rows after reopening. The Playwright config includes the test. The coverage documentation and follow-up record describe the witness, its observed checkpoints, and its limits.

      Priority: ⬇️ Low

      Estimated code review effort: 3 (Moderate) | ~25 minutes

      Change: Other

      Merge Risk: ⚪ Minimal · up to f9aae

      This change adds a bounded recovery test and clarifies the durability guarantee. No issue identified here prevents merging.

      🚥 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 3 files. (2 skipped: 2…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: adding browser SQLite coverage for the Electric insert flow across an immediate reload.
      Description check✅ PassedThe description provides the change summary, verification results, release impact context, references, and known limitations. It uses different headings from the template and omits the checklist check…
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      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 3 files. (2 skipped: 2 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@1914

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1914

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1914

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1914

      @tanstack/db

      npm i https://pkg.pr.new/@tanstack/db@1914

      @tanstack/db-ivm

      npm i https://pkg.pr.new/@tanstack/db-ivm@1914

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1914

      @tanstack/electric-db-collection

      npm i https://pkg.pr.new/@tanstack/electric-db-collection@1914

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1914

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1914

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1914

      @tanstack/offline-transactions

      npm i https://pkg.pr.new/@tanstack/offline-transactions@1914

      @tanstack/powersync-db-collection

      npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1914

      @tanstack/query-db-collection

      npm i https://pkg.pr.new/@tanstack/query-db-collection@1914

      @tanstack/react-db

      npm i https://pkg.pr.new/@tanstack/react-db@1914

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1914

      @tanstack/react-router-with-db

      npm i https://pkg.pr.new/@tanstack/react-router-with-db@1914

      @tanstack/rxdb-db-collection

      npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1914

      @tanstack/solid-db

      npm i https://pkg.pr.new/@tanstack/solid-db@1914

      @tanstack/svelte-db

      npm i https://pkg.pr.new/@tanstack/svelte-db@1914

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1914

      @tanstack/trailbase-db-collection

      npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1914

      @tanstack/vue-db

      npm i https://pkg.pr.new/@tanstack/vue-db@1914

      commit: f9aae2d

    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.