Support alternative SQLite backends (node:sqlite) to avoid native addon SIGSEGV crashes

[Alexey-Goru1ev]

Problem

context-mode crashes intermittently with SIGSEGV (Signal 11) when running on Node.js v22/v24 on Linux due to a V8 runtime bug that corrupts better-sqlite3's native addon .got.plt section.

Root cause

V8's garbage collector calls madvise(MADV_DONTNEED) on memory ranges that can overlap better_sqlite3.node's writable ELF segments (.got.plt). This discards resolved symbol addresses on Copy-on-Write pages, restoring unrelocated on-disk offsets — causing function calls to jump to near-null addresses.

Upstream issue: nodejs/node#62515 — "Sporadic SIGSEGV: native addon .got.plt reset to unrelocated file offsets"

Why context-mode is especially affected

• Runs as an MCP server over stdio pipes (the documented trigger condition)
• Makes frequent better-sqlite3 calls for FTS5 indexing and search
• High call frequency under sustained I/O maximizes exposure to the race condition

Crash frequency

Node Version	Crash Frequency	Tested On
v24.14.x	~4 crashes/hour	Ubuntu 24.04, Linux 6.19.10, AMD x86-64
v22.22.x	~1 crash/2 hours	Same environment

All coredumps show the same pattern: frame #0 at near-null address (0x12xxx range), consistent with .got.plt corruption.

What doesn't help

Attempted Fix	Result
Downgrade Node v24 → v22	Reduced frequency ~10x, did not eliminate
Upgrade better-sqlite3 to v12.8.0 (V8 HolderV2 fix)	No effect — crash persists
LD_BIND_NOW=1 (eager symbol resolution)	Partial — changes memory layout only
LD_PRELOAD madvise guard (intercept+block on .node segments)	Effective but fragile — requires compiled C library, supervisor wrapper, auto-heal hook

The only reliable fix is eliminating the separate .node binary that gets dlopen()'d as a standalone ELF file.

Proposal: Support pluggable SQLite backends

The codebase already has the right abstraction for this:

1. BunSQLiteAdapter (db-base.ts:40-104) already bridges bun:sqlite → better-sqlite3 API
2. loadDatabase() (db-base.ts:117-138) already has runtime detection (Bun vs Node)
3. SQLiteBase provides a clean abstract base that doesn't depend on better-sqlite3 directly
4. better-sqlite3 is already declared as an optionalDependency, not a hard requirement

Suggested approach

Add a node:sqlite adapter (similar to BunSQLiteAdapter) for Node.js >= 22.5:

loadDatabase() priority:
  1. Bun runtime    → bun:sqlite    (existing BunSQLiteAdapter)
  2. Node >= 22.5   → node:sqlite   (new NodeSQLiteAdapter)  ← NEW
  3. Node < 22.5    → better-sqlite3 (existing, fallback)

node:sqlite is built into the Node.js binary — no separate .node file, no dlopen(), no .got.plt to corrupt. It supports the same synchronous API pattern that context-mode uses.

Alternatively: user-configurable backend

Allow users to specify their preferred backend via environment variable or plugin config:

CONTEXT_MODE_SQLITE_BACKEND=node   # use node:sqlite
CONTEXT_MODE_SQLITE_BACKEND=bun    # use bun:sqlite
CONTEXT_MODE_SQLITE_BACKEND=native # use better-sqlite3 (default)

API compatibility notes

The following better-sqlite3 APIs are used by context-mode and would need adapter coverage:

API	Used For	node:sqlite equivalent
prepare(sql)	Statement caching	db.prepare(sql)
stmt.run/get/all()	CRUD operations	Same API names
exec(sql)	Schema DDL	db.exec(sql)
pragma(str)	WAL, checkpoints	db.exec('PRAGMA ...')
transaction(fn)	Atomic writes	Manual BEGIN/COMMIT wrapper
FTS5 MATCH, bm25(), highlight()	Full-text search	Same (SQLite feature, not library feature)

FTS5 is a SQLite extension, not a better-sqlite3 feature — it works with any SQLite binding that ships a complete SQLite build.

Environment

• OS: Ubuntu 24.04, Linux 6.19.10
• Arch: AMD x86-64
• Node: v22.22.2 / v24.14.1 (via nvm)
• context-mode: v1.0.74
• better-sqlite3: v12.8.0
• RAM: 13 GiB (4 GB swap used — increases V8 GC pressure → more madvise collisions)

References

• nodejs/node#62515 — upstream bug report
• Node.js node:sqlite docs — built-in SQLite module
• better-sqlite3 #1271 — related native addon stability discussion

[Alexey-Goru1ev]

Additional option: local PostgreSQL

The better-sqlite3 maintainers themselves document cases where SQLite may not be appropriate and suggest PostgreSQL as an alternative for workloads with high concurrent writes or large data volumes.

context-mode's use case — sustained high-frequency writes from FTS5 indexing under continuous MCP stdio I/O — aligns with this guidance. A local PostgreSQL backend would:

• Eliminate the native addon entirely — no .node binary, no .got.plt, no SIGSEGV risk
• Handle concurrent access natively — no WAL mode tuning, no SQLITE_BUSY retries needed
• Scale better for large knowledge bases — PostgreSQL's tsvector/tsquery full-text search is mature and well-optimized
• Already available on most dev machines (Docker, system package, or managed service)

FTS mapping

SQLite FTS5	PostgreSQL equivalent
MATCH query	@@ operator with to_tsquery()
bm25() ranking	ts_rank() / ts_rank_cd()
highlight()	ts_headline()
Porter tokenizer	Built-in english dictionary
Trigram tokenizer	pg_trgm extension (CREATE EXTENSION pg_trgm)

Tradeoff

The main downside is the external dependency — SQLite's zero-config appeal is real. But for users already running PostgreSQL locally (common for developers), this could be a configuration option alongside the SQLite backends:

CONTEXT_MODE_DB_BACKEND=postgres  # PostgreSQL via pg/postgres.js
CONTEXT_MODE_DB_BACKEND=node      # node:sqlite (built-in)
CONTEXT_MODE_DB_BACKEND=bun       # bun:sqlite (Bun runtime)
CONTEXT_MODE_DB_BACKEND=native    # better-sqlite3 (current default)

This wouldn't replace SQLite as the default — just offer an opt-in alternative for users hitting stability or scale limits.

[murataslan1]

Two things came to mind while reading this:

libsql might be worth looking at alongside node:sqlite. @libsql/client runs embedded without a native addon — it's a SQLite fork so FTS5 works out of the box. And the same adapter could optionally point at a remote Turso instance, which gives you local-first with optional cloud sync through one interface. The priority chain could be something like bun:sqlite → node:sqlite → libsql → better-sqlite3.

The other thought — if heading toward 4+ backends, hardcoding each adapter separately gets messy. Might make more sense to define a StorageAdapter interface and let people plug in whatever they want. The existing BunSQLiteAdapter is already pretty close to what that interface would look like. Something like context-mode --storage=my-adapter or the env var approach from the original proposal.

sql.js (WASM compiled SQLite) crossed my mind too as a zero-native-binary option, but for FTS5-heavy workloads like ours I'm not sure the performance trade-off is worth it outside of maybe a last-resort fallback.