deepbase-sqlite 3.7.0 → 3.8.1

package/README.md

@@ -82,7 +82,49 @@ const db2 = new DeepBase(new SqliteDriver({ name: 'mydb' }));
 
 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.
+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()` | 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 }`. |
+
+`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
+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
 
@@ -92,7 +134,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, 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.
+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
 
@@ -148,15 +190,10 @@ CREATE TABLE deepbase (
   seq INTEGER NOT NULL
 );
 
-CREATE UNIQUE INDEX deepbase_seq_unique ON deepbase(seq);
-
-CREATE TABLE deepbase_meta (
-  key TEXT PRIMARY KEY,
-  value INTEGER NOT NULL
-);
+CREATE INDEX deepbase_seq_idx ON deepbase(seq);
 ```
 
-`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`.
+Optimized PRAGMA profiles create `deepbase` `WITHOUT ROWID`.
 
 Example data:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepbase-sqlite",
-  "version": "3.7.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.7.0"
+    "deepbase": "^3.8.1"
   },
   "devDependencies": {
     "mocha": "^10.8.2"

package/src/SqliteDriver.js

@@ -4,7 +4,8 @@ import fs from 'fs';
 import * as pathModule from 'path';
 import { withBusyRetry } from './busy.js';
 import { resolveSqliteConfig } from './config.js';
-import { migrateSchema } from './schema.js';
+import { backupFrom, checkIntegrityAt, checkpoint, vacuum } from './maintenance.js';
+import { ensureSchema } from './schema.js';
 
 export class SqliteDriver extends DeepBaseDriver {
   constructor({ name, path, pragma, busyTimeoutMs, busyRetry, ...opts } = {}) {
@@ -61,7 +62,7 @@ export class SqliteDriver extends DeepBaseDriver {
     }
 
     const withoutRowid = cfg ? ' WITHOUT ROWID' : '';
-    migrateSchema(this.db, { withoutRowid });
+    ensureSchema(this.db, { withoutRowid });
 
     this.getStmt = this.db.prepare('SELECT value FROM deepbase WHERE key = ?');
     this.setStmt = this.db.prepare(`
@@ -122,6 +123,22 @@ export class SqliteDriver extends DeepBaseDriver {
     this._connected = true;
   }
 
+  async checkIntegrity() {
+    return checkIntegrityAt(this.fileName, this.busyTimeoutMs);
+  }
+
+  async backup(destination) {
+    return backupFrom(this.fileName, destination, this.busyTimeoutMs);
+  }
+
+  async vacuum() {
+    return this._runWrite(() => vacuum(this.db));
+  }
+
+  async checkpoint(mode = 'PASSIVE') {
+    return this._runWrite(() => checkpoint(this.db, mode));
+  }
+
   async connect() {
     if (this._connected) return;
     if (!this._connectPromise) {

package/src/config.js

@@ -25,7 +25,6 @@ const PRAGMA_PROFILES = Object.freeze({
 
 export const SQLITE_CONFIG = Object.freeze({
   defaultPragma: 'balanced',
-  schemaVersion: 1,
   busyTimeoutMs: 5000,
   busyRetry: Object.freeze({
     maxAttempts: 2,

package/src/index.d.ts

@@ -6,6 +6,17 @@ export interface SqliteBusyRetryOptions {
     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;
@@ -23,6 +34,27 @@ export class SqliteDriver extends DeepBaseDriver {
     pragma: string;
     busyTimeoutMs: number;
     busyRetry: Required<SqliteBusyRetryOptions>;
+
+    /** Opens the existing database read-only, runs `PRAGMA integrity_check`,
+     *  then closes it. Does not connect or mutate the driver database. */
+    checkIntegrity(): Promise<string>;
+
+    /**
+     * 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>;
+
+    /** 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,72 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import * as pathModule from 'path';
+
+const CHECKPOINT_MODES = ['PASSIVE', 'FULL', 'RESTART', 'TRUNCATE'];
+
+function checkIntegrity(db) {
+  return db.pragma('integrity_check', { simple: true });
+}
+
+function openReadonly(fileName, timeout) {
+  return new Database(fileName, {
+    readonly: true,
+    fileMustExist: true,
+    timeout,
+  });
+}
+
+export function checkIntegrityAt(fileName, timeout) {
+  const db = openReadonly(fileName, timeout);
+  try {
+    return checkIntegrity(db);
+  } finally {
+    db.close();
+  }
+}
+
+export async function backupFrom(fileName, destination, timeout) {
+  const source = openReadonly(fileName, timeout);
+  try {
+    fs.mkdirSync(pathModule.dirname(pathModule.resolve(destination)), { recursive: true });
+    await source.backup(destination);
+  } finally {
+    source.close();
+  }
+
+  const status = checkIntegrityAt(destination, timeout);
+  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

@@ -1,79 +1,20 @@
-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);
+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 UNIQUE INDEX IF NOT EXISTS deepbase_seq_unique ON deepbase(seq)');
+    db.exec('CREATE INDEX IF NOT EXISTS deepbase_seq_idx ON deepbase(seq)');
   });
 
-  migration.immediate();
+  setup.immediate();
 }

package/test/fixtures.js

@@ -13,7 +13,7 @@ export function createLegacyDatabase(fileName, rows) {
   db.close();
 }
 
-export function createSequencedDatabase(fileName, rows, { failMigration = false } = {}) {
+export function createSequencedDatabase(fileName, rows) {
   const db = new Database(fileName);
   db.exec(`
     CREATE TABLE deepbase (
@@ -29,16 +29,6 @@ export function createSequencedDatabase(fileName, rows, { failMigration = false
     }
   });
   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();
 }
 
@@ -46,12 +36,6 @@ 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 };
+  return { rows, indexes };
 }

package/test/test-multiprocess.js

@@ -3,7 +3,6 @@ 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';
 
@@ -93,7 +92,7 @@ describe('SqliteDriver multi-process safety', function () {
     await driver.disconnect();
   });
 
-  it('migrates a legacy database without seq and preserves observable order', async function () {
+  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]]);
@@ -104,14 +103,13 @@ describe('SqliteDriver multi-process safety', function () {
 
     const state = inspectDatabase(fileName);
     assert.deepStrictEqual(state.rows, [
-      { key: 'a', seq: 1 },
-      { key: 'b', seq: 2 },
+      { key: 'a', seq: 0 },
+      { key: 'b', seq: 0 },
     ]);
-    assert.strictEqual(state.schemaVersion, 1);
-    assert.ok(state.indexes.some(index => index.name === 'deepbase_seq_unique' && index.unique === 1));
+    assert.ok(state.indexes.some(index => index.name === 'deepbase_seq_idx' && index.unique === 0));
   });
 
-  it('normalizes duplicate seq values without changing their current order', async function () {
+  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, [
@@ -126,41 +124,14 @@ describe('SqliteDriver multi-process safety', function () {
     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 },
+      { key: 'c', seq: 2 },
+      { key: 'd', seq: 2 },
     ]);
   });
 
-  it('serializes concurrent schema migration across processes', async function () {
+  it('serializes concurrent schema setup across processes', async function () {
     const name = 'concurrent-migration';
     const fileName = path.join(testDataPath, `${name}.db`);
     createLegacyDatabase(fileName, [['value', 1]]);
@@ -176,8 +147,8 @@ describe('SqliteDriver multi-process safety', function () {
     ));
 
     const state = inspectDatabase(fileName);
-    assert.strictEqual(state.schemaVersion, 1);
-    assert.deepStrictEqual(state.rows, [{ key: 'value', seq: 1 }]);
+    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 () {

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';
@@ -728,5 +729,150 @@ 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('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 () {
+        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 = 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+');
+      const damaged = fs.fstatSync(handle).size - 4096;
+      fs.writeSync(handle, Buffer.alloc(damaged, 0xff), 0, damaged, 4096);
+      fs.closeSync(handle);
+      return result;
+    };
+
+    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();
+  });
+});