@zhin.js/database 1.1.7 → 1.2.0

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/base/database.js

@@ -236,6 +236,13 @@ export class Database {
                 },
                 commit: () => trx.commit(),
                 rollback: () => trx.rollback(),
+                ...(trx.queryStatement ? {
+                    queryStatement: (sql, options) => {
+                        if (!frame.active)
+                            return Promise.reject(new Error('Database transaction is already closed'));
+                        return trx.queryStatement(sql, options);
+                    },
+                } : {}),
             };
             const trxContext = new TransactionContextImpl(this, guarded);
             try {

package/lib/base/statement-rows.d.ts

@@ -0,0 +1,5 @@
+/** Row-cap helpers of `Transaction.queryStatement` (internal, not part of the public entry). */
+/** Marks a row array as cut at `maxRows` (non-enumerable, so JSON and equality ignore it). */
+export declare function markTruncated<T extends unknown[]>(rows: T, truncated: boolean): T;
+/** Applies {@link StatementQueryOptions.maxRows} to a fully read result. */
+export declare function capRows<T>(result: T, maxRows: number | undefined): T;

package/lib/base/statement-rows.js

@@ -0,0 +1,16 @@
+/** Row-cap helpers of `Transaction.queryStatement` (internal, not part of the public entry). */
+/** Marks a row array as cut at `maxRows` (non-enumerable, so JSON and equality ignore it). */
+export function markTruncated(rows, truncated) {
+    if (Array.isArray(rows) && !Object.isFrozen(rows))
+        Object.defineProperty(rows, 'truncated', { value: truncated, enumerable: false, configurable: true });
+    return rows;
+}
+/** Applies {@link StatementQueryOptions.maxRows} to a fully read result. */
+export function capRows(result, maxRows) {
+    if (maxRows === undefined || !Array.isArray(result))
+        return result;
+    const extra = result.length > maxRows;
+    if (extra)
+        result.splice(maxRows);
+    return markTruncated(result, extra);
+}

package/lib/base/transaction.d.ts

@@ -1,4 +1,4 @@
-import { Transaction, TransactionContext, TransactionSelection, TransactionUpdation, TransactionDeletion } from '../types.js';
+import { Transaction, TransactionContext, TransactionSelection, TransactionUpdation, TransactionDeletion, StatementQueryOptions } from '../types.js';
 import type { Database } from './database.js';
 /**
  * 增强的事务上下文实现
@@ -20,6 +20,8 @@ export declare class TransactionContextImpl<S extends Record<string, object>> im
      * 执行原生 SQL
      */
     query<T = any>(sql: string, params?: any[]): Promise<T>;
+    /** One statement through the single-statement protocol of the dialect (see {@link Transaction.queryStatement}). */
+    queryStatement<T = any>(sql: string, options?: StatementQueryOptions): Promise<T>;
     /**
      * 插入单条数据
      */

package/lib/base/transaction.js

@@ -138,6 +138,12 @@ export class TransactionContextImpl {
     async query(sql, params) {
         return this.trx.query(sql, params);
     }
+    /** One statement through the single-statement protocol of the dialect (see {@link Transaction.queryStatement}). */
+    async queryStatement(sql, options) {
+        if (!this.trx.queryStatement)
+            throw new Error('This database does not support single-statement queries');
+        return this.trx.queryStatement(sql, options);
+    }
     /**
      * 插入单条数据
      */

package/lib/console-credential.d.ts

@@ -0,0 +1,181 @@
+export type ConsoleCredentialDialect = 'pg' | 'mysql';
+/** Runs one statement on a connection (parameters bound by the driver). */
+export type ConsoleSqlRunner = (sql: string, params?: unknown[]) => Promise<unknown>;
+/** Connections the restricted account may hold at once (the Console pool uses at most 2). */
+export declare const CONSOLE_ROLE_CONNECTION_LIMIT = 4;
+/** Role-level `statement_timeout` backstop (the Console sets a shorter one per transaction). */
+export declare const CONSOLE_ROLE_STATEMENT_TIMEOUT = "60s";
+/** Privileges of the PostgreSQL account on tables / sequences of `public`. */
+export declare const PG_CONSOLE_TABLE_PRIVILEGES = "SELECT, INSERT, UPDATE, DELETE, TRUNCATE";
+export declare const PG_CONSOLE_SEQUENCE_PRIVILEGES = "USAGE, SELECT, UPDATE";
+/** Privileges of the MySQL account on `<database>.*` (nothing global). */
+export declare const MYSQL_CONSOLE_PRIVILEGES: readonly ["SELECT", "INSERT", "UPDATE", "DELETE", "CREATE", "ALTER", "DROP", "INDEX", "REFERENCES", "CREATE VIEW", "SHOW VIEW", "CREATE TEMPORARY TABLES"];
+/** Schema privileges the MySQL account must never hold. */
+export declare const MYSQL_FORBIDDEN_PRIVILEGES: ReadonlySet<string>;
+/**
+ * Role-level settings of the PostgreSQL account (`pg_db_role_setting`), exactly: the probe refuses
+ * an account whose settings differ — the account itself may `ALTER ROLE current_user SET …`
+ * (e.g. `search_path = pg_temp, public`), which would change how the main account's objects resolve
+ * in its sessions.
+ */
+export declare const PG_CONSOLE_ROLE_SETTINGS: readonly string[];
+/** SCRAM-SHA-256 iteration count of the verifier sent instead of the password (PostgreSQL default). */
+export declare const PG_SCRAM_ITERATIONS = 4096;
+/**
+ * A PostgreSQL SCRAM-SHA-256 verifier (`SCRAM-SHA-256$<iter>:<salt>$<StoredKey>:<ServerKey>`, RFC
+ * 7677 / `pg_authid.rolpassword` format) computed on the client, so `CREATE` / `ALTER ROLE` never
+ * carries the password itself — not to the server log, not into `--print-sql` output. The password
+ * is base64url ASCII, so SASLprep leaves it unchanged.
+ */
+export declare function pgScramVerifier(password: string, salt?: Buffer, iterations?: number): string;
+/** Replaces every spelling of `secret` (raw, quoted, URL-encoded) in `text` with `[redacted]`. */
+export declare function scrubSecret(text: string, secrets: readonly (string | undefined)[]): string;
+/** An error with `secrets` scrubbed from its message (driver codes kept; the original is dropped). */
+export declare function scrubbedError(error: unknown, secrets: readonly (string | undefined)[]): Error;
+/** `zhin_console_<first 8 hex of SHA-256(projectKey)>`: one account per project. */
+export declare function consoleRoleName(projectKey: string): string;
+/** 32 random bytes, base64url (no quotes or backslashes: safe inside a SQL literal). */
+export declare function generateConsolePassword(): string;
+export declare function quotePgIdentifier(name: string): string;
+export interface ConsoleRoleStatementOptions {
+    readonly dialect: ConsoleCredentialDialect;
+    readonly role: string;
+    /** The account's password; `--print-sql` passes a placeholder the DBA replaces. */
+    readonly password: string;
+    /** The project database. */
+    readonly database: string;
+    /** The main account (PostgreSQL: default privileges are declared for the tables it creates). */
+    readonly mainUser: string;
+    /** MySQL: host part of the new account (the host part of the main account's `CURRENT_USER()`). */
+    readonly host?: string;
+    /** PostgreSQL: the role exists already (ALTER instead of CREATE). */
+    readonly exists?: boolean;
+    /** PostgreSQL: the main account is a superuser (may set SUPERUSER / REPLICATION / BYPASSRLS attributes on ALTER). */
+    readonly mainIsSuperuser?: boolean;
+    /** PostgreSQL: the main account has CREATEDB (PG 16 lets only such an account name CREATEDB on ALTER). */
+    readonly mainCanCreateDb?: boolean;
+    /**
+     * PostgreSQL: tables (and views) of `public` to grant on. Undefined grants `ON ALL TABLES IN
+     * SCHEMA public`; gateway-owned names (`console_*`) are always left out.
+     */
+    readonly tables?: readonly string[];
+    /** PostgreSQL ≤ 14: `PUBLIC` may create in `public`; revoke that (and grant CREATE to the main account first). */
+    readonly revokePublicCreate?: boolean;
+}
+/** The statements that create (or rotate) the restricted account, in order. */
+export declare function consoleRoleStatements(options: ConsoleRoleStatementOptions): string[];
+/** `user@host` of MySQL `CURRENT_USER()` (the user part may itself contain `@`). */
+export declare function splitMysqlAccount(account: string): {
+    user: string;
+    host: string;
+};
+export interface ProvisionConsoleRoleOptions {
+    readonly dialect: ConsoleCredentialDialect;
+    /** Role name; default {@link consoleRoleName}(projectKey). */
+    readonly role?: string;
+    /** Stable project identity for the default role name (the CLI passes the project root). */
+    readonly projectKey: string;
+    /** Default {@link generateConsolePassword}. */
+    readonly password?: string;
+}
+export interface ConsoleRolePlan {
+    readonly dialect: ConsoleCredentialDialect;
+    readonly user: string;
+    readonly password: string;
+    /** MySQL host part of the account. */
+    readonly host?: string;
+    readonly database: string;
+    readonly mainUser: string;
+    readonly statements: readonly string[];
+}
+/**
+ * Reads what the statements need from the main account's connection (its name, the database,
+ * existing tables, whether the role exists) and returns the plan without running it
+ * (`--print-sql`).
+ */
+export declare function planConsoleRole(run: ConsoleSqlRunner, options: ProvisionConsoleRoleOptions): Promise<ConsoleRolePlan>;
+/**
+ * Creates (or rotates the password of) the restricted account with the main account's
+ * connection. Needs CREATEROLE (PostgreSQL) or CREATE USER + GRANT OPTION (MySQL); without them
+ * the first statement fails and the caller offers `--print-sql`.
+ */
+export declare function provisionConsoleRole(run: ConsoleSqlRunner, options: ProvisionConsoleRoleOptions): Promise<ConsoleRolePlan>;
+/**
+ * Version check of `CREATE USER IF NOT EXISTS` / `ALTER USER … IDENTIFIED BY` (MySQL 5.7.6,
+ * MariaDB 10.1.3); `undefined` when supported.
+ */
+export declare function mysqlVersionProblem(version: string): string | undefined;
+/** Role grants and PROXY grants in `SHOW GRANTS` output (`GRANT \`r\`@\`%\` TO …`, `GRANT PROXY ON …`). */
+export declare function mysqlRoleAndProxyGrants(lines: readonly string[]): {
+    readonly roles: readonly string[];
+    readonly proxies: readonly string[];
+};
+export interface ConsoleCredentialProbe {
+    readonly ok: boolean;
+    /** Why the account is not acceptable (empty when ok). */
+    readonly problems: readonly string[];
+    /** The account the connection logged in as. */
+    readonly user?: string;
+    /**
+     * For the log only (never shown to Console users): object names behind a problem, e.g. the
+     * SECURITY DEFINER functions the account may execute.
+     */
+    readonly details?: readonly string[];
+}
+/** How many SECURITY DEFINER functions a probe names in its log details. */
+export declare const PG_DEFINER_FUNCTIONS_LOGGED = 5;
+/**
+ * The account may EXECUTE a SECURITY DEFINER function owned by another role outside `pg_catalog` /
+ * `information_schema` (extension functions in other schemas included): it would run with that
+ * owner's rights. PUBLIC has EXECUTE on functions by default, so provisioning cannot fix this
+ * without changing everyone's access — the owner revokes it (or grants it explicitly) instead.
+ */
+export declare const PG_DEFINER_FUNCTION_PROBLEM: string;
+/**
+ * Functions that read or write server files or reach other servers (`pg_ls_*`, `pg_read_file`,
+ * `pg_read_binary_file`, `pg_stat_file`, server-side `lo_import` / `lo_export`, adminpack
+ * `pg_file_*`, `dblink*`): none of them may be executable by the console account (they are
+ * revoked from PUBLIC by default; an explicit grant or an extension that grants them is refused).
+ */
+export declare const PG_FILE_FUNCTIONS_QUERY = "SELECT DISTINCT p.proname AS name FROM pg_proc p\n    WHERE (p.proname LIKE 'pg\\_ls\\_%' OR p.proname IN ('pg_read_file', 'pg_read_binary_file', 'pg_stat_file', 'lo_import', 'lo_export')\n      OR p.proname LIKE 'pg\\_file\\_%' OR p.proname LIKE 'dblink%')\n      AND has_function_privilege(current_user, p.oid, 'EXECUTE')\n    ORDER BY 1";
+/** The query behind {@link PG_DEFINER_FUNCTION_PROBLEM} (at most PG_DEFINER_FUNCTIONS_LOGGED + 1 rows). */
+export declare const PG_DEFINER_FUNCTIONS_QUERY = "SELECT n.nspname AS schema, p.proname AS name FROM pg_proc p\n    JOIN pg_namespace n ON n.oid = p.pronamespace\n    WHERE p.prosecdef AND p.proowner <> (SELECT oid FROM pg_roles WHERE rolname = current_user)\n      AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_temp\\_%' AND n.nspname NOT LIKE 'pg\\_toast\\_temp\\_%'\n      AND has_function_privilege(current_user, p.oid, 'EXECUTE')\n    ORDER BY 1, 2 LIMIT 6";
+export interface ProbeConsoleCredentialOptions {
+    readonly dialect: ConsoleCredentialDialect;
+    /** `database.console.user`. */
+    readonly expectedUser: string;
+    /** The main account (`database.user`; PostgreSQL also the main connection's `current_user`). */
+    readonly mainUser?: string;
+}
+/**
+ * Checks, on the restricted connection itself, that it is the configured account and holds no
+ * more than {@link consoleRoleStatements} grants. Raw Console SQL stays off unless `ok`.
+ */
+export declare function probeConsoleCredential(run: ConsoleSqlRunner, options: ProbeConsoleCredentialOptions): Promise<ConsoleCredentialProbe>;
+export interface RefreshConsoleGrantsOptions {
+    readonly role: string;
+}
+/**
+ * PostgreSQL, main account: grants the account the table / sequence privileges on what exists in
+ * `public` now (tables created before the default privileges, or by another role the main
+ * account can grant for), and revokes everything on gateway-owned (`console_*`) tables that are
+ * still in the project database. Idempotent; run at instance start.
+ */
+export declare function refreshConsoleGrants(run: ConsoleSqlRunner, options: RefreshConsoleGrantsOptions): Promise<{
+    readonly granted: readonly string[];
+    readonly revoked: readonly string[];
+}>;
+export interface ConsoleCredential {
+    readonly user: string;
+    readonly password: string;
+}
+/**
+ * Connection options of the restricted Console account, built from the main connection's options
+ * (ADR 0059 §4): the main account's credentials never reach it — neither as fields nor inside a
+ * PostgreSQL `connectionString` (whose `user` / `password`, also as query parameters, would win over
+ * explicit fields, empty ones included) nor a MySQL `uri` (whose query parameters fill every falsy
+ * field: `?multipleStatements=true` would beat `false`, `?flags=LOCAL_FILES` would re-enable LOCAL
+ * INFILE). Pool of at most two connections, session reset on release; MySQL without
+ * `LOCAL_FILES` and multiple statements.
+ */
+export declare function consoleConnectionOptions(dialect: ConsoleCredentialDialect, main: Readonly<Record<string, unknown>>, credential: ConsoleCredential): Record<string, unknown>;