deepbase-sqlite 3.6.9 → 3.7.0

package/README.md

@@ -49,6 +49,12 @@ new SqliteDriver({
   path: './data',              // Directory to store database files
   name: 'default',            // Database filename (without .db)
   pragma: 'balanced',         // Performance profile: 'none' | 'safe' | 'balanced' | 'fast'
+  busyTimeoutMs: 5000,        // Native wait per lock attempt
+  busyRetry: {
+    maxAttempts: 2,           // Total transaction attempts
+    baseDelayMs: 25,          // Exponential backoff base
+    maxDelayMs: 250           // Backoff cap
+  },
   nidAlphabet: 'ABC...',      // Alphabet for ID generation
   nidLength: 10               // Length of generated IDs
 })
@@ -64,16 +70,20 @@ Uses `better-sqlite3` for synchronous operations wrapped in async API:
 - Transaction support for batch operations
 - Fast lookups with indexed keys
 
-### Singleton Pattern
+### Multi-process concurrency
 
-Multiple instances pointing to the same database file will share the same connection:
+Multiple instances and same-host processes may safely point to the same database file. Each driver owns its connection and lifecycle; SQLite coordinates writers using WAL, `BEGIN IMMEDIATE`, a busy timeout, and bounded transaction retries:
 
 ```javascript
 const db1 = new DeepBase(new SqliteDriver({ name: 'mydb' }));
 const db2 = new DeepBase(new SqliteDriver({ name: 'mydb' }));
-// Both use the same underlying database connection
+// Independent connections; disconnecting db1 does not close db2.
 ```
 
+SQLite still permits only one writer at a time. Keep write transactions short and use a client-server database when sustained write contention or multiple hosts are required. WAL requires a local filesystem shared by processes on the same host; do not place the database on NFS.
+
+When upgrading from a version that used the in-memory sequence counter, stop all old writer processes before starting the new version. The schema migration is automatic, but old and new sequence allocators must not write concurrently during a rolling deployment.
+
 ### Nested Data Structure
 
 Efficiently stores nested objects using a key-value schema:
@@ -82,7 +92,7 @@ Efficiently stores nested objects using a key-value schema:
 - Values are stored as JSON
 - Fast lookups for both exact keys and partial paths
 
-Each row also stores a monotonic `seq` so reads that rebuild objects use `ORDER BY seq, key`. That matches JavaScript insertion order for sibling keys and keeps `shift()` / `pop()` aligned with `JsonDriver`. The driver now exposes `first()` / `last()` using SQL boundary queries in the same order semantics as `keys()`. Existing databases pick up `seq` via `ALTER TABLE` on connect (legacy rows default to `0`, then tie-break by `key`).
+Each row also stores a monotonic, database-assigned `seq` so reads that rebuild objects use `ORDER BY seq, key`. That matches JavaScript insertion order for sibling keys and keeps `shift()` / `pop()` aligned with `JsonDriver`. Existing databases migrate automatically inside an atomic `BEGIN IMMEDIATE` transaction. Legacy and duplicate sequence values are normalized while preserving their previous `ORDER BY seq, key` order.
 
 ### ACID Compliance
 
@@ -90,7 +100,7 @@ SQLite provides:
 
 - **Atomicity**: All operations complete or none do
 - **Consistency**: Data remains valid across transactions
-- **Isolation**: Concurrent operations don't interfere
+- **Isolation**: Concurrent writes are serialized by SQLite
 - **Durability**: Committed data persists even after crashes
 
 ## Pragma Modes
@@ -104,7 +114,7 @@ SQLite provides:
 | **balanced** *(default)* | NORMAL | 8 MB | 256 MB | Yes | Best mix of speed and safety for most apps |
 | **fast** | OFF | 16 MB | 256 MB | Yes | Maximum throughput — data may be lost on OS crash |
 
-All WAL modes use `journal_mode=WAL`, `temp_store=MEMORY`, and `busy_timeout=5000ms`.
+All WAL modes use `journal_mode=WAL` and `temp_store=MEMORY`. Lock waiting is configured independently through `busyTimeoutMs` and therefore also applies to `pragma: 'none'`.
 
 ```javascript
 // Backward-compatible (no PRAGMAs, no WITHOUT ROWID)
@@ -132,30 +142,33 @@ import { SqliteFastDriver } from 'deepbase-sqlite';
 Data is stored in a simple key-value table:
 
 ```sql
--- pragma: 'none' (legacy-compatible)
 CREATE TABLE deepbase (
   key TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-)
+  value TEXT NOT NULL,
+  seq INTEGER NOT NULL
+);
 
--- pragma: 'safe' | 'balanced' | 'fast' (optimized)
-CREATE TABLE deepbase (
+CREATE UNIQUE INDEX deepbase_seq_unique ON deepbase(seq);
+
+CREATE TABLE deepbase_meta (
   key TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-) WITHOUT ROWID
+  value INTEGER NOT NULL
+);
 ```
 
+`deepbase_meta` is always created `WITHOUT ROWID`; optimized PRAGMA profiles do the same for `deepbase`. The metadata table tracks the internal schema version, while user data remains exclusively in `deepbase`.
+
 Example data:
 
 ```
