@zhin.js/database 1.1.7 → 1.1.8

package/README.md

@@ -8,7 +8,7 @@ Universal database abstraction layer for Zhin.js framework with support for mult
 npm install @zhin.js/database
 ```
 
-Install the database driver you need（SQLite 使用 Node 内置 `node:sqlite`，无需安装，需 Node.js 22.5+，推荐 24+）:
+Install the database driver you need（SQLite 使用 Node 内置 `node:sqlite`，无需安装，需 Node.js >=22.19.0，推荐 24+）:
 
 ```bash
 # For MySQL
@@ -83,7 +83,7 @@ const user = await userModel.create({
 ## Supported Databases
 
 ### ✅ Relational Databases (已完整实现)
-- **SQLite** - 内置支持，使用 Node 自带 `node:sqlite`（无需安装驱动，需 Node.js 22.5+，推荐 24+）
+- **SQLite** - 内置支持，使用 Node 自带 `node:sqlite`（无需安装驱动，需 Node.js >=22.19.0，推荐 24+）
   - 轻量级、零配置
   - 适合中小型应用
   - 支持 WAL 模式
@@ -262,27 +262,33 @@ await db.start();
 
 ## Model API
 
+以下为关系型模型（`RelatedModel`，SQLite / MySQL / PostgreSQL）的便捷方法；更复杂的查询见下方链式查询 API。
+
 ```typescript
 const model = db.model('users');
 
 // Create
 const user = await model.create({ name: 'John', email: 'john@example.com' });
+const created = await model.createMany([{ name: 'A' }, { name: 'B' }]);
 
 // Read
-const users = await model.find({ name: 'John' });
-const user = await model.findOne({ email: 'john@example.com' });
+const users = await model.findAll({ name: 'John' });
+const one = await model.findOne({ email: 'john@example.com' });
+const byId = await model.findById(1);
 
-// Update
-await model.update({ name: 'John' }, { name: 'Jane' });
+// Update —— 条件在前、数据在后；返回受影响行数
+await model.updateWhere({ name: 'John' }, { name: 'Jane' });
+await model.updateById(1, { name: 'Jane' });
 
-// Delete
-await model.remove({ name: 'Jane' });
+// Delete —— 启用软删除的模型会改为标记 deletedAt
+await model.deleteWhere({ name: 'Jane' });
+await model.deleteById(1);
 
 // Count
 const count = await model.count({ email: { $like: '%@example.com' } });
 
-// Pagination
-const result = await model.find({}, { limit: 10, offset: 0 });
+// Pagination —— 用链式查询
+const page = await model.select().where({}).limit(10).offset(0);
 ```
 
 ## 链式查询 API (Fluent Query Builder)

package/lib/dialects/sqlite.d.ts

@@ -4,10 +4,30 @@ 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;
 }
+/** 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;
 export declare class SQLiteDialect<S extends Record<string, object> = Record<string, object>> extends Dialect<SQLiteDialectConfig, S, string> {
     /** Node 内置 SQLite 连接（node:sqlite），在 connect() 中动态加载 */
     private db;
+    /** Own transaction flag; `DatabaseSync#isTransaction` is preferred where Node provides it. */
+    private transactionOpen;
     constructor(config: SQLiteDialectConfig);
     isConnected(): boolean;
     connect(): Promise<void>;
@@ -16,6 +36,10 @@ export declare class SQLiteDialect<S extends Record<string, object> = Record<str
     /** 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;
+    private execute;
     /** Column declarations are scoped to the table in this database, never the result alias. */
     private readonly jsonColumns;
     registerTableSchema(table: string, definition: Record<string, {

package/lib/dialects/sqlite.js

@@ -1,10 +1,27 @@
 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 { RelatedDatabase } from '../type/related/database.js';
+/** 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;
+}
+function isInMemoryFilename(filename) {
+    return filename === ':memory:' || filename === '' || filename.startsWith('file::memory:');
+}
 export class SQLiteDialect extends Dialect {
     /** Node 内置 SQLite 连接（node:sqlite），在 connect() 中动态加载 */
     db = null;
+    /** Own transaction flag; `DatabaseSync#isTransaction` is preferred where Node provides it. */
+    transactionOpen = false;
     constructor(config) {
         super('sqlite', config);
     }
@@ -20,7 +37,21 @@ export class SQLiteDialect extends Dialect {
             if (!fs.existsSync(dirname)) {
                 fs.mkdirSync(dirname, { recursive: true });
             }
-            this.db = new DatabaseSync(this.config.filename);
+            const db = new DatabaseSync(this.config.filename);
+            try {
+                // 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}`);
@@ -58,6 +89,42 @@ export class SQLiteDialect extends Dialect {
         });
     }
     async query(sql, params) {
+        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;
+    }
+    async execute(sql, params) {
         if (!this.db)
             throw new Error('SQLite 未连接');
         const trimmedSql = sql.trim().toLowerCase();
@@ -235,15 +302,44 @@ 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;
+        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 (readOnly)
+                await dialect.query('PRAGMA query_only = OFF').catch(() => undefined);
+        };
+        const finish = async (sql) => {
+            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);
             }

package/lib/index.d.ts

@@ -13,3 +13,5 @@ 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';

package/lib/index.js

@@ -13,5 +13,7 @@ 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';
 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 {};

package/lib/probe.js

@@ -0,0 +1,98 @@
+/**
+ * One-shot connection probe for setup wizards: connect, run the dialect health query, disconnect.
+ * Error text is stripped of credentials before it is returned.
+ */
+/** Driver package that must be importable for each dialect (`null`: built into Node). */
+export const DATABASE_DRIVER_PACKAGES = Object.freeze({
+    sqlite: null,
+    mysql: 'mysql2',
+    pg: 'pg',
+    mongodb: 'mongodb',
+});
+/** Whether the optional driver package for `dialect` can be loaded. */
+export async function isDatabaseDriverAvailable(dialect, importer = specifier => import(specifier)) {
+    const pkg = DATABASE_DRIVER_PACKAGES[dialect];
+    if (pkg === null)
+        return true;
+    try {
+        await importer(pkg);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function createProbeTarget(dialect, config) {
+    switch (dialect) {
+        case 'sqlite': {
+            const { SQLiteDialect } = await import('./dialects/sqlite.js');
+            return new SQLiteDialect(config);
+        }
+        case 'mysql': {
+            const { MySQLDialect } = await import('./dialects/mysql.js');
+            return new MySQLDialect(config);
+        }
+        case 'pg': {
+            const { PostgreSQLDialect } = await import('./dialects/pg.js');
+            return new PostgreSQLDialect(config);
+        }
+        case 'mongodb': {
+            const { MongoDBDialect } = await import('./dialects/mongodb.js');
+            return new MongoDBDialect(config);
+        }
+        default:
+            throw new Error(`Unsupported dialect: ${String(dialect)}`);
+    }
+}
+/**
+ * Opens a temporary connection with `config` and closes it again.
+ * `factory` is a test seam; it defaults to the built-in dialects.
+ */
+export async function probeDatabaseConnection(dialect, config, options = {}) {
+    const secrets = collectSecrets(config);
+    const startedAt = Date.now();
+    let target;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error('connection timed out')), options.timeoutMs ?? 10_000);
+    });
+    try {
+        target = await (options.factory ?? createProbeTarget)(dialect, config);
+        await Promise.race([target.connect(), timeout]);
+        const healthy = await Promise.race([target.healthCheck(), timeout]);
+        if (!healthy)
+            return Object.freeze({ ok: false, error: 'probe query failed' });
+        return Object.freeze({ ok: true, latencyMs: Date.now() - startedAt });
+    }
+    catch (error) {
+        return Object.freeze({ ok: false, error: redactProbeError(error, secrets) });
+    }
+    finally {
+        clearTimeout(timer);
+        await target?.disconnect().catch(() => undefined);
+    }
+}
+function collectSecrets(config) {
+    const values = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (typeof value !== 'string' || !value)
+            continue;
+        if (/pass|secret|token|key/iu.test(key))
+            values.push(value);
+        if (/url|uri|connectionString/iu.test(key)) {
+            const credentials = /\/\/([^@/]*)@/u.exec(value)?.[1];
+            if (credentials)
+                values.push(credentials, ...credentials.split(':').filter(Boolean));
+        }
+    }
+    return values.filter(value => value.length >= 3).sort((a, b) => b.length - a.length);
+}
+/** Removes credentials (configured secret values, URL userinfo) from a driver error. */
+export function redactProbeError(error, secrets = []) {
+    let message = error instanceof Error ? error.message : String(error);
+    for (const secret of secrets)
+        message = message.split(secret).join('***');
+    message = message.replace(/\/\/[^@\s/]*@/gu, '//***@');
+    message = message.replace(/(password|pwd)\s*[=:]\s*\S+/giu, '$1=***');
+    return message.slice(0, 300);
+}

