Two majors of sqlite3, and the upstream is unmaintained

[macterra]

Six manifests depend on sqlite3, split across two major versions. Nobody chose the split, and the package has since declared itself unmaintained — so this is worth settling deliberately rather than letting a bot finish it.

The split, and why it exists

Added	Package	Version
2024-09	packages/gatekeeper	^5.1.7
2025-01	packages/keymaster	^5.1.7
2025-02	services/mediators/satoshi	^5.1.7
2026-05-15	services/mediators/zcash	^5.1.7 → later ^6.0.1
2026-05-21	services/mediators/ethereum	^6.0.1
2026-05-21	services/mediators/solana	^6.0.1

sqlite3@5.1.7 was published 2024-01-05 and 6.0.1 on 2026-03-12. Everything written before March took 5.1.7 because that is what npm install sqlite3 had given for two years; everything written after took 6.0.1. The split is nothing but the date each service was created, either side of an upstream major.

zcash is the exception that confirms it: added at ^5.1.7 on 15 May, moved to ^6.0.1 within a fortnight by dependabot in a bump the npm_and_yarn group across N directories PR. The bot took one straggler and left the other three, presumably because they carried no advisory to trigger on.

So there is no design intent to recover here.

Why it is not merely untidy

The prebuild seeding in scripts/prefetch-prebuilds.mjs resolves a version and downloads an asset whose filename contains it. Until #961 it read only the root lockfile, so it seeded 5.1.7 and silently missed the three services on 6.0.1 — they fell back to prebuild-install's un-retried network fetch, which is the failure #879 was written to remove.

That failure is invisible: the build still succeeds, just over the network. It surfaced only because removing a forced source build made someone check which prebuild was actually being used. #961 makes the script seed every installed version, which is correct defensively — but it is scaffolding around a split that should not exist.

The wrinkle that changes the question

node-sqlite3 marked itself unmaintained at v6.0.0. From the release notes:

Mark repository as unmaintained (#1844)

So "align on 6.0.1" means standardising on an abandoned package. The two majors are otherwise near-identical — same dependency list, same API, and the only real change in 6.0.0 is engines: node >=20.17.0, which this repo satisfies at 22.23.2.

Options

Align on 6.0.1. Cheapest. Three manifests move, the seeding special-case becomes redundant, and the repo standardises on a package nobody maintains.

Move to node:sqlite. Built into the Node 22 this repo already runs — confirmed available, currently flagged experimental. It would remove a native module from six services entirely: no prebuilds, no prebuild-install, no python3 make g++ in those Dockerfiles, and no emulated source builds when publishing for arm64. Larger change, and the experimental flag is a real consideration for a database.

Move to better-sqlite3. Maintained, synchronous API, still a native module — so the prebuild machinery stays.

Scope

The usage is contained, which makes any of these tractable: one file per package.

packages/gatekeeper/src/db/sqlite.ts
packages/keymaster/src/db/sqlite.ts
services/mediators/{satoshi,zcash,ethereum,solana}/src/db/sqlite.ts

Two of those are published npm packages — @didcid/gatekeeper and @didcid/keymaster — so whichever way this goes, it changes a dependency for anyone installing them, and belongs in a release rather than a cleanup.

[macterra]

node:sqlite tested against the real suite

The open question above was whether node:sqlite could actually carry this workload, with the experimental flag listed as the concern. Compatibility, at least, is now settled empirically rather than argued.

I ran the repo's own sqlite suite against node:sqlite without changing any adapter, by pointing jest's moduleNameMapper at a shim standing in for the sqlite/sqlite3 pair.

426/426 gatekeeper tests pass, including all 30 in tests/gatekeeper/db-sqlite.test.ts — the concurrency serialization tests, the BEGIN IMMEDIATE/ROLLBACK path, and the legacy TEXT-affinity coercion in normalizeBlock.

The shim is 25 lines:

class Db {
    constructor(private readonly handle: DatabaseSync) {}
    async exec(sql: string): Promise<void> { this.handle.exec(sql); }
    async run(sql: string, ...params: any[]) {
        const r = this.handle.prepare(sql).run(...params);
        return { changes: Number(r.changes), lastID: Number(r.lastInsertRowid) };
    }
    async get<T>(sql: string, ...params: any[]) {
        const row = this.handle.prepare(sql).get(...params);
        return row === undefined ? undefined : ({ ...row } as T);
    }
    async all<T>(sql: string, ...params: any[]) {
        return this.handle.prepare(sql).all(...params).map(r => ({ ...r })) as T[];
    }
    async close(): Promise<void> { this.handle.close(); }
}

Everything the adapters rely on is present: multi-statement exec (the blocks table and its index arrive in one call), changes as a plain number rather than a BigInt, and get() returning undefined on a miss. The only adaptations needed were lastInsertRowid → lastID and spreading rows out of null-prototype objects.

The surface is as contained as the scope section suggests. The only sqlite3 reference in the codebase is sqlite3.Database passed as the driver argument in five adapters, and no call site uses named parameters — so a migration is five files plus dropping the dependency.

The actual blocker is synchronous writes, not the experimental flag

DatabaseSync blocks the event loop; sqlite3 hands work to a threadpool. That is the one behavioural difference that matters, and it cuts both ways.

Reads are not close. 2000 point reads, like-for-like (both re-preparing each call, as the shim does):

	2000 reads
sqlite3	436ms
node:sqlite (prepare per call)	25ms
node:sqlite (cached statement)	15ms

Writes are the risk. 500 single-row writes took 30s on sqlite3 and 27s on node:sqlite — no meaningful driver difference, because that time is fsync, not the binding. But 60ms of synchronous write would stall the whole gatekeeper process rather than one request, where today it occupies a threadpool thread. That number is WSL's disk and says nothing about production, so it is the measurement worth taking on real hardware before committing — it, and not API compatibility, is what decides this.

Second consequence: node:sqlite needs Node ≥22.5, above the >=20.17.0 floor that sqlite3@6 implies. For two published packages that is a real narrowing. It still emits an ExperimentalWarning on 22.15.

Alignment

Separately, I have the "align on 6.0.1" option working locally: three manifests moved, every tracked lockfile now resolves a single version, and 1679 tests pass against a real install of 6.0.1 (the first run did not count — regenerating lockfiles left 5.1.7 in node_modules, so the suite was still exercising the old driver).

Two notes on that path:

• @didcid/gatekeeper and @didcid/keymaster declared no engines, so 6.0.0's node >=20.17.0 floor would have reached consumers as a confusing native-build failure instead of a clear npm error. Worth declaring explicitly alongside the bump.
• The prebuild-seeding guard asserting sqlite3 has more than one version becomes false. Inverting it to assert exactly one turns the decision into something enforced — and it catches the precise mechanism that caused this, a bot moving one manifest and leaving the rest.

Alignment does not close this issue. It removes the accidental split and buys time; standardising on an unmaintained package is still the thing to decide.

[macterra]

The repo has a second sqlite driver, and it has the same unseeded-prebuild defect

Looking at whether sqlite support could be dropped entirely turned up something the table above misses: Herald selects sqlite too, but on a different driver.

services/herald/server/package.json:  "better-sqlite3": "^11.10.0"

So this is not "two majors of one driver" — it is two different sqlite drivers across seven manifests. That reshapes the options: aligning on sqlite3@6.0.1 leaves Herald untouched, and moving to node:sqlite means converting Herald as well or keeping a native module for one service regardless.

The live part

better-sqlite3 installs the same way the others do:

scripts.install = 'prebuild-install || node-gyp rebuild --release'

But it is not seeded. scripts/prefetch-prebuilds.mjs covers sqlite3 and @ipshipyard/node-datachannel only, and services/herald/Dockerfile sets:

ENV npm_config_sqlite3_local_prebuilds=/prebuilds \
    npm_config_ipshipyard_node_datachannel_local_prebuilds=/prebuilds

npm_config_better_sqlite3_local_prebuilds is absent, and the Dockerfile's second install — cd herald/server && npm ci — is where better-sqlite3 actually arrives. So every Herald build fetches that binary over the network with a single request and no retry: precisely the failure #879 was written to remove, and precisely the failure #961 just fixed for sqlite3.

It is arguably worse here than in the sqlite3 case. services/herald/Dockerfile is node:22.23.2-trixie-slim with no apt-get at all, so there is no toolchain for the || node-gyp rebuild fallback to use. When the fetch fails, the build does not degrade to a slow source compile — it fails outright.

This is invisible today for the same reason the original was: the fetch normally succeeds, so the image publishes and nothing looks wrong.

Fixing the seeding is not a one-line addition

better-sqlite3 names its assets by Node ABI, not N-API version:

better-sqlite3-v11.10.0-node-v127-linux-x64.tar.gz
better-sqlite3-v11.10.0-node-v127-linux-arm64.tar.gz

node-v127 is Node 22's ABI, where the existing entries resolve a napi number:

{ name: 'sqlite3', repo: 'TryGhost/node-sqlite3', napi: 6 },

So the script needs to express both naming schemes, and services/herald/Dockerfile needs the matching npm_config_better_sqlite3_local_prebuilds — which, note, must be set before the second npm ci, not just the first.

The generalisable fix is for tests/ci/prebuild-seeding.test.ts to stop enumerating known packages and instead assert that every dependency whose install script invokes prebuild-install is seeded and has a matching local_prebuilds env var in the Dockerfiles that install it. That guard would have caught this one on the day Herald was added, and will catch the next one. Filed as a follow-up rather than folded in here, since it stands on its own regardless of which sqlite direction this issue takes.

Bearing on the options

Also relevant to "remove sqlite support entirely", which is worth adding to the list above: no deployment uses sqlite. Every service defaults to json, and sqlite appears in no compose file and no CI workflow — which is why the seeding gap could sit unnoticed. Removal would delete seven dependency entries, six adapters, both prebuild special-cases and this defect with them.

The costs are real though: @didcid/gatekeeper/db/sqlite and @didcid/keymaster/wallet/sqlite are documented subpath exports, so removal is semver-major for consumers; packages/mcp-server offers only json | sqlite, leaving it single-option; and it would end the only embedded backend with transactions and crash safety, since json rewrites the whole file per save. That is a product decision about whether durable local storage is offered at all — worth making deliberately rather than inheriting from a dependency problem.