-key                   | value
-----------------------|------------------
-users.alice.name      | "Alice"
-users.alice.age       | 30
-users.bob.name        | "Bob"
-users.bob.age         | 25
-config.theme           | "dark"
-config.lang            | "en"
+key                   | value    | seq
+----------------------|----------|----
+users.alice.name      | "Alice"  | 1
+users.alice.age       | 30       | 2
+users.bob.name        | "Bob"    | 3
+users.bob.age         | 25       | 4
+config.theme          | "dark"   | 5
+config.lang           | "en"     | 6
 ```
 
 ## Use Cases
@@ -271,6 +284,17 @@ await db.set(`user_${userId}_profile`, data);
 
 ## Troubleshooting
 
+### `SQLITE_BUSY` / `database is locked`
+
+The driver waits and retries complete transactions when another connection owns the write lock. If the retry budget is exhausted:
+
+1. Confirm every process points to the same local filesystem, not NFS.
+2. Look for long-running migrations, raw `better-sqlite3` connections, SQLite tools, or overlapping deployments.
+3. Increase `busyTimeoutMs` or `busyRetry.maxAttempts` only for known transient contention.
+4. Move to a client-server database if write contention is sustained.
+
+`better-sqlite3` is synchronous. Each native lock wait blocks that Node.js thread for up to `busyTimeoutMs`; the JavaScript backoff between attempts is asynchronous.
+
 ### `Could not locate the bindings file` / `better_sqlite3.node` missing
 
 This error means `better-sqlite3`'s native binding was never fetched or built.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-sqlite",
-  "version": "3.6.9",
+  "version": "3.7.0",
   "description": "⚡ DeepBase SQLite - SQLite database driver",
   "type": "module",
   "main": "src/index.cjs",
@@ -17,10 +17,7 @@
     "better-sqlite3": "^11.8.1"
   },
   "peerDependencies": {
-    "deepbase": "^3.6.9"
-  },
-  "scripts": {
-    "test": "mocha test/test.js"
+    "deepbase": "^3.7.0"
   },
   "devDependencies": {
     "mocha": "^10.8.2"
@@ -44,5 +41,8 @@
   "bugs": {
     "url": "https://github.com/clasen/DeepBase/issues"
   },
-  "homepage": "https://github.com/clasen/DeepBase/tree/main/packages/driver-sqlite"
-}
+  "homepage": "https://github.com/clasen/DeepBase/tree/main/packages/driver-sqlite",
+  "scripts": {
+    "test": "mocha test/test.js test/test-multiprocess.js"
+  }
+}

package/src/SqliteDriver.js

@@ -2,55 +2,28 @@ import { DeepBaseDriver } from 'deepbase';
 import Database from 'better-sqlite3';
 import fs from 'fs';
 import * as pathModule from 'path';
-
-const PRAGMA = {
-  none: null,
-  safe: {
-    journal_mode: 'WAL',
-    synchronous: 'FULL',
-    temp_store: 'MEMORY',
-    cache_size: -2000,
-    busy_timeout: 5000,
-    mmap_size: 0,
-  },
-  balanced: {
-    journal_mode: 'WAL',
-    synchronous: 'NORMAL',
-    temp_store: 'MEMORY',
-    cache_size: -8000,
-    busy_timeout: 5000,
-    mmap_size: 268435456,
-  },
-  fast: {
-    journal_mode: 'WAL',
-    synchronous: 'OFF',
-    temp_store: 'MEMORY',
-    cache_size: -16000,
-    busy_timeout: 5000,
-    mmap_size: 268435456,
-  },
-};
+import { withBusyRetry } from './busy.js';
+import { resolveSqliteConfig } from './config.js';
+import { migrateSchema } from './schema.js';
 
 export class SqliteDriver extends DeepBaseDriver {
-  static _instances = {};
-
-  constructor({ name, path, pragma, ...opts } = {}) {
+  constructor({ name, path, pragma, busyTimeoutMs, busyRetry, ...opts } = {}) {
     super(opts);
 
+    const config = resolveSqliteConfig({ pragma, busyTimeoutMs, busyRetry });
     this.name = name || 'default';
     this.path = path || pathModule.join(process.cwd(), 'db');
-    this.pragma = pragma || 'balanced';
+    this.pragma = config.pragma;
+    this.pragmaConfig = config.pragmaConfig;
+    this.busyTimeoutMs = config.busyTimeoutMs;
+    this.busyRetry = config.busyRetry;
 
     this.path = pathModule.resolve(this.path);
     this.fileName = pathModule.join(this.path, `${this.name}.db`);
 
-    if (SqliteDriver._instances[this.fileName]) {
-      return SqliteDriver._instances[this.fileName];
-    }
-
     this.db = null;
-    this._nextSeq = 1;
-    SqliteDriver._instances[this.fileName] = this;
+    this._connectPromise = null;
+    this._writeQueue = Promise.resolve();
   }
 
   _connectSync() {
@@ -61,7 +34,7 @@ export class SqliteDriver extends DeepBaseDriver {
     }
 
     try {
-      this.db = new Database(this.fileName);
+      this.db = new Database(this.fileName, { timeout: this.busyTimeoutMs });
     } catch (err) {
       if (this._isMissingNativeBinding(err)) {
         const hint =
@@ -78,35 +51,22 @@ export class SqliteDriver extends DeepBaseDriver {
       throw err;
     }
 
-    const cfg = PRAGMA[this.pragma];
+    const cfg = this.pragmaConfig;
     if (cfg) {
       this.db.pragma(`journal_mode = ${cfg.journal_mode}`);
       this.db.pragma(`synchronous = ${cfg.synchronous}`);
       this.db.pragma(`temp_store = ${cfg.temp_store}`);
       this.db.pragma(`cache_size = ${cfg.cache_size}`);
-      this.db.pragma(`busy_timeout = ${cfg.busy_timeout}`);
       this.db.pragma(`mmap_size = ${cfg.mmap_size}`);
     }
 
     const withoutRowid = cfg ? ' WITHOUT ROWID' : '';
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS deepbase (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL,
-        seq INTEGER NOT NULL DEFAULT 0
-      )${withoutRowid}
-    `);
-
-    const tableCols = this.db.prepare('PRAGMA table_info(deepbase)').all();
-    if (!tableCols.some((c) => c.name === 'seq')) {
-      this.db.exec('ALTER TABLE deepbase ADD COLUMN seq INTEGER NOT NULL DEFAULT 0');
-    }
+    migrateSchema(this.db, { withoutRowid });
 
     this.getStmt = this.db.prepare('SELECT value FROM deepbase WHERE key = ?');
