@zhin.js/database 1.1.7 → 1.2.0

package/lib/dialects/mysql.d.ts

@@ -8,6 +8,13 @@ export interface MySQLDialectConfig extends ConnectionOptions {
      * 如果提供此选项，将使用连接池而不是单连接
      */
     pool?: PoolConfig;
+    /**
+     * Pool mode: `COM_RESET_CONNECTION` (`connection.reset()`, MySQL 5.7.3+) before a connection
+     * goes back to the pool, so session variables, user variables, temporary tables and prepared
+     * statements never outlive one use; a connection that cannot be reset is destroyed. The
+     * restricted Console account uses it (ADR 0059 §4).
+     */
+    resetSession?: boolean;
 }
 export declare class MySQLDialect<S extends Record<string, object> = Record<string, object>> extends Dialect<MySQLDialectConfig, S, string> {
     private connection;
@@ -15,12 +22,38 @@ export declare class MySQLDialect<S extends Record<string, object> = Record<stri
     private usePool;
     private readonly booleanColumns;
     private readonly bigintColumns;
+    /** `SELECT VERSION()` of the server, read once at connect ('' when it could not be read). */
+    private serverVersion;
     constructor(config: MySQLDialectConfig);
     isConnected(): boolean;
     connect(): Promise<void>;
+    /** Whether the server is MariaDB (from `VERSION()`; false when unknown). */
+    isMariaDb(): boolean;
+    /**
+     * Binary, NO PAD collation for indexed text keys: `utf8mb4_0900_bin` (MySQL 8.0+),
+     * `utf8mb4_nopad_bin` (MariaDB 10.2+, which has no 0900 collations before 11.4), and
+     * `utf8mb4_bin` on MySQL 5.7 (binary, but PAD SPACE: the only binary utf8mb4 collation there).
+     */
+    indexedTextCollation(): string;
     disconnect(): Promise<void>;
     healthCheck(): Promise<boolean>;
+    /**
+     * What the driver will actually send at connect time (after merging `uri` and `flags`):
+     * whether `LOAD DATA LOCAL` and multiple statements are possible on this connection.
+     */
+    connectionSafety(): {
+        readonly localFiles: boolean;
+        readonly multipleStatements: boolean;
+    } | undefined;
+    /** Gives a pool connection back, reset first with {@link MySQLDialectConfig.resetSession}. */
+    private releaseConnection;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
+    /**
+     * One statement as a prepared statement (binary protocol): MySQL never runs a second statement
+     * from it, even when the connection was configured with `multipleStatements`. With `maxRows`
+     * the rows are streamed and those past the cap discarded, so memory stays bounded.
+     */
+    private queryStatementOn;
     registerTableSchema(table: string, definition: Record<string, {
         type: string;
     }>): void;
@@ -41,6 +74,7 @@ export declare class MySQLDialect<S extends Record<string, object> = Record<stri
     formatBoolean(value: boolean): string;
     formatDate(value: Date): string;
     formatJson(value: any): string;
+    /** MySQL string literals treat `\\` as an escape (unless `NO_BACKSLASH_ESCAPES`): double both. */
     escapeString(value: string): string;
     formatDefaultValue(value: any): string;
     formatLimit(limit: number): string;

package/lib/dialects/mysql.js

@@ -1,13 +1,19 @@
 import { Dialect } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
 import { getLogger } from '@zhin.js/logger';
+import { markTruncated } from '../base/statement-rows.js';
 const logger = getLogger('database');
+/** `ClientConstants.LOCAL_FILES` / `MULTI_STATEMENTS` of the MySQL protocol. */
+const CLIENT_LOCAL_FILES = 0x80;
+const CLIENT_MULTI_STATEMENTS = 0x10000;
 export class MySQLDialect extends Dialect {
     connection = null;
     pool = null;
     usePool = false;
     booleanColumns = new Set();
     bigintColumns = new Set();
+    /** `SELECT VERSION()` of the server, read once at connect ('' when it could not be read). */
+    serverVersion = '';
     constructor(config) {
         super('mysql', config);
         this.usePool = !!config.pool;
@@ -20,7 +26,7 @@ export class MySQLDialect extends Dialect {
         try {
             if (this.usePool) {
                 const { createPool } = await import('mysql2/promise');
-                const { pool, ...connectionOptions } = this.config;
+                const { pool, resetSession: _reset, ...connectionOptions } = this.config;
                 const poolConfig = {
                     ...connectionOptions,
                     waitForConnections: true,
@@ -33,13 +39,38 @@ export class MySQLDialect extends Dialect {
             }
             else {
                 const { createConnection } = await import('mysql2/promise');
-                this.connection = await createConnection(this.config);
+                const { resetSession: _reset, ...connectionOptions } = this.config;
+                this.connection = await createConnection(connectionOptions);
             }
         }
         catch (error) {
             logger.error('forgot install mysql2 ?');
             throw new Error(`MySQL 连接失败: ${error}`);
         }
+        try {
+            const rows = await this.query('SELECT VERSION() AS v');
+            this.serverVersion = String(rows?.[0]?.v ?? '');
+        }
+        catch (error) {
+            this.serverVersion = '';
+            // Unknown server: indexed text keys fall back to utf8mb4_0900_bin, which MariaDB < 11.4 lacks.
+            logger.warn(`MySQL: could not read VERSION() (${error instanceof Error ? error.message : String(error)}); assuming MySQL 8 collations`);
+        }
+    }
+    /** Whether the server is MariaDB (from `VERSION()`; false when unknown). */
+    isMariaDb() {
+        return /mariadb/iu.test(this.serverVersion);
+    }
+    /**
+     * Binary, NO PAD collation for indexed text keys: `utf8mb4_0900_bin` (MySQL 8.0+),
+     * `utf8mb4_nopad_bin` (MariaDB 10.2+, which has no 0900 collations before 11.4), and
+     * `utf8mb4_bin` on MySQL 5.7 (binary, but PAD SPACE: the only binary utf8mb4 collation there).
+     */
+    indexedTextCollation() {
+        if (this.isMariaDb())
+            return 'utf8mb4_nopad_bin';
+        const major = Number(/^(\d+)\./u.exec(this.serverVersion)?.[1]);
+        return Number.isFinite(major) && major > 0 && major < 8 ? 'utf8mb4_bin' : 'utf8mb4_0900_bin';
     }
     async disconnect() {
         if (this.usePool && this.pool) {
@@ -63,7 +94,46 @@ export class MySQLDialect extends Dialect {
             return false;
         }
     }
+    /**
+     * What the driver will actually send at connect time (after merging `uri` and `flags`):
+     * whether `LOAD DATA LOCAL` and multiple statements are possible on this connection.
+     */
+    connectionSafety() {
+        const config = this.usePool ? this.pool?.pool?.config?.connectionConfig : this.connection?.connection?.config;
+        if (!config || typeof config.clientFlags !== 'number')
+            return undefined;
+        return Object.freeze({
+            localFiles: (config.clientFlags & CLIENT_LOCAL_FILES) !== 0 || typeof config.infileStreamFactory === 'function',
+            multipleStatements: config.multipleStatements === true || (config.clientFlags & CLIENT_MULTI_STATEMENTS) !== 0,
+        });
+    }
+    /** Gives a pool connection back, reset first with {@link MySQLDialectConfig.resetSession}. */
+    async releaseConnection(connection) {
+        if (!this.config.resetSession) {
+            connection.release();
+            return;
+        }
+        try {
+            if (typeof connection.reset !== 'function')
+                throw new Error('connection.reset() is not available');
+            await connection.reset();
+            connection.release();
+        }
+        catch {
+            connection.destroy();
+        }
+    }
     async query(sql, params) {
+        if (this.usePool && this.config.resetSession) {
+            const connection = await this.pool.getConnection();
+            try {
+                const [rows, fields] = await connection.execute(sql, params);
+                return this.processQueryResults(rows, fields);
+            }
+            finally {
+                await this.releaseConnection(connection);
+            }
+        }
         if (this.usePool) {
             const [rows, fields] = await this.pool.execute(sql, params);
             return this.processQueryResults(rows, fields);
@@ -73,6 +143,45 @@ export class MySQLDialect extends Dialect {
             return this.processQueryResults(rows, fields);
         }
     }
+    /**
+     * One statement as a prepared statement (binary protocol): MySQL never runs a second statement
+     * from it, even when the connection was configured with `multipleStatements`. With `maxRows`
+     * the rows are streamed and those past the cap discarded, so memory stays bounded.
+     */
+    async queryStatementOn(connection, sql, options) {
+        const maxRows = options?.maxRows;
+        const core = connection?.connection;
+        if (maxRows === undefined || typeof core?.execute !== 'function') {
+            const [rows, fields] = await connection.execute(sql, []);
+            if (maxRows === undefined || !Array.isArray(rows))
+                return this.processQueryResults(rows, fields);
+            const extra = rows.length > maxRows;
+            return markTruncated(this.processQueryResults(rows.slice(0, maxRows), fields), extra);
+        }
+        const { rows, fields, truncated, header } = await new Promise((resolve, reject) => {
+            const rows = [];
+            let fields;
+            let header;
+            let truncated = false;
+            const command = core.execute(sql, []);
+            command.on('error', reject);
+            command.on('fields', (value) => { fields = value; });
+            command.on('result', (row) => {
+                if (fields === undefined) {
+                    header = row;
+                    return;
+                }
+                if (rows.length < maxRows)
+                    rows.push(row);
+                else
+                    truncated = true;
+            });
+            command.on('end', () => resolve({ rows, fields, truncated, header }));
+        });
+        if (fields === undefined && header !== undefined)
+            return header;
+        return markTruncated(this.processQueryResults(rows, fields), truncated);
+    }
     registerTableSchema(table, definition) {
         for (const [columnName, column] of Object.entries(definition)) {
             if (column.type === 'boolean')
@@ -136,7 +245,7 @@ export class MySQLDialect extends Dialect {
         return typeMap[type.toLowerCase()] || 'TEXT';
     }
     quoteIdentifier(identifier) {
-        return `\`${identifier}\``;
+        return `\`${identifier.replace(/`/g, '``')}\``;
     }
     getParameterPlaceholder(index) {
         return '?';
@@ -151,10 +260,11 @@ export class MySQLDialect extends Dialect {
         return `'${value.toISOString().slice(0, 19).replace('T', ' ')}'`;
     }
     formatJson(value) {
-        return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+        return `'${this.escapeString(JSON.stringify(value))}'`;
     }
+    /** MySQL string literals treat `\\` as an escape (unless `NO_BACKSLASH_ESCAPES`): double both. */
     escapeString(value) {
-        return value.replace(/'/g, "''");
+        return value.replace(/\\/g, '\\\\').replace(/'/g, "''");
     }
     formatDefaultValue(value) {
         if (typeof value === 'string') {
@@ -201,7 +311,7 @@ export class MySQLDialect extends Dialect {
         if (indexedText && (column.length ?? 768) > 768) {
             throw new RangeError(`MySQL indexed text column ${field} exceeds the utf8mb4 index limit of 768 characters`);
         }
-        const collation = indexedText ? ' CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin' : '';
+        const collation = indexedText ? ` CHARACTER SET utf8mb4 COLLATE ${this.indexedTextCollation()}` : '';
         const type = boundedText ? 'VARCHAR' : this.mapColumnType(column.type);
         const length = boundedText ? `(${column.length ?? 768})` : column.length ? `(${column.length})` : '';
         const nullable = column.nullable === false ? ' NOT NULL' : '';
@@ -284,11 +394,14 @@ export class MySQLDialect extends Dialect {
                 if (options?.isolationLevel) {
                     await connection.query(`SET TRANSACTION ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`);
                 }
-                // 开始事务
-                await connection.beginTransaction();
+                // 开始事务；声明只读时数据库拒绝写入
+                if (options?.readOnly)
+                    await connection.query('START TRANSACTION READ ONLY');
+                else
+                    await connection.beginTransaction();
             }
             catch (error) {
-                connection.release();
+                await dialect.releaseConnection(connection);
                 throw error;
             }
             return {
@@ -297,7 +410,7 @@ export class MySQLDialect extends Dialect {
                         await connection.commit();
                     }
                     finally {
-                        connection.release(); // 归还连接到池
+                        await dialect.releaseConnection(connection); // 归还连接到池
                     }
                 },
                 async rollback() {
@@ -305,12 +418,15 @@ export class MySQLDialect extends Dialect {
                         await connection.rollback();
                     }
                     finally {
-                        connection.release(); // 归还连接到池
+                        await dialect.releaseConnection(connection); // 归还连接到池
                     }
                 },
                 async query(sql, params) {
                     const [rows, fields] = await connection.execute(sql, params);
                     return dialect.processQueryResults(rows, fields);
+                },
+                async queryStatement(sql, options) {
+                    return await dialect.queryStatementOn(connection, sql, options);
                 }
             };
         }
@@ -319,8 +435,11 @@ export class MySQLDialect extends Dialect {
             if (options?.isolationLevel) {
                 await this.connection.query(`SET TRANSACTION ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`);
             }
-            // 开始事务
-            await this.connection.beginTransaction();
+            // 开始事务；声明只读时数据库拒绝写入
+            if (options?.readOnly)
+                await this.connection.query('START TRANSACTION READ ONLY');
+            else
+                await this.connection.beginTransaction();
             const connection = this.connection;
             return {
                 async commit() {
@@ -332,6 +451,9 @@ export class MySQLDialect extends Dialect {
                 async query(sql, params) {
                     const [rows, fields] = await connection.execute(sql, params);
                     return dialect.processQueryResults(rows, fields);
+                },
+                async queryStatement(sql, options) {
+                    return await dialect.queryStatementOn(connection, sql, options);
                 }
             };
         }

package/lib/dialects/pg.d.ts

@@ -8,18 +8,35 @@ export interface PostgreSQLDialectConfig extends ClientConfig {
      * 如果提供此选项，将使用连接池而不是单连接
      */
     pool?: PoolConfig;
+    /**
+     * Pool mode: `DISCARD ALL` before a connection goes back to the pool (session settings, roles,
+     * temp objects and prepared statements never outlive one use). A connection that cannot be
+     * reset is destroyed. The restricted Console account uses it (ADR 0059 §4).
+     */
+    resetSession?: boolean;
 }
 export declare class PostgreSQLDialect<S extends Record<string, object> = Record<string, object>> extends Dialect<PostgreSQLDialectConfig, S, string> {
     private connection;
     private pool;
     private usePool;
     constructor(config: PostgreSQLDialectConfig);
+    /** Gives a pool client back, after `DISCARD ALL` with {@link PostgreSQLDialectConfig.resetSession}. */
+    private releaseClient;
     isConnected(): boolean;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     healthCheck(): Promise<boolean>;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
+    /**
+     * One statement through the extended protocol: the server refuses a second command in it
+     * (`cannot insert multiple commands into a prepared statement`), whatever the text hides.
+     */
+    private queryStatementOn;
+    private extendedProtocol;
+    /** `queryMode: 'extended'` arrived in pg 8.11; an older driver would silently use the simple protocol. */
+    private assertExtendedProtocol;
     private normalizeResult;
+    private normalizeRows;
     dispose(): Promise<void>;
     /**
      * 获取连接池统计信息（仅在使用连接池时有效）
@@ -55,6 +72,8 @@ export declare class PostgreSQLDialect<S extends Record<string, object> = Record
      * 开始事务
      * 在连接池模式下，会获取一个专用连接用于事务
      */
+    /** `BEGIN [ISOLATION LEVEL …] [READ ONLY]`: a declared read-only transaction refuses writes. */
+    private formatBegin;
     beginTransaction(options?: TransactionOptions): Promise<Transaction>;
 }
 export declare class PG<S extends Record<string, object> = Record<string, object>> extends RelatedDatabase<PostgreSQLDialectConfig, S> {

package/lib/dialects/pg.js

@@ -1,7 +1,21 @@
 import { Dialect } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
 import { getLogger } from '@zhin.js/logger';
+import { capRows } from '../base/statement-rows.js';
 const logger = getLogger('database');
+/**
+ * Keeps the driver's `command` / `rowCount` on the row array as non-enumerable properties, so
+ * callers that need the affected row count of DML (Console SQL editor) can read it.
+ */
+function withCommandInfo(rows, result) {
+    if (!Array.isArray(rows) || Object.isFrozen(rows))
+        return rows;
+    if (typeof result.command === 'string')
+        Object.defineProperty(rows, 'command', { value: result.command, enumerable: false, configurable: true });
+    if (typeof result.rowCount === 'number')
+        Object.defineProperty(rows, 'rowCount', { value: result.rowCount, enumerable: false, configurable: true });
+    return rows;
+}
 export class PostgreSQLDialect extends Dialect {
     connection = null;
     pool = null;
@@ -10,6 +24,20 @@ export class PostgreSQLDialect extends Dialect {
         super('pg', config);
         this.usePool = !!config.pool;
     }
+    /** Gives a pool client back, after `DISCARD ALL` with {@link PostgreSQLDialectConfig.resetSession}. */
+    async releaseClient(client) {
+        if (!this.config.resetSession) {
+            client.release();
+            return;
+        }
+        try {
+            await client.query('DISCARD ALL');
+            client.release();
+        }
+        catch (error) {
+            client.release(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
     // Connection management
     isConnected() {
         return this.usePool ? this.pool !== null : this.connection !== null;
@@ -18,7 +46,7 @@ export class PostgreSQLDialect extends Dialect {
         try {
             if (this.usePool) {
                 const { Pool } = await import('pg');
-                const { pool, ...connectionOptions } = this.config;
+                const { pool, resetSession: _reset, ...connectionOptions } = this.config;
                 const poolConfig = {
                     ...connectionOptions,
                     max: pool?.max ?? 10,
@@ -31,7 +59,8 @@ export class PostgreSQLDialect extends Dialect {
             }
             else {
                 const { Client } = await import('pg');
-                this.connection = new Client(this.config);
+                const { resetSession: _reset, ...clientOptions } = this.config;
+                this.connection = new Client(clientOptions);
                 await this.connection.connect();
             }
         }
@@ -64,6 +93,15 @@ export class PostgreSQLDialect extends Dialect {
     }
     async query(sql, params) {
         if (this.usePool) {
+            if (this.config.resetSession) {
+                const client = await this.pool.connect();
+                try {
+                    return this.normalizeResult(await client.query(sql, params));
+                }
+                finally {
+                    await this.releaseClient(client);
+                }
+            }
             const result = await this.pool.query(sql, params);
             return this.normalizeResult(result);
         }
@@ -72,7 +110,31 @@ export class PostgreSQLDialect extends Dialect {
             return this.normalizeResult(result);
         }
     }
+    /**
+     * One statement through the extended protocol: the server refuses a second command in it
+     * (`cannot insert multiple commands into a prepared statement`), whatever the text hides.
+     */
+    async queryStatementOn(client, sql, options) {
+        await this.assertExtendedProtocol();
+        const result = await client.query({ text: sql, values: [], queryMode: 'extended' });
+        return capRows(this.normalizeResult(result), options?.maxRows);
+    }
+    extendedProtocol;
+    /** `queryMode: 'extended'` arrived in pg 8.11; an older driver would silently use the simple protocol. */
+    assertExtendedProtocol() {
+        return this.extendedProtocol ??= (async () => {
+            const pg = await import('pg');
+            const Query = pg.Query ?? pg.default?.Query;
+            const probe = Query ? new Query({ text: 'SELECT 1', values: [], queryMode: 'extended' }) : undefined;
+            if (probe?.requiresPreparation?.() !== true) {
+                throw new Error('Single-statement queries need the pg driver 8.11 or later (queryMode: extended)');
+            }
+        })();
+    }
     normalizeResult(result) {
+        return withCommandInfo(this.normalizeRows(result), result);
+    }
+    normalizeRows(result) {
         const bigintFields = new Set((result.fields ?? [])
             .filter((field) => field.dataTypeID === 20)
             .map((field) => field.name));
@@ -120,7 +182,7 @@ export class PostgreSQLDialect extends Dialect {
         return typeMap[type.toLowerCase()] || 'TEXT';
     }
     quoteIdentifier(identifier) {
-        return `"${identifier}"`;
+        return `"${identifier.replace(/"/g, '""')}"`;
     }
     getParameterPlaceholder(index) {
         return `$${index + 1}`;
@@ -244,21 +306,23 @@ export class PostgreSQLDialect extends Dialect {
      * 开始事务
      * 在连接池模式下，会获取一个专用连接用于事务
      */
+    /** `BEGIN [ISOLATION LEVEL …] [READ ONLY]`: a declared read-only transaction refuses writes. */
+    formatBegin(options) {
+        const isolation = options?.isolationLevel ? ` ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}` : '';
+        return `BEGIN${isolation}${options?.readOnly ? ' READ ONLY' : ''}`;
+    }
     async beginTransaction(options) {
         const dialect = this;
         if (this.usePool) {
             // 从连接池获取一个连接用于事务
             const client = await this.pool.connect();
             // 开始事务（可以带隔离级别）
-            let beginSql = 'BEGIN';
-            if (options?.isolationLevel) {
-                beginSql = `BEGIN ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`;
-            }
+            const beginSql = this.formatBegin(options);
             try {
                 await client.query(beginSql);
             }
             catch (error) {
-                client.release();
+                await dialect.releaseClient(client);
                 throw error;
             }
             return {
@@ -267,7 +331,7 @@ export class PostgreSQLDialect extends Dialect {
                         await client.query('COMMIT');
                     }
                     finally {
-                        client.release(); // 归还连接到池
+                        await dialect.releaseClient(client); // 归还连接到池
                     }
                 },
                 async rollback() {
@@ -275,12 +339,15 @@ export class PostgreSQLDialect extends Dialect {
                         await client.query('ROLLBACK');
                     }
                     finally {
-                        client.release(); // 归还连接到池
+                        await dialect.releaseClient(client); // 归还连接到池
                     }
                 },
                 async query(sql, params) {
                     const result = await client.query(sql, params);
                     return dialect.normalizeResult(result);
+                },
+                async queryStatement(sql, options) {
+                    return await dialect.queryStatementOn(client, sql, options);
                 }
             };
         }
@@ -288,10 +355,7 @@ export class PostgreSQLDialect extends Dialect {
             // 单连接模式
             const dialect = this;
             // 开始事务（可以带隔离级别）
-            let beginSql = 'BEGIN';
-            if (options?.isolationLevel) {
-                beginSql = `BEGIN ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`;
-            }
+            const beginSql = this.formatBegin(options);
             await this.query(beginSql);
             return {
                 async commit() {
@@ -302,6 +366,9 @@ export class PostgreSQLDialect extends Dialect {
                 },
                 async query(sql, params) {
                     return dialect.query(sql, params);
+                },
+                async queryStatement(sql, options) {
+                    return await dialect.queryStatementOn(dialect.connection, sql, options);
                 }
             };
         }

package/lib/dialects/sqlite.d.ts

@@ -4,18 +4,102 @@ import { RelatedDatabase } from '../type/related/database.js';
 export interface SQLiteDialectConfig {
     filename: string;
     mode?: string;
+    /**
+     * `PRAGMA busy_timeout` in ms (default 0: no synchronous wait; see `busyRetryMs`). The wait
+     * is synchronous (`node:sqlite`), so only a connection whose own writes are short statements
+     * should set it — the gateway does for its `console_*` connection (ADR 0054 §7). Two
+     * connections of one process with async transactions would block each other's event loop.
+     */
+    busyTimeoutMs?: number;
+    /**
+     * Without `busyTimeoutMs`, a statement outside a transaction (and `BEGIN IMMEDIATE`) that hits
+     * `SQLITE_BUSY` is retried with an async backoff for at most this long (default 5000 ms; 0
+     * disables). The event loop keeps running while another process (the gateway) holds the
+     * write lock, so two connections in one process cannot deadlock each other.
+     */
+    busyRetryMs?: number;
+    /**
+     * Refuse `ATTACH DATABASE` on this connection (ADR 0059 §2). Every raw statement — `query`,
+     * single statements of a transaction, the isolated read process — reads `PRAGMA database_list`
+     * before and after it runs; any schema besides `main` / `temp` fails the statement. Inside a
+     * transaction the transaction is rolled back and poisoned (later statements, `COMMIT` included,
+     * are refused), then the extra schema is detached. Where Node provides `setAuthorizer`, an
+     * authorizer denying `SQLITE_ATTACH` is installed as well. Off by default: the instance turns it
+     * on, so its raw SQL cannot open the gateway's `.zhin/gateway.db` beside the project database.
+     */
+    denyAttach?: boolean;
+}
+/** A statement attached another database file to a connection with {@link SQLiteDialectConfig.denyAttach}. */
+export declare class SqliteAttachRefusedError extends Error {
+    readonly schemas: readonly string[];
+    readonly code = "attach_refused";
+    constructor(schemas: readonly string[]);
+}
+/** Default budget of {@link SQLiteDialectConfig.busyRetryMs}. */
+export declare const SQLITE_BUSY_RETRY_MS = 5000;
+/** `SQLITE_BUSY` and its extended codes except `SQLITE_BUSY_SNAPSHOT` (a stale read snapshot never clears by waiting). */
+export declare function isSqliteBusyError(error: unknown): boolean;
+/** Options of {@link SQLiteDialect.queryReadOnlyIsolated}. */
+export interface SqliteIsolatedQueryOptions {
+    readonly maxRows: number;
+    readonly timeoutMs: number;
+}
+export interface SqliteIsolatedQueryResult {
+    readonly columns: readonly string[];
+    readonly rows: Record<string, unknown>[];
+    readonly truncated: boolean;
+}
+/** Thrown when an isolated read exceeded its time budget (its process is killed). */
+export declare class SqliteQueryTimeoutError extends Error {
+    readonly code = "timeout";
+    constructor(timeoutMs: number);
 }
 export declare class SQLiteDialect<S extends Record<string, object> = Record<string, object>> extends Dialect<SQLiteDialectConfig, S, string> {
-    /** Node 内置 SQLite 连接（node:sqlite），在 connect() 中动态加载 */
-    private db;
+    #private;
+    /** Own transaction flag; `DatabaseSync#isTransaction` is preferred where Node provides it. */
+    private transactionOpen;
+    /** The transaction in progress; `poisoned` once a statement in it attached a database (denyAttach). */
+    private currentTransaction;
+    /** Worker of the isolated read in flight (also while a terminated one is still unwinding). */
+    private isolatedReader;
     constructor(config: SQLiteDialectConfig);
     isConnected(): boolean;
     connect(): Promise<void>;
+    /** True when {@link queryReadOnlyIsolated} can open its own connection (a file database). */
+    supportsIsolatedReads(): boolean;
+    /**
+     * 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.
+     */
+    queryReadOnlyIsolated(sql: string, options: SqliteIsolatedQueryOptions): Promise<SqliteIsolatedQueryResult>;
+    /**
+     * 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.
+     */
+    backupTo(destination: string): Promise<void>;
     disconnect(): Promise<void>;
     healthCheck(): Promise<boolean>;
     /** node:sqlite 仅支持 number/string/bigint/buffer/null；JSON 列在库内为 TEXT，对象需序列化 */
     private prepareBindParams;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
+    /** Async retry budget: only for connections that do not wait synchronously (`busyTimeoutMs`). */
+    private busyRetryBudget;
+    private inTransaction;
+    /**
+     * 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.
+     */
+    private assertNotAttached;
+    /** Rolls back and poisons an open transaction, detaches `extra` and throws (naming `reported`). */
+    private refuseAttach;
+    /** Statements of a poisoned transaction are refused (it was rolled back when ATTACH was found). */
+    private assertTransactionUsable;
+    private execute;
+    private executeUnchecked;
     /** Column declarations are scoped to the table in this database, never the result alias. */
     private readonly jsonColumns;
     registerTableSchema(table: string, definition: Record<string, {