feat(web): replace sql.js with sqlite-wasm and OPFS by riderx · Pull Request #52 · Cap-go/capacitor-fast-sql

riderx · 2026-07-14T16:50:17Z

Summary

Replace sql.js + IndexedDB web backend with @sqlite.org/sqlite-wasm and OPFS persistence (fixes feat: replace sql.js with sqlite-wasm and OPFS #51)
Update WebConfig / docs for COOP/COEP requirements; example Vite config sets isolation headers
Fall back to a non-persistent worker DB with a warning when OPFS is unavailable

Test plan

bun run build / bun run verify:web pass
Example app with COOP/COEP: connect, insert, reload, data still present via OPFS
Without COOP/COEP: connect still works and warns that persistence is unavailable
Native iOS/Android verify unchanged

Made with Cursor

Summary by CodeRabbit

New Features
- Web database storage now uses SQLite WebAssembly with OPFS persistence.
- Added options to disable OPFS or provide a custom Worker.
- Added fallback behavior when OPFS is unavailable.
Documentation
- Updated setup, architecture, configuration, and troubleshooting guidance.
- Documented required cross-origin isolation headers.
- Noted that existing IndexedDB databases are not automatically migrated.
Bug Fixes
- Improved web SQL execution, result handling, and database connection management.

Persist web databases via the official SQLite Wasm OPFS VFS instead of loading the full DB into RAM and mirroring it through IndexedDB. Co-authored-by: Cursor <cursoragent@cursor.com>

coderabbitai · 2026-07-14T16:50:24Z

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 11 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 267481d6-3593-44bf-80af-bb9fc806fb75

📥 Commits

Reviewing files that changed from the base of the PR and between 8a362cb and 3a7a4e9.

⛔ Files ignored due to path filters (1)

bun.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

README.md
package.json
rollup.config.mjs
src/definitions.ts
src/web.ts

📝 Walkthrough

Walkthrough

Changes

The web database implementation was migrated from sql.js with IndexedDB persistence to SQLite Wasm workers with OPFS persistence and fallback behavior. Public configuration, bundling, Vite headers, architecture documentation, usage guidance, and troubleshooting instructions were updated.

SQLite Wasm Web Migration

Layer / File(s)	Summary
Web configuration and SQLite Wasm packaging `src/definitions.ts`, `package.json`, `rollup.config.mjs`	`WebConfig` now supports `useOpfs` and custom Workers; SQLite Wasm is added as a dependency and externalized from Rollup bundles.
Worker-backed database lifecycle and execution `src/web.ts`, `src/performance-config.ts`	The web plugin opens, configures, executes, and closes databases through `sqlite3Worker1Promiser`, preferring OPFS and falling back when unavailable.
Web server and bundler configuration `example-app/vite.config.ts`	Vite server and preview responses add COOP/COEP headers and exclude SQLite Wasm from dependency optimization.
Architecture, usage, and troubleshooting documentation `ARCHITECTURE.md`, `README.md`, `SETUP.md`	Documentation now describes SQLite Wasm, OPFS persistence, required headers, configuration options, migration limits, and troubleshooting steps.

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

Sequence Diagram(s)

sequenceDiagram
  participant App
  participant CapgoCapacitorFastSqlWeb
  participant sqlite3Worker1Promiser
  participant OPFS
  App->>CapgoCapacitorFastSqlWeb: connect(databaseName)
  CapgoCapacitorFastSqlWeb->>sqlite3Worker1Promiser: open database with OPFS preference
  sqlite3Worker1Promiser->>OPFS: access persistent storage
  OPFS-->>sqlite3Worker1Promiser: provide storage or report unavailable
  sqlite3Worker1Promiser-->>CapgoCapacitorFastSqlWeb: return dbId
  App->>CapgoCapacitorFastSqlWeb: execute SQL
  CapgoCapacitorFastSqlWeb->>sqlite3Worker1Promiser: exec with object rows
  sqlite3Worker1Promiser-->>CapgoCapacitorFastSqlWeb: return rows and metadata
  CapgoCapacitorFastSqlWeb-->>App: return query result

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly states the main web change: replacing sql.js with sqlite-wasm and OPFS.
Linked Issues check	✅ Passed	The web backend, docs, and config were updated to use sqlite-wasm with OPFS, matching the linked web-only feature request.
Out of Scope Changes check	✅ Passed	The changes stay focused on the web SQLite backend and related docs/config, with no clear unrelated feature additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-14T16:50:27Z

Beta npm build

Maintainers can publish this PR to npm for fast testing.

Comment /publish-beta after the PR checks are green.

The workflow will:

publish a prerelease package on the beta tag
add a pinned pr-52 dist-tag for this exact PR build
update this comment with the install command

Security note: beta publish is only enabled for branches inside this repository.

socket-security · 2026-07-14T16:50:36Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@rollup/plugin-node-resolve@16.0.3
	@sqlite.org/sqlite-wasm@3.53.0-build1

View full report

cursor

Stale comment

Risk: medium. This PR replaces the web SQL backend (sql.js → sqlite-wasm/OPFS), exceeding the low-risk approval threshold. Cursor Bugbot was not present; CI passed with no unresolved automated findings. Human review is needed; reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Approver External}

