deepbase-sqlite 3.6.0 → 3.6.4

package/README.md

@@ -5,9 +5,14 @@ SQLite driver for DeepBase.
 ## Installation
 
 ```bash
-npm install deepbase deepbase-sqlite
+npm install deepbase deepbase-sqlite --ignore-scripts=false
 ```
 
+> `deepbase-sqlite` depends on `better-sqlite3`, a native module. Its install
+> script downloads a prebuilt binary (or compiles from source as a fallback).
+> If your environment disables npm lifecycle scripts, see
+> [Troubleshooting](#troubleshooting) below.
+
 ## Description
 
 Stores data in SQLite database files. Perfect for:
@@ -143,12 +148,12 @@ CREATE TABLE deepbase (
 Example data:
 
 ```
-key                    | value
------------------------|------------------
-users.alice.name       | "Alice"
-users.alice.age        | 30
-users.bob.name         | "Bob"
-users.bob.age          | 25
+key                   | value
+----------------------|------------------
+users.alice.name      | "Alice"
+users.alice.age       | 30
+users.bob.name        | "Bob"
+users.bob.age         | 25
 config.theme           | "dark"
 config.lang            | "en"
 ```
@@ -264,6 +269,52 @@ await db.set('users', userId, 'profile', data);
 await db.set(`user_${userId}_profile`, data);
 ```
 
+## Troubleshooting
+
+### `Could not locate the bindings file` / `better_sqlite3.node` missing
+
+This error means `better-sqlite3`'s native binding was never fetched or built.
+It almost always comes from npm install scripts being disabled, which prevents
+`better-sqlite3`'s `install` script from downloading the prebuilt binary.
+
+Check whether scripts are disabled:
+
+```bash
+npm config get ignore-scripts   # should be "false"
+cat ~/.npmrc 2>/dev/null        # look for `ignore-scripts=true`
+cat .npmrc 2>/dev/null
+```
+
+Fix — rebuild the native binding in the project that uses `deepbase-sqlite`:
+
+```bash
+npm rebuild better-sqlite3 --ignore-scripts=false
+```
+
+If `npm rebuild` still doesn't fetch a prebuild (common when `ignore-scripts`
+is persisted in `.npmrc`), do a clean reinstall of just that package:
+
+```bash
+rm -rf node_modules/better-sqlite3
+npm i --ignore-scripts=false
+```
+
+Verify the binding landed:
+
+```bash
+ls node_modules/better-sqlite3/build/Release/better_sqlite3.node
+```
+
+Notes:
+
+- `npm i <pkg> --ignore-scripts=false` only runs scripts if the install
+  actually changes `node_modules`. When npm reports `up to date`, no install
+  scripts run — use `npm rebuild` or remove the package folder first.
+- In monorepos or CI, prefer setting `ignore-scripts=false` for the install
+  step rather than passing it as a one-off flag.
+- When this happens at runtime, `deepbase-sqlite` will throw an error with
+  code `DEEPBASE_SQLITE_BINDING_MISSING` and a pointer back to this section.
+
 ## License
 
 MIT - Copyright (c) Martin Clasen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-sqlite",
-  "version": "3.6.0",
+  "version": "3.6.4",
   "description": "⚡ DeepBase SQLite - SQLite database driver",
   "type": "module",
   "main": "src/index.cjs",
@@ -17,7 +17,7 @@
     "better-sqlite3": "^11.8.1"
   },
   "peerDependencies": {
-    "deepbase": "^3.6.0"
+    "deepbase": "^3.6.4"
   },
   "scripts": {
     "test": "mocha test/test.js"

package/src/SqliteDriver.js

@@ -59,7 +59,23 @@ export class SqliteDriver extends DeepBaseDriver {
       fs.mkdirSync(this.path, { recursive: true });
     }
 
-    this.db = new Database(this.fileName);
+    try {
+      this.db = new Database(this.fileName);
+    } catch (err) {
+      if (this._isMissingNativeBinding(err)) {
+        const hint =
+          'deepbase-sqlite: the native binding for "better-sqlite3" is missing. ' +
+          'This usually means npm install scripts were disabled (e.g. `ignore-scripts=true` in your .npmrc). ' +
+          'Fix it with: `npm rebuild better-sqlite3 --ignore-scripts=false`, ' +
+          'or reinstall with `npm i --ignore-scripts=false`. ' +
+          'See https://github.com/clasen/DeepBase/tree/main/packages/driver-sqlite#troubleshooting';
+        const wrapped = new Error(hint);
+        wrapped.cause = err;
+        wrapped.code = 'DEEPBASE_SQLITE_BINDING_MISSING';
+        throw wrapped;
+      }
+      throw err;
+    }
 
     const cfg = PRAGMA[this.pragma];
     if (cfg) {
@@ -257,6 +273,16 @@ export class SqliteDriver extends DeepBaseDriver {
     return result;
   }
 
+  _isMissingNativeBinding(err) {
+    if (!err) return false;
+    const msg = String(err.message || '');
+    return (
+      err.code === 'MODULE_NOT_FOUND' ||
+      msg.includes('Could not locate the bindings file') ||
+      msg.includes('better_sqlite3.node')
+    );
+  }
+
   _escapeLikePattern(str) {
     return str.replace(/[!%_]/g, '!$&');
   }