fix(db): require better-sqlite3 ^12.4.1 so Node 24 gets the native backend (colbymchenry#203) (colbymchenry#216)

colbymchenry · claude · web-flow · commit 9b06b0edde65 · 2026-05-20T11:54:19.000-05:00
better-sqlite3 ^11.0.0 (latest 11.10.0) ships no prebuilt binary for
Node 24's ABI (node-v137) and predates Node 24, so every Node 24 install
silently fell back to the 5-10x-slower WASM backend. Bump to ^12.4.1 —
the first 12.x with the Node 24 prebuild — and raise the engines floor to
Node 20 (Node 18 is EOL and dropped from better-sqlite3 12.x prebuilds).

Verified on macOS Node 24.15.0 (ABI 137): prebuilt binary used with no
compiler (installs even with CC/CXX sabotaged), `codegraph init -i` shows
no WASM banner, and `codegraph status` reports Backend: native. 639/639
tests pass on Node 22.

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -33,6 +33,12 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   setup is actually fast. `codegraph uninit` removes any hooks it installed.
 
 ### Changed
+- **Minimum Node.js is now 20** (was 18). Node 18 is end-of-life and the
+  native SQLite binding (`better-sqlite3` 12.x) no longer ships a Node 18
+  prebuilt binary. Node 22 LTS and Node 24 get the native backend out of the
+  box; on other Node versions CodeGraph still runs via the WASM fallback
+  (slower, but functional). Node 25+ remains blocked (V8 WASM JIT crash, see
+  [#81](https://github.com/colbymchenry/codegraph/issues/81)).
 - **MCP / explore**: `codegraph_explore` output is now adaptive to project
   size. The tool used to apply a fixed 35KB cap regardless of how large the
   codebase was, which on small projects (~100 files) produced bigger
@@ -57,6 +63,20 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   Thanks to [@essopsp](https://github.com/essopsp) for the repro.
 
 ### Fixed
+- **Native SQLite backend on Node 24**: indexing on Node 24 always dropped to
+  the 5-10x-slower WASM backend, printing a `better-sqlite3 unavailable`
+  warning that `npm rebuild better-sqlite3` / `xcode-select --install` could
+  not clear ([#203](https://github.com/colbymchenry/codegraph/issues/203)).
+  The bundled `better-sqlite3` was pinned to a v11 release that ships no
+  prebuilt binary for Node 24's ABI (`node-v137`), so every Node 24 install
+  silently degraded — and because CodeGraph is usually installed globally, the
+  `npm install` / `npm rebuild` people ran in their own project never touched
+  CodeGraph's copy. CodeGraph now requires `better-sqlite3` `^12.4.1`, whose
+  prebuilds include Node 24, so a fresh install on Node 22 or Node 24 gets the
+  native backend with no compiler. On an already-broken install, reinstall
+  CodeGraph (e.g. `npm install -g @colbymchenry/codegraph`) to pull the new
+  binding; `codegraph status` should then report `Backend: native`. Thanks to
+  [@Finndersen](https://github.com/Finndersen) for the report.
 - **MCP**: tools no longer fail with "CodeGraph not initialized" when the index
   actually exists. This hit clients that launch the MCP server from a directory
   other than your project and don't report a workspace root in `initialize`
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -51,9 +51,9 @@
     "vitest": "^2.1.9"
   },
   "optionalDependencies": {
-    "better-sqlite3": "^11.0.0"
+    "better-sqlite3": "^12.4.1"
   },
   "engines": {
-    "node": ">=18.0.0 <25.0.0"
+    "node": ">=20.0.0 <25.0.0"
   }
 }

Original file line number	Diff line number	Diff line change
`@@ -51,9 +51,9 @@`
`51`	`51`	`"vitest": "^2.1.9"`
`52`	`52`	`},`
`53`	`53`	`"optionalDependencies": {`
`54`		`- "better-sqlite3": "^11.0.0"`
	`54`	`+ "better-sqlite3": "^12.4.1"`
`55`	`55`	`},`
`56`	`56`	`"engines": {`
`57`		`- "node": ">=18.0.0 <25.0.0"`
	`57`	`+ "node": ">=20.0.0 <25.0.0"`
`58`	`58`	`}`
`59`	`59`	`}`