@zhin.js/database 1.1.7 → 1.2.0

package/lib/dialects/sqlite.js

@@ -1,15 +1,140 @@
 import * as fs from 'node:fs';
 import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { Dialect } from '../base/index.js';
+import { capRows, markTruncated } from '../base/statement-rows.js';
 import { RelatedDatabase } from '../type/related/database.js';
+/** A statement attached another database file to a connection with {@link SQLiteDialectConfig.denyAttach}. */
+export class SqliteAttachRefusedError extends Error {
+    schemas;
+    code = 'attach_refused';
+    constructor(schemas) {
+        super(`ATTACH DATABASE is not allowed on this connection (attached: ${schemas.join(', ')}); the statement was undone`);
+        this.schemas = schemas;
+        this.name = 'SqliteAttachRefusedError';
+    }
+}
+/** Schemas of `PRAGMA database_list` other than `main` / `temp`. */
+function attachedSchemas(db) {
+    const rows = db.prepare('PRAGMA database_list').all();
+    return rows.map(row => String(row.name ?? '')).filter(name => name !== 'main' && name !== 'temp');
+}
+/** `SQLITE_ATTACH` / `SQLITE_DENY` / `SQLITE_OK` (sqlite3.h), for an authorizer where Node has one. */
+const SQLITE_ATTACH_ACTION = 24;
+const SQLITE_DENY_RESULT = 1;
+const SQLITE_OK_RESULT = 0;
+/** `SQLITE_AUTH`: the statement was refused by the authorizer (which only ever denies ATTACH here). */
+const SQLITE_AUTH_ERRCODE = 23;
+function isAuthorizerDenial(error) {
+    const record = error;
+    return record?.errcode === SQLITE_AUTH_ERRCODE || /\bnot authorized\b/iu.test(String(record?.message ?? ''));
+}
+/** Installs an authorizer that denies ATTACH when `node:sqlite` supports `setAuthorizer` (feature-detected). */
+function installAttachAuthorizer(db) {
+    const target = db;
+    if (typeof target.setAuthorizer !== 'function')
+        return false;
+    try {
+        target.setAuthorizer((action) => (action === SQLITE_ATTACH_ACTION ? SQLITE_DENY_RESULT : SQLITE_OK_RESULT));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Default budget of {@link SQLiteDialectConfig.busyRetryMs}. */
+export const SQLITE_BUSY_RETRY_MS = 5_000;
+const BUSY_RETRY_FIRST_DELAY_MS = 2;
+const BUSY_RETRY_MAX_DELAY_MS = 100;
+/** `SQLITE_BUSY` and its extended codes except `SQLITE_BUSY_SNAPSHOT` (a stale read snapshot never clears by waiting). */
+export function isSqliteBusyError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const errcode = error.errcode;
+    return typeof errcode === 'number' && (errcode & 0xff) === 5 && errcode !== 517;
+}
+/** Thrown when an isolated read exceeded its time budget (its process is killed). */
+export class SqliteQueryTimeoutError extends Error {
+    code = 'timeout';
+    constructor(timeoutMs) {
+        super(`Query exceeded the ${timeoutMs} ms time limit and was stopped`);
+        this.name = 'SqliteQueryTimeoutError';
+    }
+}
+/**
+ * Child-process body of {@link SQLiteDialect.queryReadOnlyIsolated} (CommonJS, `node -e`): its own
+ * read-only connection with `query_only`, rows iterated up to the cap and the wall-clock budget.
+ * A separate process, because only a process can be stopped (SIGKILL) inside a native SQLite step.
+ */
+const ISOLATED_READ_CHILD = `
+const { DatabaseSync } = require('node:sqlite');
+const attached = (db) => db.prepare('PRAGMA database_list').all().map(row => String(row.name)).filter(name => name !== 'main' && name !== 'temp');
+process.once('message', (job) => {
+  const { filename, sql, maxRows, deadline, json, denyAttach } = job;
+  let db;
+  let reply;
+  try {
+    db = new DatabaseSync(filename, denyAttach ? { readOnly: true, limits: { attach: 0 } } : { readOnly: true });
+    if (denyAttach && typeof db.setAuthorizer === 'function') {
+      try { db.setAuthorizer((action) => (action === 24 ? 1 : 0)); } catch {}
+    }
+    db.exec('PRAGMA query_only = ON');
+    const statement = db.prepare(sql);
+    const meta = typeof statement.columns === 'function' ? statement.columns() : [];
+    const decode = new Set(meta.filter(c => c.database === 'main' && c.table && c.column && (json[c.table] || []).includes(c.column)).map(c => c.name));
+    const rows = [];
+    let truncated = false;
+    let timeout = false;
+    for (const row of statement.iterate()) {
+      if (rows.length >= maxRows) { truncated = true; break; }
+      const out = {};
+      for (const [key, value] of Object.entries(row)) {
+        out[key] = value;
+        if (decode.has(key) && typeof value === 'string') { try { out[key] = JSON.parse(value); } catch {} }
+      }
+      rows.push(out);
+      if (Date.now() > deadline) { timeout = true; break; }
+    }
+    const extra = denyAttach ? attached(db) : [];
+    reply = extra.length
+      ? { ok: false, attach: extra }
+      : timeout ? { ok: false, timeout: true } : { ok: true, rows, truncated, columns: meta.map(c => c.name) };
+  } catch (error) {
+    reply = { ok: false, message: String(error && error.message || error), code: error && error.code, errcode: error && error.errcode };
+  } finally {
+    try { db && db.close(); } catch {}
+  }
+  process.send(reply, () => process.exit(0));
+});
+`;
+/** How long a new isolated read waits for a stopped one to be gone. */
+const ISOLATED_READER_EXIT_WAIT_MS = 2_000;
+function isInMemoryFilename(filename) {
+    return filename === ':memory:' || filename === '' || filename.startsWith('file::memory:');
+}
 export class SQLiteDialect extends Dialect {
     /** Node 内置 SQLite 连接（node:sqlite），在 connect() 中动态加载 */
-    db = null;
+    /** The `node:sqlite` connection: a true private field, so no handle on the dialect object reaches it. */
+    #db = null;
+    /** Own transaction flag; `DatabaseSync#isTransaction` is preferred where Node provides it. */
+    transactionOpen = false;
+    /** The transaction in progress; `poisoned` once a statement in it attached a database (denyAttach). */
+    currentTransaction = null;
+    /** Worker of the isolated read in flight (also while a terminated one is still unwinding). */
+    isolatedReader = null;
+    /**
+     * Captured once at construction: later changes to `config` (a plugin holding the config object)
+     * cannot turn the ATTACH check off.
+     */
+    #denyAttach;
+    /** An ATTACH-denying authorizer is installed (Node with `setAuthorizer`). */
+    #authorizer = false;
     constructor(config) {
         super('sqlite', config);
+        this.#denyAttach = config.denyAttach === true;
     }
     isConnected() {
-        return this.db !== null;
+        return this.#db !== null;
     }
     async connect() {
         try {
@@ -20,19 +145,162 @@ export class SQLiteDialect extends Dialect {
             if (!fs.existsSync(dirname)) {
                 fs.mkdirSync(dirname, { recursive: true });
             }
-            this.db = new DatabaseSync(this.config.filename);
+            const deny = this.#denyAttach;
+            // `limits.attach = 0` where Node honours it (ignored by Node 22); the database_list check is the defense.
+            const db = deny ? new DatabaseSync(this.config.filename, { limits: { attach: 0 } }) : new DatabaseSync(this.config.filename);
+            try {
+                if (deny)
+                    this.#authorizer = installAttachAuthorizer(db);
+                // Two processes share the file (gateway: console_* tables, instance: the rest):
+                // WAL lets readers run beside one writer and never blocks readers on a writer.
+                const busy = this.config.busyTimeoutMs;
+                if (busy !== undefined && Number.isSafeInteger(busy) && busy > 0)
+                    db.exec(`PRAGMA busy_timeout = ${busy}`);
+                if (!isInMemoryFilename(this.config.filename))
+                    db.exec('PRAGMA journal_mode = WAL');
+            }
+            catch (error) {
+                db.close();
+                throw error;
+            }
+            this.#db = db;
         }
         catch (error) {
             throw new Error(`SQLite 连接失败（需要 Node.js 22.5+，推荐 24+）: ${error}`);
         }
     }
+    /** True when {@link queryReadOnlyIsolated} can open its own connection (a file database). */
+    supportsIsolatedReads() {
+        return this.#db !== null && !isInMemoryFilename(this.config.filename);
+    }
+    /**
+     * Runs one read statement on its own read-only connection in a child process, so a slow query
+     * never blocks this event loop: rows are iterated up to `maxRows`, and the process is killed
+     * (SIGKILL — SQLite cannot be interrupted inside a step otherwise) when `timeoutMs` passes. One
+     * isolated read runs at a time per connection; the child never keeps this process alive.
+     */
+    async queryReadOnlyIsolated(sql, options) {
+        if (!this.supportsIsolatedReads())
+            throw new Error('Isolated reads need a file database');
+        const previous = this.isolatedReader;
+        if (previous) {
+            // A killed reader is gone within milliseconds; a running one is not waited for.
+            if (previous.killed)
+                await Promise.race([previous.exited, delay(ISOLATED_READER_EXIT_WAIT_MS, undefined, { ref: false })]);
+            if (this.isolatedReader)
+                throw new Error('A previous query is still running; try again shortly');
+        }
+        const { spawn } = await import('node:child_process');
+        const json = Object.fromEntries([...this.jsonColumns].map(([table, columns]) => [table, [...columns]]));
+        const { NODE_OPTIONS: _options, ...env } = process.env;
+        const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', '-e', ISOLATED_READ_CHILD], {
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            serialization: 'advanced',
+            env,
+            windowsHide: true,
+        });
+        let markExited;
+        const reader = { child, exited: new Promise(resolve => { markExited = resolve; }), killed: false };
+        this.isolatedReader = reader;
+        // Neither the child nor its channel keeps this process alive (the pending timer does, while needed).
+        child.unref();
+        child.channel?.unref?.();
+        const kill = () => {
+            reader.killed = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        };
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const timer = setTimeout(() => {
+                kill();
+                finish(new SqliteQueryTimeoutError(options.timeoutMs));
+            }, options.timeoutMs);
+            child.once('exit', code => {
+                if (this.isolatedReader === reader)
+                    this.isolatedReader = null;
+                markExited();
+                finish(new Error(`SQLite query process exited (${code ?? 'killed'})`));
+            });
+            child.once('error', error => {
+                if (this.isolatedReader === reader)
+                    this.isolatedReader = null;
+                markExited();
+                finish(error);
+            });
+            child.once('message', (message) => {
+                // A child that answered has closed SQLite and is exiting: the next read need not wait.
+                if (this.isolatedReader === reader)
+                    this.isolatedReader = null;
+                if (message.attach?.length) {
+                    finish(new SqliteAttachRefusedError(message.attach));
+                }
+                else if (!message.ok && this.#denyAttach && isAuthorizerDenial(message)) {
+                    finish(new SqliteAttachRefusedError(['(refused by the SQLite authorizer)']));
+                }
+                else if (message.ok) {
+                    finish(null, { columns: message.columns ?? [], rows: message.rows ?? [], truncated: message.truncated === true });
+                }
+                else if (message.timeout) {
+                    finish(new SqliteQueryTimeoutError(options.timeoutMs));
+                }
+                else {
+                    finish(Object.assign(new Error(message.message ?? 'SQLite query failed'), { code: message.code, errcode: message.errcode }));
+                }
+            });
+            child.send({ filename: this.config.filename, sql, maxRows: options.maxRows, deadline: Date.now() + options.timeoutMs, json, denyAttach: this.#denyAttach }, error => {
+                if (error) {
+                    kill();
+                    finish(error);
+                }
+            });
+        });
+    }
+    /**
+     * Copies the database to `destination` (a consistent snapshot, also while WAL frames are not
+     * checkpointed): `node:sqlite` `backup()` where Node provides it, otherwise `VACUUM INTO`. The
+     * copy is created owner-only (0600). The destination must not exist.
+     */
+    async backupTo(destination) {
+        if (!this.#db)
+            throw new Error('SQLite 未连接');
+        if (fs.existsSync(destination))
+            throw new Error(`Backup destination already exists: ${destination}`);
+        fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+        const { createRequire } = await import('node:module');
+        const sqlite = createRequire(import.meta.url)('node:sqlite');
+        if (typeof sqlite.backup === 'function')
+            await sqlite.backup(this.#db, destination);
+        else
+            this.#db.prepare('VACUUM INTO ?').run(destination);
+        fs.chmodSync(destination, 0o600);
+    }
     async disconnect() {
-        if (this.db) {
+        if (this.isolatedReader) {
+            this.isolatedReader.killed = true;
+            try {
+                this.isolatedReader.child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+        if (this.#db) {
             try {
-                this.db.close();
+                this.#db.close();
             }
             finally {
-                this.db = null;
+                this.#db = null;
             }
         }
     }
@@ -58,7 +326,102 @@ export class SQLiteDialect extends Dialect {
         });
     }
     async query(sql, params) {
-        if (!this.db)
+        const budget = this.busyRetryBudget();
+        if (budget <= 0)
+            return this.execute(sql, params);
+        const deadline = Date.now() + budget;
+        let wait = BUSY_RETRY_FIRST_DELAY_MS;
+        for (;;) {
+            // A statement inside an open transaction is never replayed here: the transaction's caller
+            // owns that retry (BEGIN IMMEDIATE takes the write lock up front, so this is rare).
+            // COMMIT is the exception: SQLite documents a busy COMMIT as safe to retry.
+            const replayable = !this.inTransaction() || /^\s*commit\b/i.test(sql);
+            try {
+                return await this.execute(sql, params);
+            }
+            catch (error) {
+                if (!replayable || !isSqliteBusyError(error) || Date.now() + wait > deadline)
+                    throw error;
+            }
+            await delay(wait);
+            wait = Math.min(wait * 2, BUSY_RETRY_MAX_DELAY_MS);
+        }
+    }
+    /** Async retry budget: only for connections that do not wait synchronously (`busyTimeoutMs`). */
+    busyRetryBudget() {
+        const busy = this.config.busyTimeoutMs;
+        if (busy !== undefined && busy > 0)
+            return 0;
+        if (isInMemoryFilename(this.config.filename))
+            return 0;
+        const budget = this.config.busyRetryMs ?? SQLITE_BUSY_RETRY_MS;
+        return Number.isFinite(budget) && budget > 0 ? budget : 0;
+    }
+    inTransaction() {
+        const native = this.#db?.isTransaction;
+        return typeof native === 'boolean' ? native : this.transactionOpen;
+    }
+    /**
+     * denyAttach: fails when `db` has a schema besides main / temp. Inside a transaction the
+     * transaction is rolled back first and marked poisoned (DETACH is refused while it holds
+     * locks); then every extra schema is detached.
+     */
+    assertNotAttached() {
+        if (!this.#denyAttach || !this.#db)
+            return;
+        const extra = attachedSchemas(this.#db);
+        if (!extra.length)
+            return;
+        this.refuseAttach(extra);
+    }
+    /** Rolls back and poisons an open transaction, detaches `extra` and throws (naming `reported`). */
+    refuseAttach(extra, reported = extra) {
+        if (!this.#db)
+            throw new SqliteAttachRefusedError(reported);
+        if (this.currentTransaction) {
+            this.currentTransaction.poisoned = true;
+            try {
+                this.#db.exec('ROLLBACK');
+            }
+            catch { /* not in a transaction any more */ }
+            this.transactionOpen = false;
+        }
+        for (const schema of extra) {
+            try {
+                this.#db.exec(`DETACH DATABASE ${this.quoteIdentifier(schema)}`);
+            }
+            catch { /* already gone */ }
+        }
+        throw new SqliteAttachRefusedError(reported);
+    }
+    /** Statements of a poisoned transaction are refused (it was rolled back when ATTACH was found). */
+    assertTransactionUsable() {
+        if (this.currentTransaction?.poisoned) {
+            throw new SqliteAttachRefusedError(['(transaction rolled back after ATTACH)']);
+        }
+    }
+    async execute(sql, params) {
+        if (!this.#db)
+            throw new Error('SQLite 未连接');
+        this.assertTransactionUsable();
+        this.assertNotAttached();
+        try {
+            return await this.executeUnchecked(sql, params);
+        }
+        catch (error) {
+            // Where Node has `setAuthorizer` (24+), SQLite refuses the ATTACH itself ("not authorized").
+            // Same outcome as the database_list defense on Node 22: the transaction is poisoned and the
+            // caller sees SqliteAttachRefusedError, whichever Node runs the instance.
+            if (this.#authorizer && isAuthorizerDenial(error))
+                this.refuseAttach([], ['(refused by the SQLite authorizer)']);
+            throw error;
+        }
+        finally {
+            this.assertNotAttached();
+        }
+    }
+    async executeUnchecked(sql, params) {
+        if (!this.#db)
             throw new Error('SQLite 未连接');
         const trimmedSql = sql.trim().toLowerCase();
         const isInsert = trimmedSql.startsWith('insert');
@@ -67,7 +430,7 @@ export class SQLiteDialect extends Dialect {
         const sqlWithoutLiterals = trimmedSql.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""');
         const hasReturning = /\breturning\b/.test(sqlWithoutLiterals);
         const args = this.prepareBindParams(params ?? []);
-        const stmt = this.db.prepare(sql);
+        const stmt = this.#db.prepare(sql);
         if (isInsert && !hasReturning) {
             const result = stmt.run(...args);
             return {
@@ -121,12 +484,12 @@ export class SQLiteDialect extends Dialect {
         return result;
     }
     async dispose() {
-        if (this.db) {
+        if (this.#db) {
             try {
-                this.db.close();
+                this.#db.close();
             }
             finally {
-                this.db = null;
+                this.#db = null;
             }
         }
     }
@@ -144,7 +507,7 @@ export class SQLiteDialect extends Dialect {
         return typeMap[type.toLowerCase()] || 'TEXT';
     }
     quoteIdentifier(identifier) {
-        return `"${identifier}"`;
+        return `"${identifier.replace(/"/g, '""')}"`;
     }
     getParameterPlaceholder(index) {
         return '?';
@@ -235,17 +598,87 @@ export class SQLiteDialect extends Dialect {
      */
     async beginTransaction(options) {
         const dialect = this;
-        // 开始事务
-        await this.query('BEGIN TRANSACTION');
+        const readOnly = options?.readOnly === true;
+        // Write transactions: IMMEDIATE takes the write lock at BEGIN, so contention with the
+        // gateway's connection surfaces there (retried by query()), never as SQLITE_BUSY_SNAPSHOT
+        // halfway through. A declared read-only transaction takes no write lock (DEFERRED: WAL
+        // readers never wait for a writer) and query_only makes an accidental write fail loudly.
+        // Callers that cannot declare intent (the plugin-runtime Database Host) stay IMMEDIATE.
+        await this.query(readOnly ? 'BEGIN DEFERRED' : 'BEGIN IMMEDIATE');
+        this.transactionOpen = true;
+        const state = { poisoned: false };
+        this.currentTransaction = state;
+        if (readOnly) {
+            try {
+                await this.query('PRAGMA query_only = ON');
+            }
+            catch (error) {
+                await this.query('ROLLBACK').catch(() => undefined);
+                this.transactionOpen = false;
+                throw error;
+            }
+        }
+        const close = async () => {
+            dialect.transactionOpen = false;
+            if (dialect.currentTransaction === state)
+                dialect.currentTransaction = null;
+            if (readOnly)
+                await dialect.query('PRAGMA query_only = OFF').catch(() => undefined);
+        };
+        const finish = async (sql) => {
+            if (state.poisoned) {
+                // Already rolled back when the ATTACH was found: nothing to commit, nothing to roll back.
+                await close();
+                if (sql === 'COMMIT')
+                    throw new SqliteAttachRefusedError(['(transaction rolled back after ATTACH)']);
+                return;
+            }
+            try {
+                await dialect.query(sql);
+            }
+            catch (error) {
+                // A failed COMMIT (e.g. busy past the budget) leaves the transaction to the caller's rollback.
+                if (sql === 'ROLLBACK')
+                    await close();
+                throw error;
+            }
+            await close();
+        };
         return {
-            async commit() {
-                await dialect.query('COMMIT');
-            },
-            async rollback() {
-                await dialect.query('ROLLBACK');
-            },
+            commit: () => finish('COMMIT'),
+            rollback: () => finish('ROLLBACK'),
             async query(sql, params) {
                 return dialect.query(sql, params);
+            },
+            /** `prepare()` compiles only the first statement; with `maxRows` rows are iterated, not all read. */
+            async queryStatement(sql, options) {
+                const maxRows = options?.maxRows;
+                if (maxRows === undefined || !dialect.#db)
+                    return capRows(await dialect.query(sql), maxRows);
+                dialect.assertTransactionUsable();
+                dialect.assertNotAttached();
+                const rows = [];
+                let truncated = false;
+                let statement;
+                try {
+                    statement = dialect.#db.prepare(sql);
+                    for (const row of statement.iterate()) {
+                        if (rows.length >= maxRows) {
+                            truncated = true;
+                            break;
+                        }
+                        rows.push(row);
+                    }
+                }
+                catch (error) {
+                    if (dialect.#authorizer && isAuthorizerDenial(error))
+                        dialect.refuseAttach([], ['(refused by the SQLite authorizer)']);
+                    throw error;
+                }
+                finally {
+                    dialect.assertNotAttached();
+                }
+                return markTruncated(dialect.processQueryResults(rows, statement.columns()), truncated);
             }
         };
     }

package/lib/index.d.ts

@@ -13,3 +13,6 @@ export * from './dialects/memory.js';
 export * from './dialects/sqlite.js';
 export * from './migration.js';
 export * from './structured-schema.js';
+export * from './probe.js';
+export * from './reserved-tables.js';
+export * from './console-credential.js';

package/lib/index.js

@@ -13,5 +13,8 @@ export * from './dialects/memory.js';
 export * from './dialects/sqlite.js';
 export * from './migration.js';
 export * from './structured-schema.js';
+export * from './probe.js';
+export * from './reserved-tables.js';
+export * from './console-credential.js';
 import { registerBuiltinDatabases } from './builtin-runtime.js';
 registerBuiltinDatabases();

package/lib/probe.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One-shot connection probe for setup wizards: connect, run the dialect health query, disconnect.
+ * Error text is stripped of credentials before it is returned.
+ */
+export type ProbeDialect = 'sqlite' | 'mysql' | 'pg' | 'mongodb';
+export interface DatabaseProbeResult {
+    readonly ok: boolean;
+    readonly latencyMs?: number;
+    readonly error?: string;
+}
+interface ProbeTarget {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<boolean>;
+}
+/** Driver package that must be importable for each dialect (`null`: built into Node). */
+export declare const DATABASE_DRIVER_PACKAGES: Readonly<Record<ProbeDialect, string | null>>;
+/** Whether the optional driver package for `dialect` can be loaded. */
+export declare function isDatabaseDriverAvailable(dialect: ProbeDialect, importer?: (specifier: string) => Promise<unknown>): Promise<boolean>;
+/**
+ * Opens a temporary connection with `config` and closes it again.
+ * `factory` is a test seam; it defaults to the built-in dialects.
+ */
+export declare function probeDatabaseConnection(dialect: ProbeDialect, config: Record<string, unknown>, options?: Readonly<{
+    timeoutMs?: number;
+    factory?: (dialect: ProbeDialect, config: Record<string, unknown>) => Promise<ProbeTarget>;
+}>): Promise<DatabaseProbeResult>;
+/** Removes credentials (configured secret values, URL userinfo) from a driver error. */
+export declare function redactProbeError(error: unknown, secrets?: readonly string[]): string;
+export {};