deepbase-sqlite 3.8.0 → 3.8.1

package/README.md

@@ -102,12 +102,16 @@ 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`. |
+| `checkIntegrity()` | Read-only `PRAGMA integrity_check`; returns its status verbatim. |
+| `backup(destination)` | Read-only source, 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
+`checkIntegrity()` and `backup()` open a temporary read-only connection with
+`fileMustExist: true`, then close it. They never create, migrate, or change
+PRAGMAs on the source database; a missing or mistyped source path fails instead
+of producing an empty database. `backup()` creates destination parent
+directories only after opening the source, then reopens the result read-only 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

package/package.json

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

package/src/SqliteDriver.js

@@ -4,7 +4,7 @@ import fs from 'fs';
 import * as pathModule from 'path';
 import { withBusyRetry } from './busy.js';
 import { resolveSqliteConfig } from './config.js';
-import { backupTo, checkIntegrity, checkpoint, vacuum } from './maintenance.js';
+import { backupFrom, checkIntegrityAt, checkpoint, vacuum } from './maintenance.js';
 import { ensureSchema } from './schema.js';
 
 export class SqliteDriver extends DeepBaseDriver {
@@ -124,13 +124,11 @@ export class SqliteDriver extends DeepBaseDriver {
   }
 
   async checkIntegrity() {
-    await this.connect();
-    return checkIntegrity(this.db);
+    return checkIntegrityAt(this.fileName, this.busyTimeoutMs);
   }
 
   async backup(destination) {
-    await this.connect();
-    return backupTo(this.db, destination);
+    return backupFrom(this.fileName, destination, this.busyTimeoutMs);
   }
 
   async vacuum() {

package/src/index.d.ts

@@ -35,15 +35,15 @@ export class SqliteDriver extends DeepBaseDriver {
     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. */
+    /** Opens the existing database read-only, runs `PRAGMA integrity_check`,
+     *  then closes it. Does not connect or mutate the driver database. */
     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.
+     * Opens the existing source database read-only, writes an online backup to
+     * `destination`, 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>;
 

package/src/maintenance.js

@@ -4,23 +4,37 @@ import * as pathModule from 'path';
 
 const CHECKPOINT_MODES = ['PASSIVE', 'FULL', 'RESTART', 'TRUNCATE'];
 
-export function checkIntegrity(db) {
+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 });
+function openReadonly(fileName, timeout) {
+  return new Database(fileName, {
+    readonly: true,
+    fileMustExist: true,
+    timeout,
+  });
+}
 
-  await db.backup(destination);
+export function checkIntegrityAt(fileName, timeout) {
+  const db = openReadonly(fileName, timeout);
+  try {
+    return checkIntegrity(db);
+  } finally {
+    db.close();
+  }
+}
 
-  const copy = new Database(destination, { readonly: true });
-  let status;
+export async function backupFrom(fileName, destination, timeout) {
+  const source = openReadonly(fileName, timeout);
   try {
-    status = checkIntegrity(copy);
+    fs.mkdirSync(pathModule.dirname(pathModule.resolve(destination)), { recursive: true });
+    await source.backup(destination);
   } finally {
-    copy.close();
+    source.close();
   }
 
+  const status = checkIntegrityAt(destination, timeout);
   if (status !== 'ok') {
     const error = new Error(
       `deepbase-sqlite: backup verification failed for ${destination}: ${status}. ` +

package/test/test.js

@@ -1,4 +1,5 @@
 import assert from 'assert';
+import Database from 'better-sqlite3';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -771,10 +772,29 @@ for (const pragma of PRAGMA_MODES) {
         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');
+      it('uses a temporary readonly connection', async function () {
+        await db.set('key', 'value');
+        const driver = db.getDriver(0);
         await driver.disconnect();
+
+        assert.strictEqual(await driver.checkIntegrity(), 'ok');
+        assert.strictEqual(driver._connected, false);
+        assert.strictEqual(driver.db, null);
+      });
+
+      it('does not create a missing source database or backup directory', async function () {
+        const driver = new SqliteDriver({
+          name: `missing-${pragma}`,
+          path: path.join(testDataPath, 'missing'),
+          pragma,
+        });
+        const destination = path.join(testDataPath, 'should-not-exist', 'backup.db');
+
+        await assert.rejects(driver.checkIntegrity());
+        await assert.rejects(driver.backup(destination));
+
+        assert.strictEqual(fs.existsSync(driver.fileName), false);
+        assert.strictEqual(fs.existsSync(path.dirname(destination)), false);
       });
 
       it('vacuums without losing data', async function () {
@@ -831,9 +851,9 @@ describe('SqliteDriver backup verification', function () {
     }
 
     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);
+    const originalBackup = Database.prototype.backup;
+    Database.prototype.backup = async function (dest, ...args) {
+      const result = await originalBackup.call(this, dest, ...args);
       // 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+');
@@ -843,10 +863,14 @@ describe('SqliteDriver backup verification', function () {
       return result;
     };
 
-    await assert.rejects(
-      driver.backup(destination),
-      error => error.code === 'DEEPBASE_SQLITE_BACKUP_CORRUPT',
-    );
+    try {
+      await assert.rejects(
+        driver.backup(destination),
+        error => error.code === 'DEEPBASE_SQLITE_BACKUP_CORRUPT',
+      );
+    } finally {
+      Database.prototype.backup = originalBackup;
+    }
     assert.ok(fs.existsSync(destination), 'corrupt copy is left in place for inspection');
 
     await driver.disconnect();