Merged via /merge-batch (2026-10-17, round 4). Validated as submitted on a combined board of 33 PRs over the current release/v3.8.52 tip: typecheck:core, open-sse and API-route typechecks, eslint on changed files, file-size, complexity, cognitive-complexity, dead-code, boundary 774/774, changelog-integrity, env-doc-sync, docs-sync, agent-skills-sync (Generated 0), provider-consistency and i18n new-key coverage all green; focused tests 401/406 node:test + 11/11 vitest (the only reds were the #16988 fixture, fixed separately). Remaining CI reds are the inherited base-red #15306. Thanks @insoln for the contribution!
5.1 KiB
title
| title |
|---|
| SQLite Runtime Resolution |
SQLite Runtime Resolution
OmniRoute resolves its SQLite driver at startup through a 5-step fallback chain:
-
Bundled
better-sqlite3(viadependenciesinpackage.json) — fastest, native binary, installed bynpm installwhen build tools are present. -
Runtime-installed
better-sqlite3(in~/.omniroute/runtime/) — installed lazily on first run OR byscripts/build/postinstall.mjs → scripts/postinstall.mjs. Validates native.nodemagic bytes (ELF / Mach-O / PE) before loading to guard against corrupt or wrong-platform binaries. -
node:sqlite(Node ≥22.5 stdlib) — no native build needed; used when both better-sqlite3 paths fail. Limited feature set. -
sql.js(WASM) — final fallback. Works everywhere but is slower and writes data on an interval rather than synchronously.
Why this complexity?
- Windows EBUSY:
npm install -g omniroute@latestcan fail if the previous version'sbetter_sqlite3.nodeis locked by a running process. The runtime install in~/.omniroute/runtime/sidesteps the global npm cache. - No build tools: Some environments (corporate Windows without VS Build
Tools, minimal Docker images) cannot compile
better-sqlite3. The runtime installer resolves a pre-built binary from the npm registry; the fallback drivers ensure OmniRoute still boots even if that fails. - Air-gapped systems: If the npm registry is unreachable,
node:sqliteorsql.jsguarantee baseline functionality.
Magic-byte validation
Before loading a runtime-installed .node file, OmniRoute reads the first 8
bytes and matches against known platform magics:
| Platform | Bytes (hex) | Label |
|---|---|---|
| Linux | 7F 45 4C 46 |
elf |
| macOS 64-bit BE | FE ED FA CF |
macho |
| macOS 64-bit LE | CF FA ED FE |
macho-le |
| macOS fat (universal) | CA FE BA BE |
macho-fat |
| Windows | 4D 5A (MZ) |
pe |
A mismatched magic → file is ignored, fallback continues to the next step.
Checking the active driver
import { getDriverInfo } from "@/lib/db/core";
const info = getDriverInfo();
// { source: "bundled" | "runtime" | "runtime-installed-now" | "node-sqlite" | "sql-js",
// kind: "better-sqlite3" | "node-sqlite" | "sql-js" }
Manual control
# Skip postinstall warm-up (for fast CI installs)
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute
# Force-reinstall runtime better-sqlite3
rm -rf ~/.omniroute/runtime
omniroute # will reinstall on next start
# Check what driver is active
omniroute config db-info # (if CLI command exists)
Diagnosing synchronous stalls
With better-sqlite3, set OMNIROUTE_SQLITE_SLOW_MS=200 before startup to opt
into synchronous adapter timing. The default is off. A completed operation taking
at least that many milliseconds emits a [SQLITE-SLOW] warning, at most once per
ten seconds per adapter. The warning contains only the driver, operation class
(prepare, get, all, run, exec, pragma, transaction or maintenance), and
elapsed milliseconds: no SQL, bindings, rows, paths or exception text.
This is a diagnostic aid, not a timeout or query optimization. It cannot report an operation that never returns, distinguish CPU work from disk waits, identify the exact SQL, or observe operations performed through the raw driver handle. Async backup duration is deliberately excluded; other SQLite drivers are not instrumented by this opt-in. Disabling the variable restores the original adapter without timing wrappers. No database schema or stored configuration changes.
The /healthz lag warning reports the event-loop peak since the previous sample,
not the lifetime average. Correlate its timestamps with slow-operation warnings
and host/storage metrics before attributing a stall to SQLite or disk failure.
Reference
Implementation:
bin/cli/runtime/magicBytes.mjs— binary magic-byte validation helpersbin/cli/runtime/sqliteRuntime.mjs— 5-step runtime resolver + lazy installerbin/cli/runtime/index.mjs— startup orchestrator (warmUpRuntimes())scripts/postinstall.mjs— npm post-install hook (non-fatal warm-up)src/lib/db/core.ts—ensureDbInitialized()/getDriverInfo()exports
Single-writer topology (HA unsupported)
The driver fallback chain above still runs in one process. Default SQLite OmniRoute is a single writer:
- Do not attach two OmniRoute replicas to the same
storage.sqlitefile. - A container restart, Recreate deploy, OOM kill, or HEALTHCHECK restart drops every in-flight SSE session. There is no session drain on the stock path.
- Orchestrator liveness that treats a slow
/healthzas dead will kill the only replica. Prefer TCP liveness + HTTP/healthzreadiness. See Docker Guide — availability and Kubernetes probe recommendations.