deepbase-sqlite 3.6.10 → 3.8.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,58 @@ 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. Old and new sequence allocators must not write concurrently during a rolling deployment.
+
+### Maintenance
+
+The driver owns the `better-sqlite3` connection and exposes maintenance through
+its own API, so a backup or vacuum job needs no `better-sqlite3` entry in your
+own `package.json`. That keeps a single native binding in the tree and removes
+any chance of a version mismatch between your copy and the driver's.
+
+```javascript
+const driver = db.getDriver(0);
+
+const status = await driver.checkIntegrity();     // 'ok', or what SQLite found
+await driver.backup('./backups/mydb-2026-07-28.db');
+await driver.vacuum();
+await driver.checkpoint('TRUNCATE');
+```
+
+| Method | Behaviour |
+|--------|-----------|
+| `checkIntegrity()` | Runs `PRAGMA integrity_check` and returns its status verbatim. |
+| `backup(destination)` | Online copy, verified before it resolves. Returns `destination`. |
+| `vacuum()` | Rebuilds the file to reclaim free pages. |
+| `checkpoint(mode)` | `PASSIVE` (default), `FULL`, `RESTART` or `TRUNCATE`. Returns `{ busy, log, checkpointed }`. |
+
+`backup()` creates parent directories as needed, then reopens the result and
+verifies it with `integrity_check` — a backup nobody validated is not a backup.
+It rejects with code `DEEPBASE_SQLITE_BACKUP_CORRUPT` when the copy fails to
+verify, leaving the bad file on disk for inspection, so a restore routine must
+never pick a backup by timestamp alone. The copy is consistent with writes that
+land while it runs, and it does not block the driver's write queue.
+
+`vacuum()` and `checkpoint()` do take the write lock, so they queue behind the
+driver's own writes and honour `busyRetry`. Run them when the application is
+idle. `checkpoint()` rejects with code `DEEPBASE_SQLITE_NOT_WAL` on databases
+opened with `pragma: 'none'`, which use a rollback journal and have no WAL.
+
+Retention, rotation and scheduling stay in your application — the driver takes a
+verified snapshot, nothing more.
+
 ### Nested Data Structure
 
 Efficiently stores nested objects using a key-value schema:
@@ -82,7 +130,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 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`. For legacy databases, the driver only adds the missing column and index; it does not renumber existing rows. Historical ties remain deterministic through the `key` fallback order.
 
 ### ACID Compliance
 
@@ -90,7 +138,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 +152,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 +180,28 @@ 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 (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-) WITHOUT ROWID
+CREATE INDEX deepbase_seq_idx ON deepbase(seq);
 ```
 
+Optimized PRAGMA profiles create `deepbase` `WITHOUT ROWID`.
+
 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 +317,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.10",
+  "version": "3.8.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.10"
-  },
-  "scripts": {
-    "test": "mocha test/test.js"
+    "deepbase": "^3.8.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,29 @@ 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 { backupTo, checkIntegrity, checkpoint, vacuum } from './maintenance.js';
+import { ensureSchema } 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 +35,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 +52,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');
-    }
+    ensureSchema(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 +84,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 +105,102 @@ 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 checkIntegrity() {
+    await this.connect();
+    return checkIntegrity(this.db);
+  }
+
+  async backup(destination) {
+    await this.connect();
+    return backupTo(this.db, destination);
+  }
+
+  async vacuum() {
+    return this._runWrite(() => vacuum(this.db));
+  }
+
+  async checkpoint(mode = 'PASSIVE') {
+    return this._runWrite(() => checkpoint(this.db, mode));
+  }
+
   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 +233,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 +289,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 +345,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 = {};
@@ -434,18 +464,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,77 @@
+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',
+  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,28 @@
 import { DeepBaseDriver, DeepBaseDriverOptions } from 'deepbase';
 
+export interface SqliteBusyRetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+
+export type SqliteCheckpointMode = 'PASSIVE' | 'FULL' | 'RESTART' | 'TRUNCATE';
+
+export interface SqliteCheckpointResult {
+    /** `1` when readers or writers prevented the checkpoint from completing. */
+    busy: number;
+    /** Pages in the WAL file. */
+    log: number;
+    /** Pages moved into the database file. */
+    checkpointed: 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 +32,29 @@ export class SqliteDriver extends DeepBaseDriver {
     path: string;
     fileName: string;
     pragma: string;
+    busyTimeoutMs: number;
+    busyRetry: Required<SqliteBusyRetryOptions>;
+
+    /** Runs `PRAGMA integrity_check` and returns its status: `'ok'` when the
+     *  database is sound, otherwise SQLite's description of the damage. */
+    checkIntegrity(): Promise<string>;
+
+    /**
+     * Writes an online backup to `destination`, creating parent directories as
+     * needed, then verifies the copy with `integrity_check`. Resolves with
+     * `destination`, or rejects with code `DEEPBASE_SQLITE_BACKUP_CORRUPT` when
+     * the copy does not verify.
+     */
+    backup(destination: string): Promise<string>;
+
+    /** Rebuilds the database file to reclaim free pages. Takes the write lock. */
+    vacuum(): Promise<void>;
+
+    /**
+     * Runs `PRAGMA wal_checkpoint`. Rejects with code `DEEPBASE_SQLITE_NOT_WAL`
+     * when the database uses a rollback journal (`pragma: 'none'`).
+     */
+    checkpoint(mode?: SqliteCheckpointMode): Promise<SqliteCheckpointResult>;
 }
 
 export { SqliteDriver as SqliteFastDriver };

package/src/maintenance.js

@@ -0,0 +1,58 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import * as pathModule from 'path';
+
+const CHECKPOINT_MODES = ['PASSIVE', 'FULL', 'RESTART', 'TRUNCATE'];
+
+export function checkIntegrity(db) {
+  return db.pragma('integrity_check', { simple: true });
+}
+
+export async function backupTo(db, destination) {
+  fs.mkdirSync(pathModule.dirname(pathModule.resolve(destination)), { recursive: true });
+
+  await db.backup(destination);
+
+  const copy = new Database(destination, { readonly: true });
+  let status;
+  try {
+    status = checkIntegrity(copy);
+  } finally {
+    copy.close();
+  }
+
+  if (status !== 'ok') {
+    const error = new Error(
+      `deepbase-sqlite: backup verification failed for ${destination}: ${status}. ` +
+      'The corrupt file was left in place for inspection; do not restore from it.',
+    );
+    error.code = 'DEEPBASE_SQLITE_BACKUP_CORRUPT';
+    throw error;
+  }
+
+  return destination;
+}
+
+export function vacuum(db) {
+  db.exec('VACUUM');
+}
+
+export function checkpoint(db, mode) {
+  if (!CHECKPOINT_MODES.includes(mode)) {
+    throw new TypeError(
+      `deepbase-sqlite: checkpoint mode must be one of ${CHECKPOINT_MODES.join(', ')}; received ${mode}`,
+    );
+  }
+
+  if (db.pragma('journal_mode', { simple: true }) !== 'wal') {
+    const error = new Error(
+      "deepbase-sqlite: checkpoint requires journal_mode=WAL. Databases opened with pragma: 'none' " +
+      'use a rollback journal and have no WAL to checkpoint.',
+    );
+    error.code = 'DEEPBASE_SQLITE_NOT_WAL';
+    throw error;
+  }
+
+  const [result] = db.pragma(`wal_checkpoint(${mode})`);
+  return result;
+}

package/src/schema.js

@@ -0,0 +1,20 @@
+export function ensureSchema(db, { withoutRowid = '' } = {}) {
+  const setup = db.transaction(() => {
+    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 INDEX IF NOT EXISTS deepbase_seq_idx ON deepbase(seq)');
+  });
+
+  setup.immediate();
+}

package/test/fixtures.js

@@ -0,0 +1,41 @@
+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) {
+  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);
+  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();
+  db.close();
+  return { rows, indexes };
+}

package/test/test-multiprocess.js

@@ -0,0 +1,236 @@
+import assert from 'assert';
+import { fork } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+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('adds a missing seq column without rewriting legacy rows', 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: 0 },
+      { key: 'b', seq: 0 },
+    ]);
+    assert.ok(state.indexes.some(index => index.name === 'deepbase_seq_idx' && index.unique === 0));
+  });
+
+  it('preserves duplicate historical seq values and their stable key 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: 0 },
+      { key: 'b', seq: 0 },
+      { key: 'c', seq: 2 },
+      { key: 'd', seq: 2 },
+    ]);
+  });
+
+  it('serializes concurrent schema setup 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.deepStrictEqual(state.rows, [{ key: 'value', seq: 0 }]);
+    assert.ok(state.indexes.some(index => index.name === 'deepbase_seq_idx'));
+  });
+
+  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 () {
@@ -714,5 +728,127 @@ for (const pragma of PRAGMA_MODES) {
         assert.strictEqual(await db.get('inventory'), 500);
       });
     });