package/lib/reserved-tables.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tables owned by the management gateway (ADR 0049 / 0054 §7). The gateway and the instance share
+ * one project database; the gateway's tables hold password hashes, session / token hashes and the
+ * audit log, so every instance-side path (plugin models, Console database page, raw SQL) must deny
+ * them. Deny by prefix so future gateway tables are covered without another list to update.
+ */
+export declare const GATEWAY_TABLE_PREFIX = "console_";
+/** `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). */
+export declare function referencesGatewayOwnedTable(sql: string): boolean;
+export declare class GatewayOwnedTableError extends Error {
+    constructor(table?: string);
+}
+/** Throws {@link GatewayOwnedTableError} for a gateway-owned table name. */
+export declare function assertInstanceTable(name: string): void;

package/lib/reserved-tables.js

@@ -0,0 +1,39 @@
+/**
+ * Tables owned by the management gateway (ADR 0049 / 0054 §7). The gateway and the instance share
+ * one project database; the gateway's tables hold password hashes, session / token hashes and the
+ * audit log, so every instance-side path (plugin models, Console database page, raw SQL) must deny
+ * them. Deny by prefix so future gateway tables are covered without another list to update.
+ */
+export const GATEWAY_TABLE_PREFIX = 'console_';
+/** `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);
+/** True when `name` is a gateway-owned table (case-insensitive, quotes and schema ignored). */
+export function isGatewayOwnedTable(name) {
+    const bare = String(name).trim().replace(/^[`"[]|[`"\]]$/g, '');
+    const table = (bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare)
+        .replace(/^[`"[]|[`"\]]$/g, '').toLowerCase();
+    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). */
+export function referencesGatewayOwnedTable(sql) {
+    for (const match of String(sql).matchAll(IDENTIFIER)) {
+        if (isGatewayOwnedTable(match[0]))
+            return true;
+    }
+    return false;
+}
+export class GatewayOwnedTableError extends Error {
+    constructor(table) {
+        super(table
+            ? `Table '${table}' is owned by the management gateway and is not accessible from the instance`
+            : 'Statement references a table owned by the management gateway');
+        this.name = 'GatewayOwnedTableError';
+    }
+}
+/** Throws {@link GatewayOwnedTableError} for a gateway-owned table name. */
+export function assertInstanceTable(name) {
+    if (isGatewayOwnedTable(name))
+        throw new GatewayOwnedTableError(name);
+}

package/lib/types.d.ts

@@ -285,6 +285,11 @@ export type IsolationLevel = 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE
 export interface TransactionOptions {
     isolationLevel?: IsolationLevel;
     timeout?: number;
+    /**
+     * 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`).
+     */
+    readOnly?: boolean;
 }
 export interface Transaction {
     commit(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,14 +43,15 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "license": "MIT",
   "dependencies": {
-    "@zhin.js/logger": "1.1.2"
+    "@zhin.js/logger": "1.1.3"
   },
   "peerDependencies": {
     "mongodb": ">=3.1.13",
     "mysql2": ">=3.9.8",
     "pg": ">=2.11.2",
-    "redis": "latest"
+    "redis": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {