@zhin.js/database 1.1.8 → 1.2.1

package/lib/dialects/sqlite.js

@@ -2,7 +2,46 @@ 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;
@@ -14,19 +53,88 @@ export function isSqliteBusyError(error) {
     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 {
@@ -37,8 +145,12 @@ export class SQLiteDialect extends Dialect {
             if (!fs.existsSync(dirname)) {
                 fs.mkdirSync(dirname, { recursive: true });
             }
-            const 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;
@@ -51,19 +163,144 @@ export class SQLiteDialect extends Dialect {
                 db.close();
                 throw error;
             }
-            this.db = db;
+            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.db.close();
+                this.isolatedReader.child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+        if (this.#db) {
+            try {
+                this.#db.close();
             }
             finally {
-                this.db = null;
+                this.#db = null;
             }
         }
     }
@@ -121,11 +358,70 @@ export class SQLiteDialect extends Dialect {
         return Number.isFinite(budget) && budget > 0 ? budget : 0;
     }
     inTransaction() {
-        const native = this.db?.isTransaction;
+        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)
+        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');
@@ -134,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 {
@@ -188,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;
             }
         }
     }
@@ -211,7 +507,7 @@ export class SQLiteDialect extends Dialect {
         return typeMap[type.toLowerCase()] || 'TEXT';
     }
     quoteIdentifier(identifier) {
-        return `"${identifier}"`;
+        return `"${identifier.replace(/"/g, '""')}"`;
     }
     getParameterPlaceholder(index) {
         return '?';
@@ -310,6 +606,8 @@ export class SQLiteDialect extends Dialect {
         // 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');
@@ -322,10 +620,19 @@ export class SQLiteDialect extends Dialect {
         }
         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);
             }
@@ -342,6 +649,36 @@ export class SQLiteDialect extends Dialect {
             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

@@ -15,3 +15,4 @@ 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

@@ -15,5 +15,6 @@ 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/reserved-tables.d.ts

@@ -5,11 +5,20 @@
  * them. Deny by prefix so future gateway tables are covered without another list to update.
  */
 export declare const GATEWAY_TABLE_PREFIX = "console_";
+/**
+ * The gateway's marker in the project database (ADR 0059 §3 修订): which `.zhin/gateway.db` holds
+ * the Console accounts. Gateway-owned like `console_*`: no instance path may read or drop it.
+ */
+export declare const GATEWAY_STORE_MARKER_TABLE = "zhin_gateway_store";
 /** `console_`-prefixed tables that the instance itself owns (historical names). */
 export declare const INSTANCE_CONSOLE_TABLES: readonly string[];
 /** True when `name` is a gateway-owned table (case-insensitive, quotes and schema ignored). */
 export declare function isGatewayOwnedTable(name: string): boolean;
-/** True when SQL text mentions a gateway-owned table anywhere (identifiers, quoted or literal). */
+/**
+ * True when SQL text mentions a gateway-owned table anywhere (identifiers, quoted or literal),
+ * also when the name is spelled with escapes (`U&"\\0063onsole_users"`, `E'\\x63onsole_users'`).
+ * A custom `UESCAPE` character cannot be decoded reliably, so it counts as a reference.
+ */
 export declare function referencesGatewayOwnedTable(sql: string): boolean;
 export declare class GatewayOwnedTableError extends Error {
     constructor(table?: string);

package/lib/reserved-tables.js

@@ -5,6 +5,11 @@
  * them. Deny by prefix so future gateway tables are covered without another list to update.
  */
 export const GATEWAY_TABLE_PREFIX = 'console_';
+/**
+ * The gateway's marker in the project database (ADR 0059 §3 修订): which `.zhin/gateway.db` holds
+ * the Console accounts. Gateway-owned like `console_*`: no instance path may read or drop it.
+ */
+export const GATEWAY_STORE_MARKER_TABLE = 'zhin_gateway_store';
 /** `console_`-prefixed tables that the instance itself owns (historical names). */
 export const INSTANCE_CONSOLE_TABLES = Object.freeze(['console_conversations']);
 const instanceConsoleTables = new Set(INSTANCE_CONSOLE_TABLES);
@@ -13,14 +18,48 @@ export function isGatewayOwnedTable(name) {
     const bare = String(name).trim().replace(/^[`"[]|[`"\]]$/g, '');
     const table = (bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare)
         .replace(/^[`"[]|[`"\]]$/g, '').toLowerCase();
+    if (table === GATEWAY_STORE_MARKER_TABLE)
+        return true;
     return table.startsWith(GATEWAY_TABLE_PREFIX) && !instanceConsoleTables.has(table);
 }
-const IDENTIFIER = /(?<![A-Za-z0-9_$])console_[A-Za-z0-9_$]*/gi;
-/** True when SQL text mentions a gateway-owned table anywhere (identifiers, quoted or literal). */
+const IDENTIFIER = /(?<![A-Za-z0-9_$])(?:console_[A-Za-z0-9_$]*|zhin_gateway_store)(?![A-Za-z0-9_$])/gi;
+/**
+ * Spellings of the SQL text with escape sequences decoded: PostgreSQL `U&"\\0063…"` /
+ * `U&'\\+000063…'` and `E'\\x63…'` / octal / `\\u`, MySQL backslash escapes inside strings
+ * (`'con\\sole_users'`) and doubled quotes inside quoted names (`"console_""x"`).
+ */
+function decodedSpellings(sql) {
+    const hex = (code) => {
+        const value = Number.parseInt(code, 16);
+        return Number.isFinite(value) && value <= 0x10ffff ? String.fromCodePoint(value) : '';
+    };
+    // U& names and strings: \XXXX and \+XXXXXX.
+    const unicode = sql
+        .replace(/\\\+([0-9a-f]{6})/gi, (_, code) => hex(code))
+        .replace(/\\([0-9a-f]{4})/gi, (_, code) => hex(code));
+    // E'' strings: \xHH, \ooo, \uXXXX, \UXXXXXXXX.
+    const escaped = sql
+        .replace(/\\U([0-9a-f]{8})/g, (_, code) => hex(code))
+        .replace(/\\u([0-9a-f]{4})/g, (_, code) => hex(code))
+        .replace(/\\x([0-9a-f]{1,2})/gi, (_, code) => hex(code))
+        .replace(/\\([0-7]{1,3})/g, (_, code) => String.fromCharCode(Number.parseInt(code, 8) & 0xff));
+    const spellings = [sql, unicode, escaped].flatMap(text => [text, text.replace(/\\(.)/g, '$1')]);
+    return spellings.flatMap(text => [text, text.replace(/""|``/g, '')]);
+}
+/**
+ * True when SQL text mentions a gateway-owned table anywhere (identifiers, quoted or literal),
+ * also when the name is spelled with escapes (`U&"\\0063onsole_users"`, `E'\\x63onsole_users'`).
+ * A custom `UESCAPE` character cannot be decoded reliably, so it counts as a reference.
+ */
 export function referencesGatewayOwnedTable(sql) {
-    for (const match of String(sql).matchAll(IDENTIFIER)) {
-        if (isGatewayOwnedTable(match[0]))
-            return true;
+    const text = String(sql);
+    if (/\bu&\s*['"]/i.test(text) && /\buescape\b/i.test(text))
+        return true;
+    for (const spelling of decodedSpellings(text)) {
+        for (const match of spelling.matchAll(IDENTIFIER)) {
+            if (isGatewayOwnedTable(match[0]))
+                return true;
+        }
     }
     return false;
 }

package/lib/types.d.ts

@@ -209,7 +209,7 @@ export interface DocumentQueryResult {
     limit?: number;
     skip?: number;
     projection?: Record<string, 1 | 0>;
-    operation?: 'find' | 'insertOne' | 'insertMany' | 'updateOne' | 'updateMany' | 'deleteOne' | 'deleteMany' | 'createCollection' | 'createIndex' | 'dropIndex' | 'dropCollection';
+    operation?: 'find' | 'insertOne' | 'insertMany' | 'updateOne' | 'updateMany' | 'deleteOne' | 'deleteMany' | 'createCollection' | 'createIndex' | 'dropIndex' | 'dropCollection' | 'listCollections';
 }
 /**
  * 键值查询结果类型
@@ -288,13 +288,28 @@ export interface TransactionOptions {
     /**
      * The transaction only reads. SQLite then opens it with `BEGIN DEFERRED` (no write lock, so it
      * never waits for another connection's writer) and refuses writes inside it (`query_only`).
+     * PostgreSQL opens it `READ ONLY` and MySQL with `START TRANSACTION READ ONLY`.
      */
     readOnly?: boolean;
 }
+export interface StatementQueryOptions {
+    /**
+     * Keep at most this many rows. Drivers stop reading past it where they can (SQLite iterates,
+     * MySQL streams and discards); the returned array then carries a non-enumerable `truncated`.
+     */
+    readonly maxRows?: number;
+}
 export interface Transaction {
     commit(): Promise<void>;
     rollback(): Promise<void>;
     query<T = any>(sql: string, params?: any[]): Promise<T>;
+    /**
+     * Runs exactly one statement through a protocol that refuses a second one: PostgreSQL's
+     * extended protocol (`cannot insert multiple commands into a prepared statement`), MySQL
+     * prepared statements (never `multipleStatements`, whatever the connection config says) and
+     * SQLite `prepare()` (which compiles only the first statement). For SQL typed by a person.
+     */
+    queryStatement?<T = any>(sql: string, options?: StatementQueryOptions): Promise<T>;
 }
 /**
  * 增强的事务接口，支持链式调用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.8",
+  "version": "1.2.1",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,7 +45,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@zhin.js/logger": "1.1.3"
+    "@zhin.js/logger": "1.2.0"
   },
   "peerDependencies": {
     "mongodb": ">=3.1.13",