riderx · 2026-07-14T17:05:17Z

@coderabbitai review

coderabbitai · 2026-07-14T17:05:24Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

rollup.config.mjs (1)
8-22: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Bundle @sqlite.org/sqlite-wasm for the IIFE build
@sqlite.org/sqlite-wasm doesn’t expose a browser global, so globals: { '@sqlite.org/sqlite-wasm': 'sqlite3Wasm' } makes dist/plugin.js fail when loaded directly. Either inline this dependency for the IIFE target or drop the script-tag distribution.
🤖 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 `@rollup.config.mjs` around lines 8 - 22, Update the IIFE output configuration
in rollup.config.mjs to bundle `@sqlite.org/sqlite-wasm` instead of mapping it to
the nonexistent sqlite3Wasm browser global; keep the dependency external for the
CJS output if required by its existing distribution contract.

🤖 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 `@README.md`:
- Around line 163-166: Update the README header code fence containing the
Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy lines to include the
text language identifier after the opening fence, preserving the header examples
unchanged.
- Line 648: Update the worker option type in src/definitions.ts to expose Worker
| (() => Worker) instead of any, then regenerate the README API section so its
worker row reflects that type; do not edit README.md directly.

In `@src/web.ts`:
- Around line 137-166: Update the exec request in the method containing this
promiser call to include countChanges: true and lastInsertRowId: true,
preserving the existing SQL execution flow. Adjust the catch block to prefer
error?.result?.message, then error.message, and finally String(error) when
constructing the SQL execution failure.

---

Outside diff comments:
In `@rollup.config.mjs`:
- Around line 8-22: Update the IIFE output configuration in rollup.config.mjs to
bundle `@sqlite.org/sqlite-wasm` instead of mapping it to the nonexistent
sqlite3Wasm browser global; keep the dependency external for the CJS output if
required by its existing distribution contract.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: d1079ca1-153c-4c23-913a-c3084bf00fa6

📥 Commits

Reviewing files that changed from the base of the PR and between c0fb8ba and 8a362cb.

⛔ Files ignored due to path filters (1)

bun.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

ARCHITECTURE.md
README.md
SETUP.md
example-app/vite.config.ts
package.json
rollup.config.mjs
src/definitions.ts
src/performance-config.ts
src/web.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Cap-go/capacitor-updater (manual)

💤 Files with no reviewable changes (1)

src/performance-config.ts

Pass countChanges/lastInsertRowId on exec, unwrap Worker1 errors, bundle sqlite-wasm into the IIFE build, and tighten WebConfig docs. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

cursor

Risk: medium. This PR replaces the web SQL backend (sql.js → sqlite-wasm/OPFS), exceeding the low-risk approval threshold. Cursor Bugbot was not present on this PR. Human review is needed; reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Approver External}

cursor

Risk: medium. Cursor Bugbot was not present on this PR; CodeRabbit approved with all review threads resolved and CI checks passed. Approved.

_{Sent by Cursor Approval Agent: Pull Request Approver}

feat(web): replace sql.js with sqlite-wasm and OPFS

8a362cb

Persist web databases via the official SQLite Wasm OPFS VFS instead of loading the full DB into RAM and mirroring it through IndexedDB. Co-authored-by: Cursor <cursoragent@cursor.com>

riderx marked this pull request as ready for review July 14, 2026 16:54

cursor Bot approved these changes Jul 14, 2026 •

edited

Loading

View reviewed changes

cursor Bot reviewed Jul 14, 2026

View reviewed changes

coderabbitai Bot requested changes Jul 14, 2026

View reviewed changes

Comment thread README.md Outdated

Comment thread README.md Outdated

Comment thread src/web.ts

riderx and others added 2 commits July 14, 2026 19:07

fix(web): address review feedback for sqlite-wasm

f844b16

Pass countChanges/lastInsertRowId on exec, unwrap Worker1 errors, bundle sqlite-wasm into the IIFE build, and tighten WebConfig docs. Co-authored-by: Cursor <cursoragent@cursor.com>

style: format files after sqlite-wasm review fixes

3a7a4e9

Co-authored-by: Cursor <cursoragent@cursor.com>

coderabbitai Bot approved these changes Jul 14, 2026

View reviewed changes

cursor Bot reviewed Jul 14, 2026

View reviewed changes

cursor Bot approved these changes Jul 14, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

riderx commented Jul 14, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Jul 14, 2026

Beta npm build

Uh oh!

socket-security Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

riderx commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

riderx commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

socket-security Bot commented Jul 14, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading