Use sqlite-web transaction local DB API by findolor · Pull Request #2795 · rainlanguage/raindex

findolor · 2026-07-01T08:41:25Z

Summary

bump @rainlanguage/sqlite-web to 0.0.3
replace the old positional local DB callbacks with an options object: { localDb, statusCallback }
require localDb.query, localDb.wipeAndRecreate, and localDb.transaction for sync YAMLs
send batch writes through one localDb.transaction([...]) call instead of looping queries with manual BEGIN / COMMIT
keep schema/reset/view SQL as single .sql scripts and adapt them into sqlite-web-compatible single-statement batches at the Rust boundary
update webapp wiring, mocks, README/API docs, and local DB WASM tests

Review

Ran a staged local review with two read-only reviewers.
Fixed the actionable finding by adding direct WASM constructor coverage for the exported { localDb, statusCallback } options path and missing transaction validation.

Verification

cargo check -p raindex_common
cargo check -p raindex_common -p raindex_cli
cargo test --workspace
cargo test -p raindex_common local_db::
cargo test -p raindex_cli local_db::pipeline::bootstrap
nix develop .#wasm-shell -c bash -c 'CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner cargo test --target wasm32-unknown-unknown --lib -p raindex_quote -p raindex_bindings -p raindex_js_api -p raindex_common'
nix develop .#wasm-shell -c bash -c 'npm install --no-check && cd packages/raindex && npm run build && npm test'
nix develop .#wasm-shell -c bash -c 'npm install --no-check && npm run svelte-lint-format-check -w @rainlanguage/webapp && npm run test -w @rainlanguage/webapp'
nix develop .#wasm-shell -c bash -c 'npm install --no-check && npm run build -w @rainlanguage/raindex && npm run build -w @rainlanguage/ui-components && npm run build -w @rainlanguage/webapp && npm run lint-format-check:all && npm run test --workspaces'
git diff --check
nix develop -c rainix-rs-static
In-app browser smoke test against http://127.0.0.1:5173/db-playground
- initially caught sqlite-web Batch statements must contain a single statement
- fixed by adapting the existing SQL scripts into single-statement transaction entries before calling sqlite-web
- rerun showed LOCALDB ACTIVE; schema query returned local DB tables; db_metadata returned { id: 1, db_schema_version: 5 }
- relevant browser logs showed no sqlite/localDb transaction error; only the expected sqlite-web WASM load warning

Summary by CodeRabbit

New Features
- Local DB setup now uses a single options object, making configuration simpler and more consistent.
- SQL operations for table creation, cleanup, and related tasks now run as batched statements, improving reliability.
- Registry and client APIs now support updated local DB and status callback handling.
Bug Fixes
- Improved handling for reset and transaction flows, including clearer error reporting when required local DB functions are missing.
Documentation
- Updated setup and architecture docs to match the new configuration format.

findolor · 2026-07-01T08:41:39Z

Use sqlite-web transaction local DB API #2795 👈 (View in Graphite)
main

How to use the Graphite Merge Queue

Add the label Raindex-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

coderabbitai · 2026-07-01T08:41:43Z

Warning

Review limit reached

@findolor, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d2e513a0-1f4b-4fe5-8e7d-5a93b2eb25af

📥 Commits

Reviewing files that changed from the base of the PR and between b080e7d and 1afc572.

⛔ Files ignored due to path filters (1)

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (29)

crates/cli/src/commands/local_db/pipeline/bootstrap.rs
crates/common/src/local_db/executor.rs
crates/common/src/local_db/pipeline/adapters/bootstrap.rs
crates/common/src/local_db/query/clear_tables/mod.rs
crates/common/src/local_db/query/create_tables/mod.rs
crates/common/src/local_db/query/create_views/mod.rs
crates/common/src/local_db/query/mod.rs
crates/common/src/local_db/query/sql_script.rs
crates/common/src/local_db/query/sql_statement_batch.rs
crates/common/src/raindex_client/local_db/executor.rs
crates/common/src/raindex_client/local_db/mod.rs
crates/common/src/raindex_client/local_db/orders.rs
crates/common/src/raindex_client/local_db/pipeline/bootstrap.rs
crates/common/src/raindex_client/local_db/pipeline/runner/scheduler/wasm.rs
crates/common/src/raindex_client/local_db/query/clear_tables.rs
crates/common/src/raindex_client/local_db/query/create_tables.rs
crates/common/src/raindex_client/local_db/vaults.rs
crates/common/src/raindex_client/mod.rs
crates/common/src/raindex_client/raindex_yaml.rs
crates/common/src/raindex_client/trades/get_by_owner.rs
crates/common/src/raindex_client/trades/get_by_tx.rs
crates/common/src/raindex_client/trades/mod.rs
crates/common/src/raindex_client/vaults.rs
crates/js_api/src/registry.rs
package.json
packages/raindex/ARCHITECTURE.md
packages/raindex/README.md
packages/webapp/ARCHITECTURE.md
packages/webapp/src/routes/+layout.ts

📝 Walkthrough

Walkthrough

The PR reworks SQL execution into transaction batches (new SqlScript parser, clear_tables_batch/create_tables_batch/create_views_batch, SqlStatementBatch::inner_statements) used by reset/bootstrap flows, and refactors the JS local-database callback API into a unified local_db/options object consumed by JsCallbackExecutor, LocalDb, RaindexClient::new, and the JS API registry, with matching tests, webapp wiring, and docs updated.

Changes

