feat: migrate SQLite connector to built-in node:sqlite (#317) (#330)

* feat: migrate SQLite connector to built-in node:sqlite (#317)

Replace better-sqlite3 with Node's built-in node:sqlite module, eliminating
native C++ compilation (node-gyp) and prebuild friction. SQLite now needs no
driver package and is always available.

API mapping:
- new Database(path, {readonly}) -> new DatabaseSync(path, {readOnly})
- db.defaultSafeIntegers(true)   -> stmt.setReadBigInts(true) (per-statement,
                                    centralized in a private prepare() helper)
- db.inTransaction               -> db.isTransaction

Behavior preserved vs better-sqlite3:
- run() returns BigInt `changes` with setReadBigInts; normalized via Number()
- foreign keys default off (enableForeignKeyConstraints: false)

Build/runtime gotchas fixed:
- tsup removeNodeProtocol stripped `node:sqlite` -> `sqlite` (unresolvable);
  set removeNodeProtocol: false
- node:sqlite emits ExperimentalWarning at load time; install a targeted
  warning filter (suppress-experimental-warning.ts) before loading node:sqlite,
  and load it via a non-hoisted lazy dynamic import() inside connect()

Other:
- drop better-sqlite3 / @types/better-sqlite3; bump engines.node to >=22.5.0
- CI run-tests Node 20 -> 22; update install/quickstart docs
- remove better-sqlite3 native-build approvals from pnpm-workspace.yaml

BREAKING CHANGE: requires Node.js >= 22.5.0

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

* refactor: consolidate SQLite introspection queries behind typed helpers

Schema introspection reads small integer flags (notnull, pk, unique) that
must be plain numbers for `=== 1` / `> 0` comparisons to work, while
executeSQL needs BigInt to preserve 64-bit user-data precision. The migration
left this split implicit and inconsistent: some methods used this.prepare()
(BigInt) and others this.db.prepare() (number), and getTableSchema was on the
wrong side — its `notnull === 1` check silently failed against BigInt.

- Add private queryAll<T>/queryOne<T> helpers for introspection (plain numbers,
  centralizing the repeated `as unknown as X` casts and the not-connected guard)
- Route all introspection (getTables, getViews, tableExists, getTableIndexes,
  getTableSchema) through them; getTableSchema now compares plain numbers
- Keep prepare() (BigInt) for executeSQL only, with a clarified doc comment

No behavior change for covered cases; corrects the latent NOT NULL detection
for non-PK columns in getTableSchema. All SQLite tests pass.

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

* docs: state Node.js >= 22.5.0 requirement for the npm method

The engine floor now applies to running DBHub via npm/npx (node:sqlite),
not just SQLite. Note it in the README quick-start and dev sections, and add
a callout in installation.mdx clarifying Docker users don't need local Node.

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

* refactor: install node:sqlite warning hook lazily, not at startup

The experimental-warning suppression was a top-level side-effect import, so
loadConnectors patched process.emitWarning globally at every startup — even
for instances that never use SQLite. Now that node:sqlite is loaded lazily
inside connect(), the hook can be too: convert the suppress module to an
idempotent function and call it right before the dynamic import. Non-SQLite
processes no longer touch process.emitWarning.

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tianzhou

.github/workflows/run-tests.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'pnpm'
 
       - name: Get pnpm store directory
@@ -71,7 +71,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'pnpm'
 
       - name: Get pnpm store directory

README.md

@@ -74,7 +74,7 @@ docker run --rm --init \
    --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
 ```
 
-**NPM:**
+**NPM:** (requires Node.js >= 22.5.0)
 
 ```bash
 npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
@@ -104,6 +104,8 @@ See [Multi-Database Configuration](https://dbhub.ai/config/toml) for complete se
 
 ## Development
 
+Requires Node.js >= 22.5.0 (DBHub uses the built-in `node:sqlite` module).
+
 ```bash
 # Install dependencies
 pnpm install

docs/installation.mdx

@@ -4,6 +4,10 @@ title: "Installation"
 
 ## npm
 
+<Note>
+The npm method requires **Node.js >= 22.5.0** (DBHub uses Node's built-in `node:sqlite` module). The Docker image bundles a compatible Node runtime, so no local Node install is needed when running via Docker.
+</Note>
+
 <Tabs>
   <Tab title="npx">
     ```bash
@@ -51,10 +55,11 @@ Available driver packages:
 - `mysql2` — MySQL
 - `mariadb` — MariaDB
 - `mssql` — SQL Server
-- `better-sqlite3` — SQLite
+
+SQLite uses the built-in `node:sqlite` module (Node.js 22.5+), so it requires no driver package or native compilation and is always available.
 
 <Note>
-When a driver is not installed or a required dependency is missing (e.g., a transitive dependency like `@azure/core-client` for the SQL Server driver), DBHub will skip that connector at startup and log a message. All other connectors will work normally. Note that `--demo` mode requires the `better-sqlite3` driver.
+When a driver is not installed or a required dependency is missing (e.g., a transitive dependency like `@azure/core-client` for the SQL Server driver), DBHub will skip that connector at startup and log a message. All other connectors will work normally. SQLite (including `--demo` mode) needs no extra driver — it relies on the built-in `node:sqlite` module.
 </Note>
 
 ## Docker

docs/quickstart.mdx

@@ -7,7 +7,7 @@ This guide will walk you through setting up DBHub and connecting it to an AI too
 ## Prerequisites
 
 Before starting, ensure you have:
-- Node.js 20+ installed (for NPM method) **OR** Docker installed
+- Node.js 22.5+ installed (for NPM method) **OR** Docker installed
 - Access to an AI tool (Claude Desktop, Claude Code, Cursor, or VS Code)
 - Optionally: A PostgreSQL, MySQL, or other supported database
 

package.json

@@ -34,7 +34,7 @@
     "test:build": "node scripts/smoke-test-build.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.5.0"
   },
   "keywords": [],
   "author": "",
@@ -51,7 +51,6 @@
   "optionalDependencies": {
     "@aws-sdk/rds-signer": "^3.1001.0",
     "@azure/identity": "^4.8.0",
-    "better-sqlite3": "^11.9.0",
     "mariadb": "^3.4.0",
     "mssql": "^11.0.1",
     "mysql2": "^3.13.0",
@@ -62,7 +61,6 @@
     "@testcontainers/mssqlserver": "^11.0.3",
     "@testcontainers/mysql": "^11.0.3",
     "@testcontainers/postgresql": "^11.0.3",
-    "@types/better-sqlite3": "^7.6.12",
     "@types/express": "^4.17.21",
     "@types/mssql": "^9.1.7",
     "@types/node": "^22.13.10",