Skip to content

fix(deps): bump better-sqlite3 to v12 for Node 24 support (v1.54.1) - #184

Merged
paulkr merged 1 commit into
mainfrom
feature/int-4407-bump-better-sqlite3-to-v12-for-node-24-support
Aug 11, 2026
Merged

fix(deps): bump better-sqlite3 to v12 for Node 24 support (v1.54.1)#184
paulkr merged 1 commit into
mainfrom
feature/int-4407-bump-better-sqlite3-to-v12-for-node-24-support

Conversation

@siddharth-bhansali

Copy link
Copy Markdown
Collaborator

INT-4407

Problem

one sync is silently broken for anyone on Node 24 without a C++ toolchain — which is the default experience for a new user, since Node 24 is what you get installing Node today.

better-sqlite3@11 publishes prebuilt binaries only up to NODE_MODULE_VERSION 131 (Node 23):

v11.10.0 win32-x64:  node-v108  node-v115  node-v127  node-v131          ← no v137
v12.11.1 win32-x64:  node-v127  node-v137  node-v141  node-v147          ← Node 24 covered

Node 24 is 137, so prebuild-install falls back to node-gyp rebuild — compiling from source, which needs Visual Studio Build Tools on Windows. And because it's an optionalDependency, npm doesn't error, it silently skips it. The install succeeds, the CLI works, and one sync is dead with no warning.

Blast radius

Narrower than it sounds, but it hits the marquee feature. SQLite is only opened when a profile declares enrich (runner.ts:172, needsSqlite = !!profile.enrich) — 2 of the 9 built-in profiles:

  • Broken: gmail, fathom — i.e. exactly the profiles the cross-platform identity-key work is built around. Plus sync delete, sync remove, and mem migrate (which is the tool for getting people off SQLite).
  • Unaffected: attio ×2, google-calendar, hacker-news, notion, stripe ×2 — these never touch SQLite.

Verification

On this machine (Windows, Node 24.14.0):

  • npm ci installs 12.11.1 clean — no compilation.
  • pragma() and FTS5 both work; tsc --noEmit passes against the existing @types/better-sqlite3@^7.
  • Full suite: 13 skipped → 0 skipped, 443/443 passing.

That last point matters beyond this PR. enrich-preserve.test.ts skips itself when the driver is missing, so it had been quietly not running here — which is exactly how the --no-memory regression in #180 reached CI instead of my machine. This restores local coverage of the enrich path.

Cost

v12 requires Node 20+, so one sync no longer works on Node 18. In practice it already didn't — v11 can't build there on a current toolchain either — but the README now states it explicitly rather than implying "Node 18+" covers everything. Every other command is unaffected on 18.

Worth knowing for review

CI cannot catch this class of bug. GitHub runners ship with compilers, so they build from source successfully and go green regardless of whether a prebuild exists. Adding Node 24 to the matrix would not have found this, and won't protect against the next occurrence — the protection is keeping the dependency current.

Lockfile. This needed a real regeneration, not a version-field edit. npm install --package-lock-only dropped node_modules/pg (an optional dep that can't install here), so I restored that entry by hand and validated the result with a clean npm ci. Documented the trap in CLAUDE.md so the next person doesn't ship a lockfile with pg missing.

Not bumped: @types/better-sqlite3 stays at ^7.6.13 (latest is 9.6.0). It typechecks clean against v12 and bumping it is unrelated risk — happy to split that out if you'd rather they moved together.

🤖 Generated with Claude Code

v11 publishes prebuilt binaries only up to NODE_MODULE_VERSION 131 (Node 23).
Node 24 is 137, so npm falls back to compiling from source, which needs
Visual Studio Build Tools on Windows or a compiler toolchain elsewhere. And
because better-sqlite3 is an optionalDependency, npm does not error — it
silently skips it. The install "succeeds", the CLI works, and `one sync` is
dead with no warning anywhere. Node 24 is what a new user gets today.

What was broken: gmail and fathom sync (the only two built-in profiles that
declare enrich, and so the only ones that open SQLite), plus `sync delete`,
`sync remove`, and `mem migrate`. Attio/Stripe/Notion/Calendar/HN sync never
touch SQLite and were unaffected.

v12.11.1 ships win32-x64 prebuilds for node-v127/137/141/147, so nothing
compiles. Verified on this machine: npm ci installs it clean under Node 24,
FTS5 and pragma() both work, and the full suite goes from 13 skipped to
**0 skipped, 443/443 passing** — the enrich-preserve suite had been silently
skipping itself here, which is how the --no-memory regression in #180 reached
CI instead of a local run.

Cost: v12 requires Node 20+, so `one sync` no longer works on Node 18. In
practice it already didn't — v11 can't build there on a current toolchain
either — but the README now says so explicitly rather than implying 18 is
fine for everything.

Note CI cannot catch this class of bug: GitHub runners ship compilers, so
they build from source successfully and go green regardless. Adding Node 24
to the matrix would not have found it.

Also documents the package-lock.json pruning trap in CLAUDE.md — `npm install`
here drops the `pg` entry, which had to be restored by hand after
regenerating the lockfile for this change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@linear

linear Bot commented Aug 11, 2026

Copy link
Copy Markdown

INT-4407

@paulkr
paulkr merged commit 1a915f1 into main Aug 11, 2026
7 checks passed
@paulkr
paulkr deleted the feature/int-4407-bump-better-sqlite3-to-v12-for-node-24-support branch August 11, 2026 15:24
paulkr pushed a commit that referenced this pull request Aug 13, 2026
…184)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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