Skip to content

Use query workers by default, but only for large fan-outs - #63

Merged
abdullah-bl merged 1 commit into
mainfrom
feat/query-workers-default
Nov 16, 2026
Merged

abdullah-bl merged 1 commit into
mainfrom
feat/query-workers-default

Conversation

@abdullah-bl

Copy link
Copy Markdown
Owner

What changed

Query workers (SQLite) were off unless ONEBASE_QUERY_WORKERS was set. They are now on by default, and used only when a write affects enough live queries to keep the main thread busy.

  • When workers are used. A round of background re-runs starts on the main thread. If it is still going after 4 ms (QUERY_WORKERS_AFTER_MS), the rest goes to the workers. The first worker starts the first time that happens, and the main thread carries on until the worker has loaded the code.
  • Default count. 2 workers, 1 on a two-core machine, none on a single core. ONEBASE_QUERY_WORKERS=0 keeps every query on the main thread, as before.
  • queryWorkersAfterMs is a new Runtime option; 0 sends every background re-run to a worker, which is the old behaviour of an explicit setting. The existing worker tests use it.

Why not simply flip the default

Measured with scripts/bench-query-workers.ts on a 20-core machine, sending every background re-run to a worker:

Subscribers affected by a write Workers off Workers always on
10 all updated in 0.4–0.6 ms 1.5–2 ms, plus 15–30 MB
100 2–5 ms 3–12 ms
2,000 main thread busy 100 ms main thread busy 21 ms

The first update after a start or deploy also took 25–58 ms instead of 1–2 ms, while the worker loaded the code.

With this change, at 10 subscribers the numbers match workers off and no worker is started. At 2,000 subscribers (heavier query) the main thread is busy 26 ms per write and everyone is updated in 48 ms, against 100 ms and 86 ms with workers off.

For the reviewer

  • Behaviour change for anyone who already set ONEBASE_QUERY_WORKERS: small fan-outs now stay on the main thread for them too. That is faster for those writes, but it is a change.
  • One cost against always-on: the longest main-thread stall at 2,000 subscribers is about 4 ms, where always-on managed about 1.5 ms. Workers off is 8 ms.
  • The 4 ms threshold is a judgment call. At 2 ms the stall drops to 2 ms but a 100-subscriber fan-out of cheap queries gets slower (2.4 ms to 6 ms). At 8 ms nothing small is affected but the stall is back to 7.5 ms.
  • A server that has had one large fan-out keeps its first worker (15–30 MB) from then on; workers beyond the first stop after 30 idle seconds.

Testing

  • Typecheck clean; bun test on SQLite: 580 pass, 3 skipped, 0 fail. Postgres, MySQL and libSQL never use query workers; CI runs them.
  • New test: with default settings a small fan-out starts no worker and runs nothing on one, and a large fan-out moves to the workers.
  • Soak (not in the repo): 1,500 per-user subscribers, 14,700 mixed writes over 30 seconds, 1.38 million re-runs on workers. Every subscriber's last result matched a fresh run of its query; no errors.
  • Compiled binary: built with the release flags, served a project, 200 subscriptions over WebSocket with writes from another connection. 189 were last updated by a worker, onebase_query_worker_runs_total was 546, and the log had no warnings.
  • docs/functions.md has the re-measured table; SUBSCRIBERS=10 bun scripts/bench-query-workers.ts reproduces the small case.

🤖 Generated with Claude Code

Query workers were off unless ONEBASE_QUERY_WORKERS was set. Turning them
on for every background re-run would have made small apps worse: with 10
subscribers an update took 1.5-2 ms where it took 0.5 ms, a worker cost
15-30 MB, and the first update after a start or deploy waited 25-58 ms for
the worker to load the code.

So a round of background re-runs now starts on the main thread, and only
what is left after 4 ms goes to the workers. The first worker starts the
first time a round runs that long, and the main thread carries on until it
is ready. A small fan-out is handled exactly as with workers off and
starts no worker; with 2,000 subscribers the main thread is busy 26 ms per
write, where it was 100 ms.

The default is 2 workers, 1 on two cores, none on one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@abdullah-bl
abdullah-bl merged commit 7991c16 into main Nov 16, 2026
1 check passed
@abdullah-bl
abdullah-bl deleted the feat/query-workers-default branch November 16, 2026 03:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants