@jarenjs/db 0.49.2 → 0.66.1

package/src/drivers/bun.js

@@ -20,6 +20,7 @@
 
 import { lazyOpen, openConnection } from '../driver.js';
 import { sqliteDialect } from '../dialects/sqlite.js';
+import { PRAGMA_NAMES } from '../pragmas.js';
 
 /**
  * Adapt an already-constructed `bun:sqlite` `Database` (or any object
@@ -30,12 +31,23 @@ import { sqliteDialect } from '../dialects/sqlite.js';
  * @returns {any} a Connection, or a promise of one
  */
 export function adaptBunDatabase(db, options) {
+  // Bun closes its query cache, but prepare() creates uncached statements
+  // that keep the SQLite file open until finalized. Track only weak
+  // references: a long-lived connection must not retain every past query.
+  /** @type {Set<WeakRef<any>>} */
+  const statements = new Set();
+  const collected = new FinalizationRegistry((ref) => statements.delete(ref));
   const raw = {
     /** @param {string} sql */
     exec: (sql) => db.run(sql),
     /** @param {string} sql */
     prepare: (sql) => {
       const statement = db.prepare(sql);
+      if (typeof statement.finalize === 'function') {
+        const ref = new WeakRef(statement);
+        statements.add(ref);
+        collected.register(statement, ref, ref);
+      }
       return {
         run: (params = []) => statement.run(...params),
         // the driver contract says a missing row reads UNDEFINED;
@@ -51,7 +63,28 @@ export function adaptBunDatabase(db, options) {
           : undefined),
       };
     },
-    close: () => db.close(),
+    close: () => {
+      const errors = [];
+      for (const ref of statements) {
+        collected.unregister(ref);
+        try {
+          ref.deref()?.finalize();
+        }
+        catch (error) {
+          errors.push(error);
+        }
+      }
+      statements.clear();
+      try {
+        db.close();
+      }
+      catch (error) {
+        errors.push(error);
+      }
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1)
+        throw new AggregateError(errors, 'finalizing Bun statements and closing the database failed');
+    },
   };
   return openConnection(raw, {
     dialect: sqliteDialect,
@@ -62,6 +95,9 @@ export function adaptBunDatabase(db, options) {
       userFunctions: false,
       deterministicIndexableFunctions: false,
       aggregateFunctions: false,
+      // the configuration pragmas are the library's, not the binding's:
+      // bun:sqlite applies every one of the closed set
+      pragmas: PRAGMA_NAMES,
     },
   });
 }

package/src/drivers/indexeddb-snapshot.js

@@ -0,0 +1,149 @@
+//@ts-check
+/** Atomic, versioned SQLite snapshots. IndexedDB is storage, never an OPFS VFS. */
+import { DbRuntimeError, sqliteResultError } from '../errors.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+import { adaptOo1Database } from './wasm-oo1.js';
+
+/** @param {any} factory @param {string} name @returns {Promise<any>} */
+export function openSnapshotStorage(factory, name) {
+  return new Promise((resolve, reject) => {
+    if (typeof factory?.open !== 'function') { reject(new Error('IndexedDB is unavailable')); return; }
+    const request = factory.open(name, 1);
+    let blocked = false;
+    request.onupgradeneeded = () => { request.result.createObjectStore('snapshots'); };
+    request.onerror = () => reject(request.error);
+    request.onblocked = () => { blocked = true; reject(new Error('the IndexedDB snapshot database upgrade is blocked')); };
+    request.onsuccess = () => {
+      const db = request.result;
+      if (blocked) { db.close(); return; }
+      db.onversionchange = () => db.close();
+      const transact = (key, write, bytes, expected) => new Promise((yes, no) => {
+        const tx = db.transaction('snapshots', write ? 'readwrite' : 'readonly');
+        const store = tx.objectStore('snapshots');
+        let result;
+        let failure;
+        const read = store.get(key);
+        read.onsuccess = () => {
+          try {
+            const old = read.result;
+            if (!write) { result = old ?? null; return; }
+            if ((old?.revision ?? 0) !== expected) {
+              failure = new Error('the durable snapshot changed in another connection');
+              tx.abort();
+              return;
+            }
+            result = expected + 1;
+            if (bytes === null) store.delete(key);
+            else store.put({ revision: result, bytes }, key);
+          }
+          catch (error) { failure = error; tx.abort(); }
+        };
+        tx.oncomplete = () => yes(result);
+        tx.onabort = () => no(failure ?? tx.error ?? new Error('the snapshot transaction was aborted'));
+      });
+      resolve({
+        read: (key) => transact(key, false),
+        write: (key, bytes, revision) => transact(key, true, bytes, revision),
+        remove: async (key) => { const old = await transact(key, false); return transact(key, true, null, old?.revision ?? 0); },
+        close: () => db.close(),
+      });
+    };
+  });
+}
+
+/** Build an async binding over a synchronous wasm handle plus atomic storage.
+ * @param {any} sqlite3
+ * @param {{ openStorage: () => Promise<any>, maxBytes?: number }} options
+ * @returns {any}
+ */
+export function snapshotHandle(sqlite3, options) {
+  const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new TypeError('snapshot maxBytes must be a positive integer');
+  return {
+    synchronous: false,
+    declares: { sessions: true, userFunctions: true, deterministicIndexableFunctions: true },
+    open: async (path, openOptions = {}) => {
+      const memory = path === ':memory:' || path === '';
+      const storage = memory ? null : await options.openStorage();
+      let db;
+      try {
+        const saved = await storage?.read(path);
+        if (saved != null && (!Number.isSafeInteger(saved.revision) || saved.revision < 1
+          || !(saved.bytes instanceof Uint8Array) || saved.bytes.length < 1 || saved.bytes.length > maxBytes))
+          throw new DbRuntimeError('JD2094', 'the persisted SQLite snapshot is invalid or exceeds its declared byte bound');
+        let revision = saved?.revision ?? 0;
+        db = new sqlite3.oo1.DB(':memory:');
+        const { capi, wasm } = sqlite3;
+        if (saved?.bytes?.length > 0) {
+          if (!(saved.bytes instanceof Uint8Array) || saved.bytes.length > maxBytes)
+            throw new DbRuntimeError('JD2094', 'the persisted SQLite snapshot exceeds its declared byte bound');
+          const pointer = wasm.allocFromTypedArray(saved.bytes);
+          const rc = capi.sqlite3_deserialize(db.pointer, 'main', pointer,
+            BigInt(saved.bytes.length), BigInt(saved.bytes.length),
+            capi.SQLITE_DESERIALIZE_FREEONCLOSE | capi.SQLITE_DESERIALIZE_RESIZEABLE);
+          if (rc !== 0) { wasm.dealloc(pointer); throw sqliteResultError(rc, 'snapshot deserialize'); }
+        }
+        if (openOptions.readOnly === true) db.exec(sqliteDialect.pragma.set('query_only', 1));
+        const raw = adaptOo1Database(sqlite3, db);
+        let poisoned = null;
+        const requireUsable = () => { if (poisoned !== null) throw poisoned; };
+        const persist = async () => {
+          if (storage === null || openOptions.readOnly === true || !capi.sqlite3_get_autocommit(db.pointer)) return;
+          try {
+            const pages = db.selectValue(sqliteDialect.introspect.pragma('page_count'));
+            const pageSize = db.selectValue(sqliteDialect.introspect.pragma('page_size'));
+            if (pages * pageSize > maxBytes) throw new Error(`snapshot exceeds ${maxBytes} bytes`);
+            const bytes = capi.sqlite3_js_db_export(db.pointer);
+            if (bytes.length > maxBytes) throw new Error(`snapshot exceeds ${maxBytes} bytes`);
+            revision = await storage.write(path, bytes, revision);
+          }
+          catch (cause) {
+            poisoned = Object.assign(new DbRuntimeError('JD2094',
+              'the durable snapshot was not committed; this connection is invalid; reopen to read the last committed version',
+              { cause }), { retryable: false, class: 'persistence' });
+            throw poisoned;
+          }
+        };
+        return {
+          ...raw,
+          exec: async (sql) => { requireUsable(); raw.exec(sql); await persist(); },
+          prepare: (sql) => {
+            requireUsable();
+            const statement = raw.prepare(sql);
+            const invoke = (member, params) => {
+              requireUsable();
+              const value = statement[member](params);
+              return statement.readOnly ? value : persist().then(() => value);
+            };
+            return {
+              run: (params = []) => invoke('run', params),
+              get: (params = []) => invoke('get', params),
+              all: (params = []) => invoke('all', params),
+              iterate: (params = []) => {
+                requireUsable();
+                const iterator = statement.iterate(params);
+                return {
+                  next: async () => { requireUsable(); const step = iterator.next(); if (!statement.readOnly) await persist(); return step; },
+                  return: async () => { const step = iterator.return(); if (!statement.readOnly && poisoned === null) await persist(); return step; },
+                };
+              },
+            };
+          },
+          close: () => { try { raw.close(); } finally { storage?.close(); } },
+        };
+      }
+      catch (error) { db?.close(); storage?.close(); throw error; }
+    },
+  };
+}
+
+/** IndexedDB durability via bounded atomic snapshots, with async acknowledgements.
+ * @param {any} sqlite3
+ * @param {{ name?: string, indexedDB?: any, maxBytes?: number }} [options]
+ * @returns {any} an injected wasm handle
+ */
+export function indexedDbSnapshotHandle(sqlite3, options = {}) {
+  return snapshotHandle(sqlite3, { maxBytes: options.maxBytes,
+    openStorage: () => openSnapshotStorage(options.indexedDB ?? globalThis.indexedDB,
+      options.name ?? 'jaren-sqlite-snapshots') });
+}

package/src/drivers/node-pool.js

@@ -0,0 +1,11 @@
+//@ts-check
+import { nodeWorkerDriver } from './node-worker.js';
+import { workerPoolDriver } from './worker-pool.js';
+
+/** One writer and bounded read-only WAL workers behind the Connection contract.
+ * @param {{readers?:number, queueCapacity?:number, graceMs?:number, worker?:any}} [options]
+ * @returns {any}
+ */
+export function nodeWorkerPoolDriver(options = {}) {
+  return workerPoolDriver(options, nodeWorkerDriver);
+}

package/src/drivers/node-worker-endpoint.js

@@ -0,0 +1,105 @@
+//@ts-check
+/** One worker owns one SQLite handle. Only bounded credit frames carry rows. */
+import { parentPort, workerData } from 'node:worker_threads';
+import { nodeDriver } from './node.js';
+import { DbRuntimeError, cloneDriverError } from '../errors.js';
+import { validRequest, generationFailure, rowBytes } from './worker-protocol.js';
+
+const { generation, path, options, limits } = workerData;
+let connection;
+let sequence = 0;
+const statements = new Map();
+const cursors = new Map();
+const frame = (kind, id, value) => ({ v: 1, generation, kind, id, ...value });
+const bound = (reason) => new DbRuntimeError('JD2092', reason);
+const release = (id) => {
+  const cursor = cursors.get(id);
+  if (cursor === undefined) return;
+  cursors.delete(id);
+  cursor.iterator.return?.();
+  if (cursor.ephemeral) statements.delete(cursor.statement);
+};
+const statementOf = (id) => {
+  const statement = statements.get(id);
+  if (statement === undefined) throw generationFailure(generation);
+  return statement;
+};
+const dispatch = (request) => {
+  switch (request.op) {
+    case 'exec': return connection.exec(request.sql);
+    case 'prepare': {
+      if (statements.size >= limits.statements) throw bound(`worker statement capacity ${limits.statements} exceeded`);
+      const id = ++sequence;
+      statements.set(id, { statement: connection.prepare(request.sql), ephemeral: request.ephemeral === true });
+      return id;
+    }
+    case 'get': {
+      const row = statementOf(request.statement).statement.get(request.params);
+      if (rowBytes(row) > limits.bytes) throw bound(`one worker row exceeds ${limits.bytes} bytes`);
+      return row;
+    }
+    case 'run': return statementOf(request.statement).statement.run(request.params);
+    case 'iterate': {
+      if (cursors.size >= limits.cursors) throw bound(`worker cursor capacity ${limits.cursors} exceeded`);
+      const record = statementOf(request.statement);
+      const id = ++sequence;
+      cursors.set(id, { iterator: record.statement.iterate(request.params),
+        statement: request.statement, ephemeral: record.ephemeral, buffered: null });
+      return id;
+    }
+    case 'next': {
+      const cursor = cursors.get(request.cursor);
+      if (cursor === undefined) throw generationFailure(generation);
+      if (request.rows > limits.rows || request.bytes > limits.bytes) throw bound('worker cursor credit exceeds the negotiated window');
+      const rows = [];
+      let bytes = 0;
+      try {
+        while (rows.length < request.rows) {
+          const step = cursor.buffered ?? cursor.iterator.next();
+          cursor.buffered = null;
+          if (step.done) { release(request.cursor); return { rows, bytes, done: true }; }
+          const size = rowBytes(step.value);
+          if (size > request.bytes) throw bound(`one worker row of ${size} bytes exceeds the ${request.bytes} byte window`);
+          if (bytes + size > request.bytes) { cursor.buffered = step; break; }
+          rows.push(step.value);
+          bytes += size;
+        }
+        return { rows, bytes, done: false };
+      }
+      catch (error) { release(request.cursor); throw error; }
+    }
+    case 'return': release(request.cursor); return undefined;
+    case 'finalize': {
+      for (const [id, cursor] of cursors) if (cursor.statement === request.statement) release(id);
+      statements.delete(request.statement);
+      return undefined;
+    }
+    case 'close': {
+      for (const id of cursors.keys()) release(id);
+      statements.clear();
+      return connection.close();
+    }
+  }
+};
+try {
+  connection = await nodeDriver().open(path, options);
+  // Functions cannot cross structured clone. Capture uses the existing
+  // journal path; a live query requires a synchronous connection.
+  parentPort.postMessage(frame('ready', 0, { capabilities: { ...connection.capabilities,
+    sessions: false, userFunctions: false, deterministicIndexableFunctions: false,
+    aggregateFunctions: false, backup: false, worker: true, pooling: false } }));
+  parentPort.on('message', (request) => {
+    try {
+      if (!validRequest(request)) throw new DbRuntimeError('JD2093', 'invalid worker protocol request');
+      if (request.generation !== generation) throw generationFailure(request.generation);
+      const value = dispatch(request);
+      parentPort.postMessage(frame('result', request.id, { value }));
+      if (request.op === 'close') parentPort.close();
+    }
+    catch (error) { parentPort.postMessage(frame('failure', request?.id ?? 0, { error: cloneDriverError(error) })); }
+  });
+}
+catch (error) {
+  parentPort.postMessage(frame('failure', 0, { error: cloneDriverError(error) }));
+  parentPort.close();
+}

package/src/drivers/node-worker.js

@@ -0,0 +1,204 @@
+//@ts-check
+/** A worker transport behind the ordinary Connection contract. */
+import { finishConnection, lazyOpen } from '../driver.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+import { DbRuntimeError } from '../errors.js';
+import { generationFailure, positiveOption, queueFailure, rowBytes, validResponse, validResult } from './worker-protocol.js';
+
+/** Dedicated SQLite worker per connection. No function serialization or write replay.
+ * @param {{ windowRows?: number, windowBytes?: number, maxPending?: number,
+ *   maxStatements?: number, maxCursors?: number, allMaxRows?: number,
+ *   allMaxBytes?: number, closeTimeoutMs?: number, startupTimeoutMs?: number }} [configuration]
+ * @returns {any} a Driver
+ */
+export function nodeWorkerDriver(configuration = {}) {
+  const limits = {
+    rows: positiveOption('windowRows', configuration.windowRows, 64),
+    bytes: positiveOption('windowBytes', configuration.windowBytes, 1024 * 1024),
+    statements: positiveOption('maxStatements', configuration.maxStatements, 1024),
+    cursors: positiveOption('maxCursors', configuration.maxCursors, 64),
+  };
+  const maxPending = positiveOption('maxPending', configuration.maxPending, 64);
+  const allRows = positiveOption('allMaxRows', configuration.allMaxRows, 100000);
+  const allBytes = positiveOption('allMaxBytes', configuration.allMaxBytes, 16 * 1024 * 1024);
+  const closeMs = positiveOption('closeTimeoutMs', configuration.closeTimeoutMs, 5000);
+  const startupMs = positiveOption('startupTimeoutMs', configuration.startupTimeoutMs, 10000);
+  let generation = 0;
+  const driver = {
+    name: 'node-worker-sqlite', dialect: sqliteDialect,
+    open: (path = ':memory:', options = {}) => lazyOpen('node:worker_threads',
+      'Node worker threads are unavailable on this runtime', async ({ Worker }) => {
+        const epoch = ++generation;
+        const worker = new Worker(new URL('./node-worker-endpoint.js', import.meta.url), {
+          workerData: { path, options: { timeout: options.timeout, readOnly: options.readOnly }, generation: epoch, limits },
+          // Parent --test/--input-type/preloads do not describe the endpoint.
+          execArgv: ['--no-warnings=ExperimentalWarning'],
+        });
+        const pending = new Map();
+        let sequence = 0;
+        let failed = null;
+        let closing = false;
+        let closed = false;
+        let transactionDepth = 0;
+        let closePromise;
+        const metrics = { frames: 0, rows: 0, maxFrameRows: 0, maxFrameBytes: 0, maxPending: 0 };
+        let readyResolve;
+        let readyReject;
+        const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+        const lose = (cause) => {
+          if (failed !== null || closed) return;
+          failed = generationFailure(epoch, transactionDepth > 0, cause);
+          readyReject(failed);
+          for (const request of pending.values()) request.reject(failed);
+          pending.clear();
+        };
+        worker.on('error', lose);
+        worker.on('exit', (code) => { if (!closed) lose(new Error(`worker exited (${code})`)); });
+        worker.on('message', (message) => {
+          if (!validResponse(message, epoch)) { lose(new Error('invalid worker response')); return; }
+          if (message.kind === 'ready') { readyResolve(message.capabilities); return; }
+          if (message.kind === 'failure' && message.id === 0) {
+            readyReject(Object.assign(new Error(message.error.message), message.error)); return;
+          }
+          const request = pending.get(message.id);
+          if (request === undefined) return;
+          pending.delete(message.id);
+          if (message.kind === 'failure') {
+            const error = message.error;
+            request.reject(Object.assign(error.code?.startsWith('JD')
+              ? new DbRuntimeError(error.code, error.message) : new Error(error.message), error));
+          }
+          else if (message.kind === 'result' && validResult(request.op, message.value, limits)) request.resolve(message.value);
+          else { request.reject(generationFailure(epoch, transactionDepth > 0)); lose(new Error('invalid worker response')); }
+        });
+        const timer = setTimeout(() => { lose(new Error('worker startup timed out')); worker.terminate(); }, startupMs);
+        let capabilities;
+        try { capabilities = await ready; }
+        catch (error) { await worker.terminate(); throw error; }
+        finally { clearTimeout(timer); }
+        const request = (op, data = {}, cleanup = false) => {
+          if (failed !== null) return Promise.reject(failed);
+          if (closed || (closing && !cleanup)) return Promise.reject(new DbRuntimeError('JD2063', 'the worker connection is closing or closed'));
+          if (!cleanup && pending.size >= maxPending)
+            return Promise.reject(queueFailure(`worker request capacity ${maxPending} exceeded`, pending.size));
+          // One return per live cursor and one close have reserved capacity.
+          if (cleanup && pending.size >= maxPending + limits.cursors + 1)
+            return Promise.reject(queueFailure('worker cleanup capacity exceeded', pending.size));
+          const id = ++sequence;
+          return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject, op });
+            metrics.maxPending = Math.max(metrics.maxPending, pending.size);
+            try { worker.postMessage({ v: 1, generation: epoch, kind: 'request', id, op, ...data }); }
+            catch (error) { pending.delete(id); reject(error); }
+          });
+        };
+        const raw = {
+          closeDrainsIterators: true,
+          exec: (sql) => {
+            if (/^(?:SAVEPOINT|BEGIN)\b/.test(sql)) transactionDepth++;
+            return request('exec', { sql }).then((value) => {
+              if (/^RELEASE\b/.test(sql)) transactionDepth = Math.max(0, transactionDepth - 1);
+              if (/^(?:COMMIT|ROLLBACK(?! TO))\b/.test(sql)) transactionDepth = 0;
+              return value;
+            });
+          },
+          prepare: async (sql, metadata = {}) => {
+            const id = await request('prepare', { sql, ephemeral: metadata.ephemeral === true });
+            const iterate = async (params = []) => {
+              const cursor = await request('iterate', { statement: id, params });
+              let rows = [];
+              let at = 0;
+              let done = false;
+              let returned = false;
+              let pulling = Promise.resolve();
+              const next = async () => {
+                if (failed !== null) throw failed;
+                if (returned) return { done: true, value: undefined };
+                if (at < rows.length) return { done: false, value: rows[at++] };
+                if (done) return { done: true, value: undefined };
+                const batch = await request('next', { cursor, rows: limits.rows, bytes: limits.bytes });
+                metrics.frames++;
+                metrics.rows += batch.rows.length;
+                metrics.maxFrameRows = Math.max(metrics.maxFrameRows, batch.rows.length);
+                metrics.maxFrameBytes = Math.max(metrics.maxFrameBytes, batch.bytes);
+                if (returned) return { done: true, value: undefined };
+                rows = batch.rows;
+                at = 0;
+                done = batch.done;
+                return at < rows.length ? { done: false, value: rows[at++] } : { done: true, value: undefined };
+              };
+              return {
+                next: () => {
+                  const result = pulling.then(next);
+                  pulling = result.then(() => undefined, () => undefined);
+                  return result;
+                },
+                return: async () => {
+                  if (returned) return { done: true, value: undefined };
+                  returned = true;
+                  rows = [];
+                  if (!done) await request('return', { cursor }, true);
+                  return { done: true, value: undefined };
+                },
+              };
+            };
+            return {
+              run: (params = []) => request('run', { statement: id, params }),
+              get: (params = []) => request('get', { statement: id, params }),
+              iterate,
+              all: async (params = []) => {
+                const iterator = await iterate(params);
+                const rows = [];
+                let bytes = 0;
+                try {
+                  for (;;) {
+                    const step = await iterator.next();
+                    if (step.done) return rows;
+                    bytes += rowBytes(step.value);
+                    if (rows.length >= allRows || bytes > allBytes)
+                      throw new DbRuntimeError('JD2092', `worker all() exceeds its ${allRows} row / ${allBytes} byte bound; use a cursor`);
+                    rows.push(step.value);
+                  }
+                }
+                finally { await iterator.return(); }
+              },
+            };
+          },
+          close: () => {
+            if (closePromise !== undefined) return closePromise;
+            closing = true;
+            closePromise = new Promise((resolve, reject) => {
+              const timeout = setTimeout(() => {
+                lose(new Error('worker close timed out'));
+                // V8 termination cannot preempt a synchronous native SQLite
+                // call. Fence and detach now; never hold the caller's deadline
+                // hostage to that native call or claim it was rolled back.
+                worker.unref();
+                worker.terminate().catch(() => {});
+                reject(failed);
+              }, closeMs);
+              request('close', {}, true).then(() => {
+                closed = true;
+                clearTimeout(timeout);
+                worker.terminate().then(() => resolve(undefined), reject);
+              }, (error) => {
+                clearTimeout(timeout);
+                worker.unref();
+                worker.terminate().catch(() => {});
+                reject(error);
+              });
+            });
+            return closePromise;
+          },
+        };
+        const connection = finishConnection(raw, sqliteDialect, false, Object.freeze(capabilities), options.queueTimeout);
+        return Object.freeze({ ...connection,
+          get mustQueue() { return connection.mustQueue; },
+          generation: epoch,
+          metrics: () => Object.freeze({ ...metrics, pending: pending.size, generation: epoch, healthy: failed === null && !closed }),
+          restart: async () => { lose(new Error('worker restarted')); await worker.terminate(); return driver.open(path, options); },
+        });
+      }, []),
+  };
+  return Object.freeze(driver);
+}

package/src/drivers/node.js

@@ -8,17 +8,23 @@
 
 import { lazyOpen, openConnection } from '../driver.js';
 import { sqliteDialect } from '../dialects/sqlite.js';
+import { PRAGMA_NAMES } from '../pragmas.js';
 
 /**
  * Adapt an already-constructed `node:sqlite` `DatabaseSync` (or any
  * object with its shape) into a probed connection. Exported so the
  * adapter is exercisable without the builtin.
  * @param {any} db - A `DatabaseSync`-shaped database
- * @param {{ queueTimeout?: number }} [options]
+ * @param {{ queueTimeout?: number,
+ *   backup?: { copy: Function, rename: Function, remove: Function } }} [options]
+ *   - `backup` is the online-backup primitive triple (the module-level
+ *   `backup()` over this database, plus a rename and a removal); the
+ *   connection declares the capability exactly when it is given
  * @returns {any} a Connection, or a promise of one
  */
 export function adaptNodeDatabase(db, options) {
   const raw = {
+    ...(options?.backup !== undefined ? { backup: options.backup } : undefined),
     /** @param {string} sql */
     exec: (sql) => db.exec(sql),
     /** @param {string} sql */
@@ -32,11 +38,17 @@ export function adaptNodeDatabase(db, options) {
       };
     },
     close: () => db.close(),
-    registerFunction: (name, options, fn) => db.function(name, options, fn),
-    registerAggregate: (name, spec) => db.aggregate(name, spec),
-    session: (table) => (table === undefined
-      ? db.createSession()
-      : db.createSession({ table })),
+    // each optional primitive is exposed only when the HANDLE has it, so
+    // a substitute that carries less than `node:sqlite` reports less —
+    // a declared capability the handle cannot honour is a TypeError at
+    // the first call instead of a `false` the planner can read
+    ...(typeof db.function === 'function'
+      ? { registerFunction: (name, options, fn) => db.function(name, options, fn) } : undefined),
+    ...(typeof db.aggregate === 'function'
+      ? { registerAggregate: (name, spec) => db.aggregate(name, spec) } : undefined),
+    ...(typeof db.createSession === 'function'
+      ? { session: (table) => (table === undefined
+        ? db.createSession() : db.createSession({ table })) } : undefined),
   };
   return openConnection(raw, {
     dialect: sqliteDialect,
@@ -47,6 +59,11 @@ export function adaptNodeDatabase(db, options) {
       userFunctions: true,
       deterministicIndexableFunctions: true,
       aggregateFunctions: true,
+      // every configuration pragma of the closed set: a core SQLite
+      // library applies them all, and the read-back catches a build
+      // that compiled one out
+      pragmas: PRAGMA_NAMES,
+      backup: options?.backup !== undefined,
     },
   });
 }
@@ -69,7 +86,18 @@ export function fromNodeModule(mod, path, options) {
   const db = Object.keys(open).length > 0
     ? new mod.DatabaseSync(path, open)
     : new mod.DatabaseSync(path);
-  return adaptNodeDatabase(db, options);
+  // the online-backup primitives: the module's own `backup()` over this
+  // database, and the file system's rename and removal — imported
+  // lazily on first use, never at module scope, for the same reason the
+  // builtin itself is
+  const backup = typeof mod.backup === 'function'
+    ? {
+      copy: (target, backupOptions) => mod.backup(db, target, backupOptions),
+      rename: (from, to) => import('node:fs/promises').then((fs) => fs.rename(from, to)),
+      remove: (target) => import('node:fs/promises').then((fs) => fs.rm(target, { force: true })),
+    }
+    : undefined;
+  return adaptNodeDatabase(db, backup === undefined ? options : { ...options, backup });
 }
 
 /**
@@ -91,3 +119,9 @@ export function nodeDriver() {
       fromNodeModule, [path, options]),
   });
 }
+
+export {
+  readDocuments, readJsonDocuments, readJsonlDocuments,
+  openAtomicTarget, openStreamTarget, openNullTarget,
+  formatOf, DOCUMENT_FORMATS,
+} from '../document-files.js';