import { Dialect, Database } from '../base/index.js'; import { Column, Transaction, TransactionOptions } from '../types.js'; 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[]; 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 = Record> extends Dialect { #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; /** 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; /** * 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; disconnect(): Promise; healthCheck(): Promise; /** node:sqlite 仅支持 number/string/bigint/buffer/null;JSON 列在库内为 TEXT,对象需序列化 */ private prepareBindParams; query(sql: string, params?: any[]): Promise; /** 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): void; /** node:sqlite columns() is available since Node 22.16. It preserves table/column * provenance through aliases and joins; expression results have no origin. */ private processQueryResults; private processRowData; dispose(): Promise; mapColumnType(type: string): string; quoteIdentifier(identifier: string): string; getParameterPlaceholder(index: number): string; getStatementTerminator(): string; formatBoolean(value: boolean): string; formatDate(value: Date): string; formatJson(value: any): string; escapeString(value: string): string; formatDefaultValue(value: any): string; formatLimit(limit: number): string; formatOffset(offset: number): string; formatLimitOffset(limit: number, offset: number): string; formatCreateTable(tableName: T, columns: string[]): string; formatColumnDefinition(field: string, column: Column): string; formatAlterTable(tableName: T, alterations: string[]): string; formatDropTable(tableName: T, ifExists?: boolean): string; formatDropIndex(indexName: string, tableName: T, ifExists?: boolean): string; /** * SQLite 支持事务 */ supportsTransactions(): boolean; /** * 开始事务 */ beginTransaction(options?: TransactionOptions): Promise; } export declare class Sqlite = Record> extends RelatedDatabase { constructor(config: SQLiteDialectConfig, definitions?: Database.DefinitionObj); }