+
+    describe('Maintenance', function () {
+      it('reports a healthy database as ok', async function () {
+        await db.set('key', 'value');
+        assert.strictEqual(await db.getDriver(0).checkIntegrity(), 'ok');
+      });
+
+      it('backs up to a verified copy containing the data', async function () {
+        await db.set('users', 'alice', { name: 'Alice' });
+        const destination = path.join(testDataPath, 'backups', `backup-${pragma}.db`);
+
+        assert.strictEqual(await db.getDriver(0).backup(destination), destination);
+
+        const copy = new DeepBase(new SqliteDriver({
+          name: `backup-${pragma}`,
+          path: path.join(testDataPath, 'backups'),
+          pragma,
+        }));
+        assert.deepStrictEqual(await copy.get('users', 'alice'), { name: 'Alice' });
+        await copy.disconnect();
+      });
+
+      it('creates missing parent directories for the destination', async function () {
+        const destination = path.join(testDataPath, 'deep', 'nested', 'backup.db');
+        await db.getDriver(0).backup(destination);
+        assert.ok(fs.existsSync(destination));
+      });
+
+      it('includes writes made after the driver opened the connection', async function () {
+        await db.set('counter', 41);
+        await db.inc('counter', 1);
+        const destination = path.join(testDataPath, 'backups', `late-${pragma}.db`);
+        await db.getDriver(0).backup(destination);
+
+        const copy = new DeepBase(new SqliteDriver({
+          name: `late-${pragma}`,
+          path: path.join(testDataPath, 'backups'),
+          pragma,
+        }));
+        assert.strictEqual(await copy.get('counter'), 42);
+        await copy.disconnect();
+      });
+
+      it('opens the connection on demand', async function () {
+        const driver = new SqliteDriver({ name: `lazy-${pragma}`, path: testDataPath, pragma });
+        assert.strictEqual(await driver.checkIntegrity(), 'ok');
+        await driver.disconnect();
+      });
+
+      it('vacuums without losing data', async function () {
+        for (let i = 0; i < 50; i++) {
+          await db.set('users', `user${i}`, { name: `User ${i}` });
+        }
+        await db.del('users', 'user0');
+
+        await db.getDriver(0).vacuum();
+
+        assert.strictEqual(await db.get('users', 'user0'), null);
+        assert.deepStrictEqual(await db.get('users', 'user49'), { name: 'User 49' });
+        assert.strictEqual(await db.getDriver(0).checkIntegrity(), 'ok');
+      });
+
+      it('rejects an unknown checkpoint mode', async function () {
+        await assert.rejects(db.getDriver(0).checkpoint('SOMETIMES'), TypeError);
+      });
+
+      if (pragma === 'none') {
+        it('refuses to checkpoint a rollback-journal database', async function () {
+          await db.set('key', 'value');
+          await assert.rejects(
+            db.getDriver(0).checkpoint(),
+            error => error.code === 'DEEPBASE_SQLITE_NOT_WAL',
+          );
+        });
+      } else {
+        it('checkpoints the WAL back into the database file', async function () {
+          await db.set('key', 'value');
+          const result = await db.getDriver(0).checkpoint('TRUNCATE');
+          assert.strictEqual(result.busy, 0);
+          assert.strictEqual(result.log, 0, 'TRUNCATE leaves an empty WAL');
+          assert.strictEqual(await db.get('key'), 'value');
+        });
+      }
+    });
   });
 }
+
+describe('SqliteDriver backup verification', function () {
+  const corruptPath = path.join(testDataPath, 'corrupt');
+
+  afterEach(function () {
+    if (fs.existsSync(testDataPath)) {
+      fs.rmSync(testDataPath, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects when the written copy does not verify', async function () {
+    const driver = new SqliteDriver({ name: 'source', path: corruptPath });
+    for (let i = 0; i < 200; i++) {
+      await driver.set('users', `user${i}`, { name: `User ${i}` });
+    }
+
+    const destination = path.join(corruptPath, 'backup.db');
+    const originalBackup = driver.db.backup.bind(driver.db);
+    driver.db.backup = async dest => {
+      const result = await originalBackup(dest);
+      // Scribble over every page but the header, so the file still opens as a
+      // database yet fails integrity_check.
+      const handle = fs.openSync(dest, 'r+');
+      const damaged = fs.fstatSync(handle).size - 4096;
+      fs.writeSync(handle, Buffer.alloc(damaged, 0xff), 0, damaged, 4096);
+      fs.closeSync(handle);
+      return result;
+    };
+
+    await assert.rejects(
+      driver.backup(destination),
+      error => error.code === 'DEEPBASE_SQLITE_BACKUP_CORRUPT',
+    );
+    assert.ok(fs.existsSync(destination), 'corrupt copy is left in place for inspection');
+
+    await driver.disconnect();
+  });
+});

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?.();