SQL batch execution refactor

Layer / File(s)	Summary
SqlScript parsing and batch helpers `crates/common/src/local_db/query/sql_script.rs`, `.../query/mod.rs`, `.../query/sql_statement_batch.rs`	Adds `SqlScript` for splitting SQL text into statements/batches (quote/comment aware) and `SqlStatementBatch::inner_statements` for transaction-aware slicing.
Clear/create/view table batches `.../query/clear_tables/mod.rs`, `.../query/create_tables/mod.rs`, `.../query/create_views/mod.rs`	Replaces single-statement builders with `clear_tables_batch`, `vacuum_stmt`, `create_tables_batch`, and drop/create view statement builders derived via `SqlScript`.
local_db executor test updates `crates/common/src/local_db/executor.rs`	Test schema-stamping switches from `create_tables_stmt` to `create_tables_sql`/`create_tables_batch` via `execute_batch`.
reset_db orchestration `crates/common/src/local_db/pipeline/adapters/bootstrap.rs`	`reset_db` now runs clear batch → vacuum → create batch; tests rewritten with `with_batch`/`reset_prefix_sql` ordering assertions.
CLI bootstrap test alignment `crates/cli/src/commands/local_db/pipeline/bootstrap.rs`	Test mocks and assertions updated to the batch-based reset sequence and error propagation checks.

Estimated code review effort: 4 (Complex) | ~60 minutes

Local DB options-object API refactor

Layer / File(s)	Summary
Executor core refactor `crates/common/src/raindex_client/local_db/executor.rs`	`JsCallbackExecutor` holds a `local_db` JsValue; `execute_batch`/`invoke_transaction_unlocked` issue a single `transaction` callback from `inner_statements`; `wipe_and_recreate` simplified; tests rewritten accordingly.
LocalDb wrapper and scheduler helper `.../local_db/mod.rs`, `.../pipeline/runner/scheduler/wasm.rs`	`LocalDb::from_js_local_db(local_db: JsValue)` replaces `from_js_callback`; scheduler test helper builds an object-based mock local_db.
Query wrappers and pipeline bootstrap tests `.../local_db/query/clear_tables.rs`, `.../query/create_tables.rs`, `.../pipeline/bootstrap.rs`	`clear_tables`/`create_tables` execute batches through the new executor; tests assert transaction callback usage and reset-batch calls.
RaindexClient options API `crates/common/src/raindex_client/mod.rs`	`RaindexClient::new` now takes `options: Option<JsValue>` parsed into `LocalDbClientOptions` (localDb, statusCallback) via `Reflect`; wiring and tests updated.
Registry options parameter `crates/js_api/src/registry.rs`	`getRaindexClient` accepts a single `options` parameter, forwarded to `RaindexClient::new`.
Downstream test call-sites `.../local_db/orders.rs`, `.../local_db/vaults.rs`, `.../trades/*`, `.../vaults.rs`, `.../raindex_yaml.rs`	Tests migrated to `new_test_client_with_local_db`/`local_db_object_from_query_callback` and reduced `RaindexClient::new` argument lists.
Webapp, docs, dependency `packages/webapp/src/routes/+layout.ts`, `packages/*/ARCHITECTURE.md`, `packages/raindex/README.md`, `package.json`	`+layout.ts` passes `{ localDb, statusCallback }`; docs updated to match; `@rainlanguage/sqlite-web` bumped to `^0.0.3`.

Estimated code review effort: 5 (Critical) | ~110 minutes

Sequence Diagram(s)

sequenceDiagram
  participant JS
  participant RaindexClient
  participant LocalDbClientOptions
  participant LocalDb
  participant JsCallbackExecutor
  participant JsLocalDb

  JS->>RaindexClient: new(settings, subgraphs, options)
  RaindexClient->>LocalDbClientOptions: parse(options)
  LocalDbClientOptions-->>RaindexClient: localDb, statusCallback
  RaindexClient->>LocalDb: from_js_local_db(localDb)
  LocalDb->>JsCallbackExecutor: new(local_db)
  JsCallbackExecutor->>JsLocalDb: query / wipeAndRecreate / transaction (validated)

sequenceDiagram
  participant BootstrapPipeline
  participant Executor
  participant JsCallbackExecutor
  participant JsLocalDb

  BootstrapPipeline->>Executor: execute_batch(clear_tables_batch())
  BootstrapPipeline->>Executor: query_text(vacuum_stmt())
  BootstrapPipeline->>Executor: execute_batch(create_tables_batch())
  Executor->>JsCallbackExecutor: invoke_transaction_unlocked(batch)
  JsCallbackExecutor->>JsLocalDb: transaction(local_db, statements array)

Possibly related PRs

rainlanguage/raindex#2584: Both PRs change the vault_deltas view drop/recreate path via create_views_batch and related reset SQL expectations.
rainlanguage/raindex#2587: Both touch the batch-based clear_tables/create_tables execution path and the schema tables involved.
rainlanguage/raindex#2698: Both affect the create_tables_batch/CREATE_TABLES_SQL statements and header-guard PRAGMA stamping consumed by the batch execution flow.

Suggested reviewers: 0xgleb, JuaniRios, hardyjosh

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 76.07% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: switching to the sqlite-web transaction-based local DB API.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch arda/sqlite-web-transaction-localdb

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.}

coderabbitai

Actionable comments posted: 3

♻️ Duplicate comments (6)

crates/common/src/local_db/query/create_tables/statements/063.sql (1)

1-2: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win