-    this.getMaxSeqStmt = this.db.prepare('SELECT IFNULL(MAX(seq), 0) AS maxSeq FROM deepbase');
     this.setStmt = this.db.prepare(`
       INSERT INTO deepbase (key, value, seq)
-      VALUES (?, ?, ?)
+      VALUES (?, ?, (SELECT IFNULL(MAX(seq), 0) + 1 FROM deepbase))
       ON CONFLICT(key) DO UPDATE SET value = excluded.value
     `);
     this.delStmt = this.db.prepare('DELETE FROM deepbase WHERE key = ?');
@@ -123,18 +83,20 @@ export class SqliteDriver extends DeepBaseDriver {
     this.delChildrenStmt = this.db.prepare("DELETE FROM deepbase WHERE key LIKE ? ESCAPE '!'");
     this.hasChildrenStmt = this.db.prepare("SELECT 1 FROM deepbase WHERE key LIKE ? ESCAPE '!' LIMIT 1");
 
-    this._setTxn = this.db.transaction((key, jsonValue, keys) => {
+    const setTxn = this.db.transaction((key, jsonValue, keys) => {
       this._expandParentObjects(keys);
       this._replaceRow(key, jsonValue);
     });
+    this._setTxn = (...args) => setTxn.immediate(...args);
 
-    this._delTxn = this.db.transaction((key, likePattern, keys) => {
+    const delTxn = this.db.transaction((key, likePattern, keys) => {
       this._expandParentObjects(keys);
       this.delStmt.run(key);
       this.delChildrenStmt.run(likePattern);
     });
+    this._delTxn = (...args) => delTxn.immediate(...args);
 
-    this._updTxn = this.db.transaction((keys, func) => {
+    const updTxn = this.db.transaction((keys, func) => {
       const currentValue = this._getSync(keys);
       const newValue = func(currentValue);
       const key = this._pathToKey(keys);
@@ -142,37 +104,84 @@ export class SqliteDriver extends DeepBaseDriver {
       this._replaceRow(key, JSON.stringify(newValue));
       return keys;
     });
+    this._updTxn = (...args) => updTxn.immediate(...args);
 
-    this._setRootTxn = this.db.transaction((entries) => {
+    const setRootTxn = this.db.transaction((entries) => {
       this.db.exec('DELETE FROM deepbase');
-      this._nextSeq = 1;
       for (const [key, value] of entries) {
-        this.setStmt.run(key, JSON.stringify(value), this._consumeSeq());
+        this.setStmt.run(key, JSON.stringify(value));
       }
     });
+    this._setRootTxn = (...args) => setRootTxn.immediate(...args);
+
+    const clearTxn = this.db.transaction(() => {
+      this.db.exec('DELETE FROM deepbase');
+    });
+    this._clearTxn = (...args) => clearTxn.immediate(...args);
 
-    this._nextSeq = Number(this.getMaxSeqStmt.get()?.maxSeq || 0) + 1;
     this._connected = true;
   }
 
   async connect() {
-    this._connectSync();
+    if (this._connected) return;
+    if (!this._connectPromise) {
+      this._connectPromise = withBusyRetry(() => this._openSync(), this.busyRetry)
+        .finally(() => {
+          this._connectPromise = null;
+        });
+    }
+    return this._connectPromise;
+  }
+
+  _openSync() {
+    try {
+      this._connectSync();
+    } catch (error) {
+      this._closeConnection();
+      throw error;
+    }
   }
 
   async disconnect() {
+    return this._queueWrite(async () => {
+      if (this._connectPromise) {
+        await this._connectPromise;
+      }
+      this._closeConnection();
+    });
+  }
+
+  _closeConnection() {
     if (this.db) {
       this.db.close();
-      this.db = null;
     }
+    this.db = null;
     this._connected = false;
   }
 
+  _queueWrite(operation) {
+    const result = this._writeQueue.then(operation, operation);
+    this._writeQueue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  _runWrite(operation) {
+    return this._queueWrite(async () => {
+      await this.connect();
+      return withBusyRetry(operation, this.busyRetry);
+    });
+  }
+
   async get(...args) {
+    await this.connect();
     return this._getSync(args);
   }
 
   getSync(...args) {
-    this._connectSync();
+    this._openSync();
     return this._getSync(args);
   }
 
@@ -205,35 +214,40 @@ export class SqliteDriver extends DeepBaseDriver {
     }
 
     if (args.length === 1) {
-      await this._setRootObject(args[0]);
-      return [];
+      const entries = this._flattenObject(args[0]);
+      return this._runWrite(() => {
+        this._setRootTxn(entries);
+        return [];
+      });
     }
 
-    return this._setSync(args);
-  }
-
-  _setSync(args) {
     const keys = args.slice(0, -1);
     const value = args[args.length - 1];
     const key = this._pathToKey(keys);
-    this._setTxn(key, JSON.stringify(value), keys);
-    return keys;
+    const jsonValue = JSON.stringify(value);
+    return this._runWrite(() => {
+      this._setTxn(key, jsonValue, keys);
+      return keys;
+    });
   }
 
   _replaceRow(key, jsonValue) {
     this.delChildrenStmt.run(this._likePrefix(key));
-    this.setStmt.run(key, jsonValue, this._consumeSeq());
+    this.setStmt.run(key, jsonValue);
   }
 
   async del(...keys) {
     if (keys.length === 0) {
-      this.db.exec('DELETE FROM deepbase');
-      this._nextSeq = 1;
-      return;
+      return this._runWrite(() => {
+        this._clearTxn();
+      });
     }
 
     const key = this._pathToKey(keys);
-    this._delTxn(key, this._likePrefix(key), keys);
+    const likePattern = this._likePrefix(key);
+    return this._runWrite(() => {
+      this._delTxn(key, likePattern, keys);
+    });
   }
 
   async inc(...args) {
@@ -256,14 +270,16 @@ export class SqliteDriver extends DeepBaseDriver {
   async upd(...args) {
     const func = args.pop();
     const keys = args;
-    return this._updTxn(keys, func);
+    return this._runWrite(() => this._updTxn(keys, func));
   }
 
   async first(...args) {
+    await this.connect();
     return this._firstOrLastKey(args, false);
   }
 
   async last(...args) {
+    await this.connect();
     return this._firstOrLastKey(args, true);
   }
 
@@ -310,11 +326,6 @@ export class SqliteDriver extends DeepBaseDriver {
     return result;
   }
 
-  async _setRootObject(obj) {
-    const entries = this._flattenObject(obj);
-    this._setRootTxn(entries);
-  }
-
   _buildObjectFromChildren(parentKey, likePattern) {
     const rows = this.getKeysLikeStmt.all(likePattern || (parentKey ? this._likePrefix(parentKey) : '%'));
     const result = {};
@@ -352,12 +363,24 @@ export class SqliteDriver extends DeepBaseDriver {
     if (path.length === 0) return;
 
     if (path.length === 1) {
-      obj[path[0]] = value;
+      const key = path[0];
+      const existing = obj[key];
+      if (
+        value === null &&
+        existing !== null &&
+        typeof existing === 'object' &&
+        !Array.isArray(existing) &&
+        Object.keys(existing).length > 0
+      ) {
+        return;
+      }
+      obj[key] = value;
       return;
     }
 
     const key = path[0];
-    if (!obj.hasOwnProperty(key) || typeof obj[key] !== 'object') {
+    const current = obj[key];
+    if (!obj.hasOwnProperty(key) || current === null || typeof current !== 'object' || Array.isArray(current)) {
       obj[key] = {};
     }
 
@@ -422,18 +445,12 @@ export class SqliteDriver extends DeepBaseDriver {
 
           const entries = this._flattenObject(parentValue, parentKey);
           for (const [key, value] of entries) {
-            this.setStmt.run(key, JSON.stringify(value), this._consumeSeq());
+            this.setStmt.run(key, JSON.stringify(value));
           }
         }
       }
     }
   }
-
-  _consumeSeq() {
-    const seq = this._nextSeq;
-    this._nextSeq += 1;
-    return seq;
-  }
 }
 
 export default SqliteDriver;

package/src/busy.js

@@ -0,0 +1,28 @@
+export function isSqliteBusyError(error) {
+  return typeof error?.code === 'string' && error.code.startsWith('SQLITE_BUSY');
+}
+
+function retryDelayMs(attempt, { baseDelayMs, maxDelayMs }) {
+  const cap = Math.min(maxDelayMs, baseDelayMs * (2 ** Math.max(0, attempt - 1)));
+  if (cap === 0) return 0;
+  return Math.floor(Math.random() * (cap + 1));
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function withBusyRetry(operation, config) {
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
+    try {
+      return operation();
+    } catch (error) {
+      if (!isSqliteBusyError(error) || attempt === config.maxAttempts) {
+        throw error;
+      }
+      await delay(retryDelayMs(attempt, config));
+    }
+  }
+
+  throw new Error('Unreachable busy retry state');
+}

package/src/config.js

@@ -0,0 +1,78 @@
+const PRAGMA_PROFILES = Object.freeze({
+  none: null,
+  safe: Object.freeze({
+    journal_mode: 'WAL',
+    synchronous: 'FULL',
+    temp_store: 'MEMORY',
+    cache_size: -2000,
+    mmap_size: 0,
+  }),
+  balanced: Object.freeze({
+    journal_mode: 'WAL',
+    synchronous: 'NORMAL',
+    temp_store: 'MEMORY',
+    cache_size: -8000,
+    mmap_size: 268435456,
+  }),
+  fast: Object.freeze({
+    journal_mode: 'WAL',
+    synchronous: 'OFF',
+    temp_store: 'MEMORY',
+    cache_size: -16000,
+    mmap_size: 268435456,
+  }),
+});
+
+export const SQLITE_CONFIG = Object.freeze({
+  defaultPragma: 'balanced',
+  schemaVersion: 1,
+  busyTimeoutMs: 5000,
+  busyRetry: Object.freeze({
+    maxAttempts: 2,
+    baseDelayMs: 25,
+    maxDelayMs: 250,
+  }),
+  pragmaProfiles: PRAGMA_PROFILES,
+});
+
+function assertNonNegativeInteger(name, value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative integer`);
+  }
+}
+
+export function resolveSqliteConfig({ pragma, busyTimeoutMs, busyRetry } = {}) {
+  const resolvedPragma = pragma ?? SQLITE_CONFIG.defaultPragma;
+  if (!Object.prototype.hasOwnProperty.call(SQLITE_CONFIG.pragmaProfiles, resolvedPragma)) {
+    throw new TypeError(`pragma must be one of: ${Object.keys(SQLITE_CONFIG.pragmaProfiles).join(', ')}`);
+  }
+
+  const resolvedBusyTimeoutMs = busyTimeoutMs ?? SQLITE_CONFIG.busyTimeoutMs;
+  assertNonNegativeInteger('busyTimeoutMs', resolvedBusyTimeoutMs);
+
+  if (busyRetry !== undefined && (busyRetry === null || typeof busyRetry !== 'object' || Array.isArray(busyRetry))) {
+    throw new TypeError('busyRetry must be an object');
+  }
+
+  const resolvedBusyRetry = {
+    ...SQLITE_CONFIG.busyRetry,
+    ...(busyRetry ?? {}),
+  };
+  assertNonNegativeInteger('busyRetry.maxAttempts', resolvedBusyRetry.maxAttempts);
+  assertNonNegativeInteger('busyRetry.baseDelayMs', resolvedBusyRetry.baseDelayMs);
+  assertNonNegativeInteger('busyRetry.maxDelayMs', resolvedBusyRetry.maxDelayMs);
+
+  if (resolvedBusyRetry.maxAttempts < 1) {
+    throw new TypeError('busyRetry.maxAttempts must be at least 1');
+  }
+  if (resolvedBusyRetry.maxDelayMs < resolvedBusyRetry.baseDelayMs) {
+    throw new TypeError('busyRetry.maxDelayMs must be greater than or equal to busyRetry.baseDelayMs');
+  }
+
+  return {
+    pragma: resolvedPragma,
+    pragmaConfig: SQLITE_CONFIG.pragmaProfiles[resolvedPragma],
+    busyTimeoutMs: resolvedBusyTimeoutMs,
+    busyRetry: resolvedBusyRetry,
+  };
+}

package/src/index.d.ts

@@ -1,9 +1,17 @@
 import { DeepBaseDriver, DeepBaseDriverOptions } from 'deepbase';
 
+export interface SqliteBusyRetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+
 export interface SqliteDriverOptions extends DeepBaseDriverOptions {
     name?: string;
     path?: string;
     pragma?: 'none' | 'safe' | 'balanced' | 'fast';
+    busyTimeoutMs?: number;
+    busyRetry?: SqliteBusyRetryOptions;
 }
 
 export class SqliteDriver extends DeepBaseDriver {
@@ -13,6 +21,8 @@ export class SqliteDriver extends DeepBaseDriver {
     path: string;
     fileName: string;
     pragma: string;
+    busyTimeoutMs: number;
+    busyRetry: Required<SqliteBusyRetryOptions>;
 }
 
 export { SqliteDriver as SqliteFastDriver };

package/src/schema.js

@@ -0,0 +1,79 @@
+import { SQLITE_CONFIG } from './config.js';
+
+const SCHEMA_VERSION_KEY = 'schema_version';
+
+function createBaseSchema(db, withoutRowid) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS deepbase (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      seq INTEGER NOT NULL DEFAULT 0
+    )${withoutRowid}
+  `);
+
+  const columns = db.prepare('PRAGMA table_info(deepbase)').all();
+  if (!columns.some(column => column.name === 'seq')) {
+    db.exec('ALTER TABLE deepbase ADD COLUMN seq INTEGER NOT NULL DEFAULT 0');
+  }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS deepbase_meta (
+      key TEXT PRIMARY KEY,
+      value INTEGER NOT NULL
+    ) WITHOUT ROWID
+  `);
+}
+
+function readSchemaVersion(db) {
+  const row = db.prepare('SELECT value FROM deepbase_meta WHERE key = ?').get(SCHEMA_VERSION_KEY);
+  return Number(row?.value ?? 0);
+}
+
+function normalizeSequence(db) {
+  const nonPositive = db.prepare('SELECT 1 FROM deepbase WHERE seq < 1 LIMIT 1').get();
+  const needsNormalization = nonPositive || db.prepare(`
+      SELECT 1
+      FROM deepbase
+      GROUP BY seq
+      HAVING COUNT(*) > 1
+      LIMIT 1
+    `).get();
+  if (!needsNormalization) return;
+
+  const rows = db.prepare('SELECT key FROM deepbase ORDER BY seq, key').all();
+  const update = db.prepare('UPDATE deepbase SET seq = ? WHERE key = ?');
+
+  rows.forEach((row, index) => {
+    update.run(index + 1, row.key);
+  });
+}
+
+function writeSchemaVersion(db) {
+  db.prepare(`
+    INSERT INTO deepbase_meta (key, value)
+    VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(SCHEMA_VERSION_KEY, SQLITE_CONFIG.schemaVersion);
+}
+
+export function migrateSchema(db, { withoutRowid = '' } = {}) {
+  const migration = db.transaction(() => {
+    createBaseSchema(db, withoutRowid);
+
+    const version = readSchemaVersion(db);
+    if (version > SQLITE_CONFIG.schemaVersion) {
+      throw new Error(
+        `deepbase-sqlite schema version ${version} is newer than supported version ${SQLITE_CONFIG.schemaVersion}`,
+      );
+    }
+
+    if (version < SQLITE_CONFIG.schemaVersion) {
+      normalizeSequence(db);
+      writeSchemaVersion(db);
+    }
+
+    db.exec('CREATE UNIQUE INDEX IF NOT EXISTS deepbase_seq_unique ON deepbase(seq)');
+  });
+
+  migration.immediate();
+}

package/test/fixtures.js

@@ -0,0 +1,57 @@
+import Database from 'better-sqlite3';
+
+export function createLegacyDatabase(fileName, rows) {
+  const db = new Database(fileName);
+  db.exec('CREATE TABLE deepbase (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+  const insert = db.prepare('INSERT INTO deepbase (key, value) VALUES (?, ?)');
+  const insertRows = db.transaction((entries) => {
+    for (const [key, value] of entries) {
+      insert.run(key, JSON.stringify(value));
+    }
+  });
+  insertRows(rows);
+  db.close();
+}
+
+export function createSequencedDatabase(fileName, rows, { failMigration = false } = {}) {
+  const db = new Database(fileName);
+  db.exec(`
+    CREATE TABLE deepbase (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      seq INTEGER NOT NULL DEFAULT 0
+    )
+  `);
+  const insert = db.prepare('INSERT INTO deepbase (key, value, seq) VALUES (?, ?, ?)');
+  const insertRows = db.transaction((entries) => {
+    for (const [key, value, seq] of entries) {
+      insert.run(key, JSON.stringify(value), seq);
+    }
+  });
+  insertRows(rows);
+
+  if (failMigration) {
+    db.exec(`
+      CREATE TRIGGER fail_seq_migration
+      BEFORE UPDATE OF seq ON deepbase
+      BEGIN
+        SELECT RAISE(ABORT, 'forced migration failure');
+      END
+    `);
+  }
+  db.close();
+}
+
+export function inspectDatabase(fileName) {
+  const db = new Database(fileName);
+  const rows = db.prepare('SELECT key, seq FROM deepbase ORDER BY seq, key').all();
+  const indexes = db.prepare("PRAGMA index_list('deepbase')").all();
+  const metaTable = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'deepbase_meta'",
+  ).get();
+  const schemaVersion = metaTable
+    ? db.prepare("SELECT value FROM deepbase_meta WHERE key = 'schema_version'").get()?.value
+    : undefined;
+  db.close();
+  return { rows, indexes, schemaVersion };
+}

package/test/test-multiprocess.js

@@ -0,0 +1,265 @@
+import assert from 'assert';
+import { fork } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Database from 'better-sqlite3';
+import { SqliteDriver } from '../src/SqliteDriver.js';
+import { createLegacyDatabase, createSequencedDatabase, inspectDatabase } from './fixtures.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const workerPath = path.join(__dirname, 'worker.js');
+const testDataPath = path.join(__dirname, 'test-data-multiprocess');
+const retryOptions = {
+  busyTimeoutMs: 50,
+  busyRetry: {
+    maxAttempts: 20,
+    baseDelayMs: 2,
+    maxDelayMs: 20,
+  },
+};
+
+function createWorker(args) {
+  const child = fork(workerPath, [JSON.stringify(args)], {
+    stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+  });
+  let stderr = '';
+  child.stderr.on('data', data => {
+    stderr += data.toString();
+  });
+  const done = new Promise((resolve, reject) => {
+    child.on('error', reject);
+    child.on('exit', code => {
+      if (code === 0) resolve();
+      else reject(new Error(`Worker exited with code ${code}: ${stderr}`));
+    });
+  });
+  return { child, done };
+}
+
+function spawnWorker(args) {
+  return createWorker(args).done;
+}
+
+function spawnLockWorker(args) {
+  const worker = createWorker({ ...args, task: 'hold-lock' });
+  const locked = new Promise((resolve, reject) => {
+    worker.child.on('message', message => {
+      if (message?.type === 'locked') resolve({ done: worker.done });
+    });
+    worker.child.on('error', reject);
+    worker.child.on('exit', code => {
+      if (code !== 0) reject(new Error(`Lock worker exited before acquiring lock (${code})`));
+    });
+  });
+  return locked;
+}
+
+describe('SqliteDriver multi-process safety', function () {
+  this.timeout(30000);
+
+  beforeEach(function () {
+    fs.rmSync(testDataPath, { recursive: true, force: true });
+    fs.mkdirSync(testDataPath, { recursive: true });
+  });
+
+  afterEach(function () {
+    fs.rmSync(testDataPath, { recursive: true, force: true });
+  });
+
+  it('validates concurrency options eagerly', function () {
+    assert.throws(
+      () => new SqliteDriver({ pragma: 'invalid' }),
+      /pragma must be one of/,
+    );
+    assert.throws(
+      () => new SqliteDriver({ busyTimeoutMs: -1 }),
+      /busyTimeoutMs must be a non-negative integer/,
+    );
+    assert.throws(
+      () => new SqliteDriver({ busyRetry: { maxAttempts: 0 } }),
+      /maxAttempts must be at least 1/,
+    );
+  });
+
+  it('applies busyTimeoutMs to the SQLite connection', async function () {
+    const driver = new SqliteDriver({
+      name: 'configured-timeout',
+      path: testDataPath,
+      busyTimeoutMs: 123,
+    });
+    await driver.connect();
+    assert.strictEqual(driver.db.pragma('busy_timeout', { simple: true }), 123);
+    await driver.disconnect();
+  });
+
+  it('migrates a legacy database without seq and preserves observable order', async function () {
+    const name = 'legacy-no-seq';
+    const fileName = path.join(testDataPath, `${name}.db`);
+    createLegacyDatabase(fileName, [['b', 2], ['a', 1]]);
+
+    const driver = new SqliteDriver({ name, path: testDataPath });
+    await driver.connect();
+    await driver.disconnect();
+
+    const state = inspectDatabase(fileName);
+    assert.deepStrictEqual(state.rows, [
+      { key: 'a', seq: 1 },
+      { key: 'b', seq: 2 },
+    ]);
+    assert.strictEqual(state.schemaVersion, 1);
+    assert.ok(state.indexes.some(index => index.name === 'deepbase_seq_unique' && index.unique === 1));
+  });
+
+  it('normalizes duplicate seq values without changing their current order', async function () {
+    const name = 'duplicate-seq';
+    const fileName = path.join(testDataPath, `${name}.db`);
+    createSequencedDatabase(fileName, [
+      ['c', 3, 2],
+      ['a', 1, 0],
+      ['d', 4, 2],
+      ['b', 2, 0],
+    ]);
+
+    const driver = new SqliteDriver({ name, path: testDataPath });
+    await driver.connect();
+    await driver.disconnect();
+
+    assert.deepStrictEqual(inspectDatabase(fileName).rows, [
+      { key: 'a', seq: 1 },
+      { key: 'b', seq: 2 },
+      { key: 'c', seq: 3 },
+      { key: 'd', seq: 4 },
+    ]);
+  });
+
+  it('rolls back the complete migration when normalization fails', async function () {
+    const name = 'migration-rollback';
+    const fileName = path.join(testDataPath, `${name}.db`);
+    createSequencedDatabase(fileName, [['a', 1, 0], ['b', 2, 0]], { failMigration: true });
+
+    const driver = new SqliteDriver({ name, path: testDataPath, ...retryOptions });
+    await assert.rejects(driver.connect(), /forced migration failure/);
+
+    const failedState = inspectDatabase(fileName);
+    assert.deepStrictEqual(failedState.rows, [
+      { key: 'a', seq: 0 },
+      { key: 'b', seq: 0 },
+    ]);
+    assert.strictEqual(failedState.schemaVersion, undefined);
+
+    const raw = new Database(fileName);
+    raw.exec('DROP TRIGGER fail_seq_migration');
+    raw.close();
+
+    await driver.connect();
+    await driver.disconnect();
+    assert.deepStrictEqual(inspectDatabase(fileName).rows, [
+      { key: 'a', seq: 1 },
+      { key: 'b', seq: 2 },
+    ]);
+  });
+
+  it('serializes concurrent schema migration across processes', async function () {
+    const name = 'concurrent-migration';
+    const fileName = path.join(testDataPath, `${name}.db`);
+    createLegacyDatabase(fileName, [['value', 1]]);
+
+    await Promise.all(Array.from({ length: 6 }, (_, workerId) =>
+      spawnWorker({
+        task: 'connect-only',
+        workerId,
+        name,
+        path: testDataPath,
+        ...retryOptions,
+      }),
+    ));
+
+    const state = inspectDatabase(fileName);
+    assert.strictEqual(state.schemaVersion, 1);
+    assert.deepStrictEqual(state.rows, [{ key: 'value', seq: 1 }]);
+  });
+
+  it('keeps increments atomic across processes', async function () {
+    const name = 'concurrent-inc';
+    const driver = new SqliteDriver({ name, path: testDataPath, ...retryOptions });
+    await driver.set('counter', 0);
+    await driver.disconnect();
+
+    await Promise.all(Array.from({ length: 4 }, (_, workerId) =>
+      spawnWorker({
+        task: 'inc',
+        workerId,
+        iterations: 25,
+        name,
+        path: testDataPath,
+        ...retryOptions,
+      }),
+    ));
+
+    const verify = new SqliteDriver({ name, path: testDataPath });
+    assert.strictEqual(await verify.get('counter'), 100);
+    await verify.disconnect();
+  });
+
+  it('preserves mixed writes from multiple processes with unique seq values', async function () {
+    const name = 'mixed-writes';
+    await Promise.all(Array.from({ length: 3 }, (_, workerId) =>
+      spawnWorker({
+        task: 'mixed',
+        workerId,
+        iterations: 10,
+        name,
+        path: testDataPath,
+        ...retryOptions,
+      }),
+    ));
+
+    const verify = new SqliteDriver({ name, path: testDataPath });
+    assert.strictEqual(Object.keys(await verify.get('entries')).length, 30);
+    assert.strictEqual(Object.keys(await verify.get('items')).length, 30);
+    assert.strictEqual(await verify.get('temporary'), null);
+    await verify.disconnect();
+
+    const rows = inspectDatabase(path.join(testDataPath, `${name}.db`)).rows;
+    assert.strictEqual(new Set(rows.map(row => row.seq)).size, rows.length);
+  });
+
+  it('retries a write until a short external lock is released', async function () {
+    const name = 'short-lock';
+    const fileName = path.join(testDataPath, `${name}.db`);
+    const driver = new SqliteDriver({ name, path: testDataPath, ...retryOptions });
+    await driver.connect();
+
+    const lockWorker = await spawnLockWorker({
+      fileName,
+      holdMs: 150,
+      busyTimeoutMs: retryOptions.busyTimeoutMs,
+    });
+    await driver.set('after-lock', true);
+    await lockWorker.done;
+
+    assert.strictEqual(await driver.get('after-lock'), true);
+    await driver.disconnect();
+  });
+
+  it('surfaces SQLITE_BUSY after the configured retry budget', async function () {
+    const name = 'long-lock';
+    const fileName = path.join(testDataPath, `${name}.db`);
+    const driver = new SqliteDriver({
+      name,
+      path: testDataPath,
+      busyTimeoutMs: 10,
+      busyRetry: { maxAttempts: 2, baseDelayMs: 0, maxDelayMs: 0 },
+    });
+    await driver.connect();
+
+    const lockWorker = await spawnLockWorker({ fileName, holdMs: 300, busyTimeoutMs: 10 });
+    await assert.rejects(
+      driver.set('blocked', true),
+      error => error.code === 'SQLITE_BUSY',
+    );
+    await lockWorker.done;
+    await driver.disconnect();
+  });
+});

package/test/test.js

@@ -353,11 +353,11 @@ for (const pragma of PRAGMA_MODES) {
       });
     });
 
-    describe('Singleton Pattern', function () {
-      it('should return same instance for same file', function () {
+    describe('Independent Connection Lifecycle', function () {
+      it('should create independent instances for the same file', function () {
         const d1 = new SqliteDriver({ name: `singleton-${pragma}`, path: testDataPath, pragma });
         const d2 = new SqliteDriver({ name: `singleton-${pragma}`, path: testDataPath, pragma });
-        assert.strictEqual(d1, d2);
+        assert.notStrictEqual(d1, d2);
       });
 
       it('should return different instances for different files', function () {
@@ -365,6 +365,20 @@ for (const pragma of PRAGMA_MODES) {
         const d2 = new SqliteDriver({ name: `file2-${pragma}`, path: testDataPath, pragma });
         assert.notStrictEqual(d1, d2);
       });
+
+      it('disconnecting one instance should not close another connection', async function () {
+        const name = `lifecycle-${pragma}`;
+        const d1 = new SqliteDriver({ name, path: testDataPath, pragma });
+        const d2 = new SqliteDriver({ name, path: testDataPath, pragma });
+        await d1.connect();
+        await d2.connect();
+        await d1.set('first', 1);
+        await d1.disconnect();
+        await d2.set('second', 2);
+        assert.strictEqual(await d2.get('first'), 1);
+        assert.strictEqual(await d2.get('second'), 2);
+        await d2.disconnect();
+      });
     });
 
     describe('Root Object Operations', function () {
@@ -394,6 +408,37 @@ for (const pragma of PRAGMA_MODES) {
         assert.deepStrictEqual(await db.get(), { new: 'data' });
         assert.strictEqual(await db.get('old'), null);
       });
+
+      it('should read root when a null parent row coexists with child rows', async function () {
+        const itemPath = await db.add('user1', 'message', 'pending', { test: 1 });
+        const itemId = itemPath[itemPath.length - 1];
+        const driver = db.getDriver(0);
+        driver.db.prepare('INSERT OR REPLACE INTO deepbase (key, value, seq) VALUES (?, ?, ?)').run(
+          'user1.message.pending',
+          'null',
+          999,
+        );
+
+        const pending = {
+          [itemId]: { test: 1 },
+        };
+        const message = {
+          pending,
+        };
+        const user = {
+          message,
+        };
+
+        assert.deepStrictEqual(await db.get(), {
+          user1: {
+            message,
+          },
+        });
+        assert.deepStrictEqual(await db.get('user1'), user);
+        assert.deepStrictEqual(await db.get('user1', 'message'), message);
+        assert.deepStrictEqual(await db.get('user1', 'message', 'pending'), pending);
+        assert.deepStrictEqual(await db.keys('user1', 'message', 'pending'), [itemId]);
+      });
     });
 
     describe('Deep Nesting', function () {

package/test/worker.js

@@ -0,0 +1,61 @@
+import Database from 'better-sqlite3';
+import { SqliteDriver } from '../src/SqliteDriver.js';
+
+const options = JSON.parse(process.argv[2]);
+
+function wait(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function holdLock() {
+  const databaseOptions = options.busyTimeoutMs === undefined
+    ? undefined
+    : { timeout: options.busyTimeoutMs };
+  const db = new Database(options.fileName, databaseOptions);
+  db.exec('BEGIN IMMEDIATE');
+  process.send?.({ type: 'locked' });
+  await wait(options.holdMs);
+  db.exec('COMMIT');
+  db.close();
+}
+
+async function runDriverTask() {
+  const driver = new SqliteDriver({
+    name: options.name,
+    path: options.path,
+    pragma: options.pragma ?? 'balanced',
+    busyTimeoutMs: options.busyTimeoutMs,
+    busyRetry: options.busyRetry,
+  });
+
+  await driver.connect();
+
+  if (options.task === 'inc') {
+    for (let i = 0; i < options.iterations; i += 1) {
+      await driver.inc('counter', 1);
+    }
+  } else if (options.task === 'set-unique') {
+    for (let i = 0; i < options.iterations; i += 1) {
+      await driver.set('entries', `${options.workerId}-${i}`, i);
+    }
+  } else if (options.task === 'mixed') {
+    for (let i = 0; i < options.iterations; i += 1) {
+      await driver.set('entries', `${options.workerId}-${i}`, i);
+      await driver.add('items', { workerId: options.workerId, index: i });
+      await driver.set('temporary', `${options.workerId}-${i}`, true);
+      await driver.del('temporary', `${options.workerId}-${i}`);
+    }
+  } else if (options.task !== 'connect-only') {
+    throw new Error(`Unknown worker task: ${options.task}`);
+  }
+
+  await driver.disconnect();
+}
+
+if (options.task === 'hold-lock') {
+  await holdLock();
+} else {
+  await runDriverTask();
+}
+
+process.disconnect?.();