Skip to content

Handle SQLite WASM worker readiness so first queries don’t hit the 5s follower timeout #21

Closed

Description

@findolor

Current behaviour

  • SQLiteWasmDatabase.new() returns immediately after spinning up a worker, but there’s no signal that the worker has finished acquiring the navigator.locks lock or opened the underlying SQLite database.
  • Callers often issue queries straight away. If the worker is still in its “follower” state, WorkerState::execute_query queues the request on the broadcast channel and races it against schedule_timeout_promise(…, 5000 ms). When no leader exists yet, the race always rejects with "Query timeout" even though the database is still initializing.

Desired behaviour

  • Provide an explicit readiness hook so callers can wait until the worker has a live connection before issuing SQL.
  • If a query arrives before leadership is established, reject immediately with a clear initialization error (e.g. InitializationPending) instead of waiting for the timeout.
  • Ideally make the follower timeout configurable rather than hard-coded.

Proposal

  1. Extend the JS API (e.g. SQLiteWasmDatabase.ready(): Promise) that resolves after WorkerState::attempt_leadership succeeds and the worker posts its worker-ready control message.
  2. Detect the “no leader yet” condition in execute_query and reject promptly with a dedicated error; only use the timeout when a leader fails to answer.
  3. Surface the timeout duration through configuration so consumers can tune it if needed.
  4. Document the new readiness/initialization flow so downstream users know to await readiness or retry on the explicit error.

This would eliminate spurious "Query timeout" errors during normal startup and make it easier for consumers to coordinate with the worker lifecycle.

Activity

  1. self-assigned this
    on Nov 5, 2025
  2. coderabbitai commented on Nov 5, 2025

    @coderabbitai

    A summary of the changes CodeRabbit can apply:

    • Update packages/sqlite-web/src/lib.rs to implement worker-ready signaling and callback-based readiness: replace the SQLiteWasmDatabase struct to store ready_callbacks and pending_queries, change install_onmessage_handler signature to capture ready callbacks, add handle_worker_control_message to resolve/reject the stored ready callbacks on "worker-ready"/"worker-error", and replace new() with a version that initializes ready_callbacks and exposes an async ready() method (plus related small worker-message and timeout/enum adjustments).

    • Add worker readiness/error signaling and configurable query timeout: modify coordination.rs to add timeout_ms to WorkerState, send a "worker-ready" message from the worker and use timeout_ms for pending query timeouts; update messages.rs to add MainThread "worker-error" message; change worker.rs to serialize and post MainThreadMessage::WorkerError when errors occur; and update packages/sqlite-web's lib.rs to track a ready_promise, pass it into install_onmessage_handler, handle "worker-ready"/"worker-error" control messages, expose a SQLiteWasmDatabase.ready() async method, and wire ready_promise into worker creation and message handling.

    • ✅ Create PR with these edits
    • 📋 Get copyable edits
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions