@h-ai/reldb 0.1.0-alpha8 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -1,295 +1,14 @@
-import { z } from 'zod';
+import { DbType, ReldbConfigInput, ReldbConfig } from './schemas.js';
+export { MysqlConfig, MysqlConfigSchema, MysqlOptionsSchema, MysqlPoolConfig, MysqlPoolConfigSchema, MysqlSslConfigSchema, PoolConfig, PoolConfigSchema, PostgresqlConfig, PostgresqlConfigSchema, ReldbConfigSchema, ReldbOperationLogConfig, ReldbOperationLogConfigSchema, ReldbTypeSchema, SqliteConfig, SqliteConfigSchema, SqliteOptionsSchema, SslConfig, SslConfigSchema } from './schemas.js';
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, PaginationOptionsInput, PaginatedResult, PaginationOptions } from '@h-ai/core';
-
-/**
- * @h-ai/reldb — 数据库配置 Schema
- *
- * 本文件定义数据库模块的配置结构，使用 Zod 进行运行时校验。
- * @module reldb-config
- */
-
-/**
- * 数据库类型枚举
- *
- * 支持的数据库类型：
- * - `sqlite` - SQLite 嵌入式数据库（使用 better-sqlite3）
- * - `postgresql` - PostgreSQL 数据库（使用 pg）
- * - `mysql` - MySQL 数据库（使用 mysql2）
- */
-declare const ReldbTypeSchema: z.ZodEnum<{
-    sqlite: "sqlite";
-    postgresql: "postgresql";
-    mysql: "mysql";
-}>;
-/** 数据库类型 */
-type DbType = z.infer<typeof ReldbTypeSchema>;
-/**
- * 连接池配置 Schema
- *
- * 用于 PostgreSQL 和 MySQL 的连接池管理。
- * SQLite 为嵌入式数据库，不使用连接池。
- *
- * @example
- * ```ts
- * const poolConfig = {
- *     min: 2,
- *     max: 20,
- *     idleTimeout: 30000,
- *     acquireTimeout: 10000
- * }
- * ```
- */
-declare const PoolConfigSchema: z.ZodObject<{
-    min: z.ZodDefault<z.ZodNumber>;
-    max: z.ZodDefault<z.ZodNumber>;
-    idleTimeout: z.ZodDefault<z.ZodNumber>;
-    acquireTimeout: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-/** 连接池配置类型 */
-type PoolConfig = z.infer<typeof PoolConfigSchema>;
-/**
- * SSL 配置 Schema
- *
- * 支持多种配置方式：
- * - `true/false` - 简单开关
- * - `'require'/'prefer'/'allow'/'disable'` - SSL 模式
- * - 自定义对象 - 详细 SSL 配置
- *
- * @example
- * ```ts
- * // 简单开关
- * ssl: true
- *
- * // SSL 模式
- * ssl: 'require'
- *
- * // 自定义配置
- * ssl: { rejectUnauthorized: false }
- * ```
- */
-declare const SslConfigSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-    require: "require";
-    prefer: "prefer";
-    allow: "allow";
-    disable: "disable";
-}>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
-/** SSL 配置类型 */
-type SslConfig = z.infer<typeof SslConfigSchema>;
-/**
- * SQLite 特定选项 Schema
- *
- * @example
- * ```ts
- * sqlite: {
- *     walMode: true,   // 启用 WAL 模式，提高并发性能
- *     readonly: false  // 只读模式
- * }
- * ```
- */
-declare const SqliteOptionsSchema: z.ZodObject<{
-    walMode: z.ZodDefault<z.ZodBoolean>;
-    readonly: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-/**
- * MySQL 特定选项 Schema
- *
- * @example
- * ```ts
- * mysql: {
- *     charset: 'utf8mb4',
- *     timezone: '+08:00'
- * }
- * ```
- */
-declare const MysqlOptionsSchema: z.ZodObject<{
-    charset: z.ZodDefault<z.ZodString>;
-    timezone: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/**
- * SQLite 配置 Schema
- *
- * @example
- * ```ts
- * // 文件数据库
- * { type: 'sqlite', database: './data.db' }
- *
- * // 内存数据库（用于测试）
- * { type: 'sqlite', database: ':memory:' }
- * ```
- */
-declare const SqliteConfigSchema: z.ZodObject<{
-    type: z.ZodLiteral<"sqlite">;
-    database: z.ZodString;
-    sqlite: z.ZodOptional<z.ZodObject<{
-        walMode: z.ZodDefault<z.ZodBoolean>;
-        readonly: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/**
- * PostgreSQL 配置 Schema
- *
- * @example
- * ```ts
- * // 使用连接字符串
- * { type: 'postgresql', url: 'postgres://user:pass@localhost:5432/mydb' }
- *
- * // 使用分开的字段
- * {
- *     type: 'postgresql',
- *     host: 'localhost',
- *     port: 5432,
- *     database: 'mydb',
- *     user: 'admin',
- *     password: 'secret',
- *     pool: { max: 20 }
- * }
- * ```
- */
-declare const PostgresqlConfigSchema: z.ZodObject<{
-    url: z.ZodOptional<z.ZodString>;
-    host: z.ZodDefault<z.ZodString>;
-    port: z.ZodOptional<z.ZodNumber>;
-    database: z.ZodString;
-    user: z.ZodOptional<z.ZodString>;
-    password: z.ZodOptional<z.ZodString>;
-    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        require: "require";
-        prefer: "prefer";
-        allow: "allow";
-        disable: "disable";
-    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
-    pool: z.ZodOptional<z.ZodObject<{
-        min: z.ZodDefault<z.ZodNumber>;
-        max: z.ZodDefault<z.ZodNumber>;
-        idleTimeout: z.ZodDefault<z.ZodNumber>;
-        acquireTimeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    type: z.ZodLiteral<"postgresql">;
-}, z.core.$strip>;
-/**
- * MySQL 配置 Schema
- *
- * @example
- * ```ts
- * // 使用连接字符串
- * { type: 'mysql', url: 'mysql://user:pass@localhost:3306/mydb' }
- *
- * // 使用分开的字段
- * {
- *     type: 'mysql',
- *     host: 'localhost',
- *     port: 3306,
- *     database: 'mydb',
- *     user: 'admin',
- *     password: 'secret',
- *     mysql: { charset: 'utf8mb4' }
- * }
- * ```
- */
-declare const MysqlConfigSchema: z.ZodObject<{
-    url: z.ZodOptional<z.ZodString>;
-    host: z.ZodDefault<z.ZodString>;
-    port: z.ZodOptional<z.ZodNumber>;
-    database: z.ZodString;
-    user: z.ZodOptional<z.ZodString>;
-    password: z.ZodOptional<z.ZodString>;
-    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        require: "require";
-        prefer: "prefer";
-        allow: "allow";
-        disable: "disable";
-    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
-    pool: z.ZodOptional<z.ZodObject<{
-        min: z.ZodDefault<z.ZodNumber>;
-        max: z.ZodDefault<z.ZodNumber>;
-        idleTimeout: z.ZodDefault<z.ZodNumber>;
-        acquireTimeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    type: z.ZodLiteral<"mysql">;
-    mysql: z.ZodOptional<z.ZodObject<{
-        charset: z.ZodDefault<z.ZodString>;
-        timezone: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/**
- * 统一数据库配置 Schema（判别联合体）
- *
- * 根据 `type` 字段区分不同数据库类型的配置。
- */
-declare const ReldbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"sqlite">;
-    database: z.ZodString;
-    sqlite: z.ZodOptional<z.ZodObject<{
-        walMode: z.ZodDefault<z.ZodBoolean>;
-        readonly: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strip>>;
-}, z.core.$strip>, z.ZodObject<{
-    url: z.ZodOptional<z.ZodString>;
-    host: z.ZodDefault<z.ZodString>;
-    port: z.ZodOptional<z.ZodNumber>;
-    database: z.ZodString;
-    user: z.ZodOptional<z.ZodString>;
-    password: z.ZodOptional<z.ZodString>;
-    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        require: "require";
-        prefer: "prefer";
-        allow: "allow";
-        disable: "disable";
-    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
-    pool: z.ZodOptional<z.ZodObject<{
-        min: z.ZodDefault<z.ZodNumber>;
-        max: z.ZodDefault<z.ZodNumber>;
-        idleTimeout: z.ZodDefault<z.ZodNumber>;
-        acquireTimeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    type: z.ZodLiteral<"postgresql">;
-}, z.core.$strip>, z.ZodObject<{
-    url: z.ZodOptional<z.ZodString>;
-    host: z.ZodDefault<z.ZodString>;
-    port: z.ZodOptional<z.ZodNumber>;
-    database: z.ZodString;
-    user: z.ZodOptional<z.ZodString>;
-    password: z.ZodOptional<z.ZodString>;
-    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
-        require: "require";
-        prefer: "prefer";
-        allow: "allow";
-        disable: "disable";
-    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
-    pool: z.ZodOptional<z.ZodObject<{
-        min: z.ZodDefault<z.ZodNumber>;
-        max: z.ZodDefault<z.ZodNumber>;
-        idleTimeout: z.ZodDefault<z.ZodNumber>;
-        acquireTimeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
-    type: z.ZodLiteral<"mysql">;
-    mysql: z.ZodOptional<z.ZodObject<{
-        charset: z.ZodDefault<z.ZodString>;
-        timezone: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>], "type">;
-/** 数据库配置类型（判别联合体） */
-type ReldbConfig = z.infer<typeof ReldbConfigSchema>;
-/** SQLite 配置类型 */
-type SqliteConfig = z.infer<typeof SqliteConfigSchema>;
-/** PostgreSQL 配置类型 */
-type PostgresqlConfig = z.infer<typeof PostgresqlConfigSchema>;
-/** MySQL 配置类型 */
-type MysqlConfig = z.infer<typeof MysqlConfigSchema>;
-/**
- * 数据库配置输入类型（用于 init 等入口）
- *
- * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
- * 因此对外 API（如 reldb.init）更适合接收 ReldbConfigInput。
- */
-type ReldbConfigInput = z.input<typeof ReldbConfigSchema>;
+import 'zod';
 
 /**
  * @h-ai/reldb — JSON 操作 SQL 构建器
  *
  * 为不同数据库后端提供统一的 JSON 路径操作 SQL 表达式构建能力。
- * 路径格式遵循 SQL/JSON Path 标准（`$.key` / `$.key.subkey` / `$[0]`）。
+ * 路径支持简单点号与方括号路径（`$.key` / `$.key.subkey` / `$[0]`），不是完整 SQL/JSON Path 校验器。
  *
  * 各数据库后端映射：
  *
@@ -299,7 +18,7 @@ type ReldbConfigInput = z.input<typeof ReldbConfigSchema>;
  * | set     | json_set + json()     | jsonb_set + ::jsonb            | JSON_SET + CAST AS JSON      |
  * | insert  | json_insert + json()  | jsonb_insert + ::jsonb         | JSON_INSERT + CAST AS JSON   |
  * | remove  | json_remove           | #- (text[])                   | JSON_REMOVE                 |
- * | merge   | json_patch            | \|\| ::jsonb                  | JSON_MERGE_PATCH + CAST      |
+ * | merge   | json_patch            | 参数化递归 CTE                 | JSON_MERGE_PATCH + CAST      |
  *
  * @module reldb-json
  */
@@ -308,15 +27,12 @@ type ReldbConfigInput = z.input<typeof ReldbConfigSchema>;
  *
  * 包含可嵌入 SQL 语句的表达式片段与对应参数列表。
  * 参数占位符统一使用 `?`，各 Provider 会在执行前自动转换。
- *
  * @example
  * ```ts
- * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
- * // 将 sql 和 params 嵌入到完整 SQL 中执行
- * await reldb.sql.execute(
- *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
- *   [...params, userId],
- * )
+ * import { createJsonOps, type JsonSqlExpr } from '@h-ai/reldb'
+ *
+ * const expression: JsonSqlExpr = createJsonOps('postgresql').set('settings', '$.theme', 'dark')
+ * void [expression.sql, expression.params]
  * ```
  */
 interface JsonSqlExpr {
@@ -331,25 +47,16 @@ interface JsonSqlExpr {
  * 提供跨数据库统一的 JSON 路径操作 SQL 构建能力。
  * 所有方法返回 `JsonSqlExpr`，可嵌入 `reldb.sql.query` / `reldb.sql.execute` 等调用。
  *
- * 路径格式：遵循 SQL/JSON Path 标准，以 `$` 开头：
+ * 路径使用以下简单形式，建议以 `$` 开头：
  * - 对象字段：`$.key`、`$.key.subkey`
  * - 数组元素：`$[0]`、`$.items[1]`
- *
  * @example
  * ```ts
- * // 提取 JSON 字段值（用于 SELECT 或 WHERE）
- * const { sql, params } = reldb.json.extract('settings', '$.theme')
- * const rows = await reldb.sql.query(
- *   `SELECT * FROM users WHERE ${sql} = ?`,
- *   [...params, '"dark"'],
- * )
- *
- * // 设置 JSON 字段的某个路径（用于 UPDATE SET）
- * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
- * await reldb.sql.execute(
- *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
- *   [...params, userId],
- * )
+ * import { createJsonOps, type ReldbJsonOps } from '@h-ai/reldb'
+ *
+ * const json: ReldbJsonOps = createJsonOps('postgresql')
+ * const patch = json.merge('settings', { theme: 'dark', obsolete: null })
+ * void patch // 作为同一次 UPDATE 的 SQL 表达式执行，值在 params。
  * ```
  */
 interface ReldbJsonOps {
@@ -362,55 +69,52 @@ interface ReldbJsonOps {
      * @param column - 列名（或 SQL 列表达式，开发者负责安全性，禁止传入用户输入）
      * @param path - JSON 路径（如 `$.status`、`$.user.name`、`$[0]`）
      * @returns SQL 表达式与参数
-     *
      * @example
      * ```ts
-     * const { sql, params } = reldb.json.extract('data', '$.status')
-     * // SQLite:     sql = "json_extract(data, ?)",    params = ["$.status"]
-     * // PostgreSQL: sql = "data #> ?::text[]",         params = [["status"]]
-     * // MySQL:      sql = "JSON_EXTRACT(data, ?)",     params = ["$.status"]
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const expression = reldb.json.extract('settings', '$.theme')
+     * void [expression.sql, expression.params]
      * ```
      */
     extract: (column: string, path: string) => JsonSqlExpr;
     /**
      * JSON 路径设置表达式（创建或替换）
      *
-     * 在 JSON 列的指定路径设置新值。若路径不存在则创建，若已存在则替换。
+     * 设置指定路径的值；PostgreSQL 要求父路径存在，其他后端按原生 JSON 函数处理缺失父路径。
      * 返回修改后的完整 JSON 值，通常用于 `UPDATE SET col = ...`。
      *
      * @param column - 列名（开发者负责安全性，禁止传入用户输入）
      * @param path - JSON 路径
      * @param value - 要设置的值（支持任意 JSON 兼容类型）
      * @returns SQL 表达式与参数
-     *
      * @example
      * ```ts
-     * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
-     * await reldb.sql.execute(
-     *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
-     *   [...params, id],
-     * )
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const expression = reldb.json.set('settings', '$.theme', 'dark')
+     * const result = await reldb.sql.execute(`UPDATE users SET settings = ${expression.sql} WHERE id = ?`, [...expression.params, 'u1'])
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     set: (column: string, path: string, value: unknown) => JsonSqlExpr;
     /**
      * JSON 路径插入表达式（仅当路径不存在时）
      *
-     * 仅在指定路径不存在时插入新值，已存在的路径不会被覆盖。
+     * 使用后端原生插入语义：SQLite/MySQL 不覆盖已有值；PostgreSQL 对已有对象键报错，数组路径按 jsonb_insert 插入。
      * 返回修改后的完整 JSON 值。
      *
      * @param column - 列名（开发者负责安全性，禁止传入用户输入）
      * @param path - JSON 路径
      * @param value - 要插入的值
      * @returns SQL 表达式与参数
-     *
      * @example
      * ```ts
-     * const { sql, params } = reldb.json.insert('data', '$.newField', 'value')
-     * await reldb.sql.execute(
-     *   `UPDATE items SET data = ${sql} WHERE id = ?`,
-     *   [...params, id],
-     * )
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const expression = reldb.json.insert('settings', '$.newField', 'value')
+     * const result = await reldb.sql.execute(`UPDATE users SET settings = ${expression.sql} WHERE id = ?`, [...expression.params, 'u1'])
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     insert: (column: string, path: string, value: unknown) => JsonSqlExpr;
@@ -423,14 +127,13 @@ interface ReldbJsonOps {
      * @param column - 列名（开发者负责安全性，禁止传入用户输入）
      * @param path - JSON 路径
      * @returns SQL 表达式与参数
-     *
      * @example
      * ```ts
-     * const { sql, params } = reldb.json.remove('settings', '$.deprecated')
-     * await reldb.sql.execute(
-     *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
-     *   [...params, id],
-     * )
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const expression = reldb.json.remove('settings', '$.obsolete')
+     * const result = await reldb.sql.execute(`UPDATE users SET settings = ${expression.sql} WHERE id = ?`, [...expression.params, 'u1'])
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     remove: (column: string, path: string) => JsonSqlExpr;
@@ -447,14 +150,13 @@ interface ReldbJsonOps {
      * @param column - 列名（开发者负责安全性，禁止传入用户输入）
      * @param patch - 要合并的 JSON 对象
      * @returns SQL 表达式与参数
-     *
      * @example
      * ```ts
-     * const { sql, params } = reldb.json.merge('profile', { bio: 'new bio', avatar: null })
-     * await reldb.sql.execute(
-     *   `UPDATE users SET profile = ${sql} WHERE id = ?`,
-     *   [...params, id],
-     * )
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const expression = reldb.json.merge('settings', { theme: 'dark', obsolete: null })
+     * const result = await reldb.sql.execute(`UPDATE users SET settings = ${expression.sql} WHERE id = ?`, [...expression.params, 'u1'])
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     merge: (column: string, patch: Record<string, unknown>) => JsonSqlExpr;
@@ -466,12 +168,11 @@ interface ReldbJsonOps {
  *
  * @param path - JSON 路径（以 `$` 开头）
  * @returns 路径段数组
- *
  * @example
  * ```ts
- * parseJsonPath('$.user.name')  // ['user', 'name']
- * parseJsonPath('$.items[0]')   // ['items', '0']
- * parseJsonPath('$[1]')         // ['1']
+ * import { parseJsonPath } from '@h-ai/reldb'
+ *
+ * void parseJsonPath('$.items[0].name') // ['items', '0', 'name']
  * ```
  */
 declare function parseJsonPath(path: string): string[];
@@ -480,19 +181,28 @@ declare function parseJsonPath(path: string): string[];
  *
  * @param dbType - 数据库类型（来自 `reldb.config?.type`）
  * @returns JSON 操作实例
- *
  * @example
  * ```ts
- * // 通过 reldb.json 直接使用（推荐）
- * const { sql, params } = reldb.json.extract('data', '$.key')
+ * import { createJsonOps } from '@h-ai/reldb'
  *
- * // 手动创建（用于测试或特殊场景）
- * const jsonOps = createJsonOps('sqlite')
- * const { sql, params } = jsonOps.set('data', '$.key', 'value')
+ * const sqlite = createJsonOps('sqlite')
+ * const expression = sqlite.extract('settings', '$.theme')
+ * void expression
  * ```
  */
 declare function createJsonOps(dbType: 'sqlite' | 'postgresql' | 'mysql'): ReldbJsonOps;
 
+/**
+ * HaiReldbError 的数据约束与操作契约。
+ * @example
+ * ```ts
+ * import { HaiReldbError } from '@h-ai/reldb'
+ * import { err } from '@h-ai/core'
+ *
+ * const result = err(HaiReldbError.QUERY_FAILED, 'Query failed')
+ * if (!result.success) void result.error.code
+ * ```
+ */
 declare const HaiReldbError: {
     CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
     QUERY_FAILED: _h_ai_core.HaiErrorDef;
@@ -503,11 +213,11 @@ declare const HaiReldbError: {
     DUPLICATE_ENTRY: _h_ai_core.HaiErrorDef;
     DEADLOCK: _h_ai_core.HaiErrorDef;
     TIMEOUT: _h_ai_core.HaiErrorDef;
-    POOL_EXHAUSTED: _h_ai_core.HaiErrorDef;
     NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
-    DDL_FAILED: _h_ai_core.HaiErrorDef;
+    POOL_EXHAUSTED: _h_ai_core.HaiErrorDef;
     UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
     CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    DDL_FAILED: _h_ai_core.HaiErrorDef;
 };
 /**
  * 列数据类型
@@ -517,7 +227,8 @@ declare const HaiReldbError: {
  * | 类型        | SQLite  | PostgreSQL       | MySQL        |
  * |------------|---------|------------------|--------------|
  * | TEXT       | TEXT    | TEXT             | VARCHAR(255) |
- * | INTEGER    | INTEGER | INTEGER/SERIAL   | INT/BIGINT   |
+ * | INTEGER    | INTEGER | INTEGER/BIGSERIAL | INT/BIGINT   |
+ * | BIGINT     | INTEGER | BIGINT           | BIGINT       |
  * | REAL       | REAL    | DOUBLE PRECISION | DOUBLE       |
  * | BLOB       | BLOB    | BYTEA            | BLOB         |
  * | BOOLEAN    | INTEGER | BOOLEAN          | TINYINT(1)   |
@@ -525,33 +236,28 @@ declare const HaiReldbError: {
  * | JSON       | TEXT    | JSONB            | JSON         |
  *
  * 注：MySQL 将 TEXT 映射为 VARCHAR(255) 以支持索引和 UNIQUE 约束。
- * INTEGER 在 MySQL autoIncrement 时映射为 BIGINT，否则映射为 INT。
+ * INTEGER 在 MySQL autoIncrement 时映射为 BIGINT，在 PostgreSQL 映射为 BIGSERIAL，否则为 32 位 INT/INTEGER。
+ * Unix 毫秒应声明为 BIGINT；原始 SQL/CRUD 的 BIGINT 返回形态取决于驱动，可能为 number/string/bigint。
+ * 使用 number 的业务仓库须校验 Number.isSafeInteger，超出范围不能直接强转而丢失精度。
+ * @example
+ * ```ts
+ * import type { ColumnType } from '@h-ai/reldb'
+ *
+ * const value: ColumnType = 'TEXT'
+ * void value
+ * ```
  */
-type ColumnType = 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON';
+type ColumnType = 'TEXT' | 'INTEGER' | 'BIGINT' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON';
 /**
  * 列定义接口
  *
  * 用于定义表的列结构。
- *
  * @example
  * ```ts
- * // 主键列
- * const idColumn: ReldbColumnDef = {
- *     type: 'INTEGER',
- *     primaryKey: true,
- *     autoIncrement: true
- * }
+ * import type { ReldbColumnDef } from '@h-ai/reldb'
  *
- * // 带外键的列
- * const userIdColumn: ReldbColumnDef = {
- *     type: 'INTEGER',
- *     notNull: true,
- *     references: {
- *         table: 'users',
- *         column: 'id',
- *         onDelete: 'CASCADE'
- *     }
- * }
+ * const value: ReldbColumnDef = { type: 'INTEGER', primaryKey: true, autoIncrement: true }
+ * void value
  * ```
  */
 interface ReldbColumnDef {
@@ -581,15 +287,12 @@ interface ReldbColumnDef {
 }
 /**
  * 表定义（列名到列定义的映射）
- *
  * @example
  * ```ts
- * const userTable: ReldbTableDef = {
- *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
- *     name: { type: 'TEXT', notNull: true },
- *     email: { type: 'TEXT', unique: true },
- *     created_at: { type: 'TIMESTAMP', defaultValue: 'NOW()' }
- * }
+ * import type { ReldbTableDef } from '@h-ai/reldb'
+ *
+ * const value: ReldbTableDef = { id: { type: 'TEXT', primaryKey: true }, name: { type: 'TEXT', notNull: true } }
+ * void value
  * ```
  */
 interface ReldbTableDef {
@@ -597,23 +300,12 @@ interface ReldbTableDef {
 }
 /**
  * 索引定义
- *
  * @example
  * ```ts
- * // 普通索引
- * const emailIndex: ReldbIndexDef = { columns: ['email'] }
+ * import type { ReldbIndexDef } from '@h-ai/reldb'
  *
- * // 唯一复合索引
- * const compositeIndex: ReldbIndexDef = {
- *     columns: ['user_id', 'created_at'],
- *     unique: true
- * }
- *
- * // 部分索引（带条件）
- * const partialIndex: ReldbIndexDef = {
- *     columns: ['status'],
- *     where: "status = 'active'"
- * }
+ * const value: ReldbIndexDef = { columns: ['email'], unique: true }
+ * void value
  * ```
  */
 interface ReldbIndexDef {
@@ -626,6 +318,13 @@ interface ReldbIndexDef {
      *
      * **⚠️ 安全警告：** `where` 为原始 SQL 片段，不会经过参数化处理，
      * **禁止**将用户输入直接拼接。仅用于开发者编写的静态条件。
+     * @example
+     * ```ts
+     * import type { CrudQueryOptions } from '@h-ai/reldb'
+     *
+     * const options: CrudQueryOptions = { where: 'name = ?', params: ['Alice'] }
+     * void options // 值走绑定参数；SQL 结构由开发者静态编写。
+     * ```
      */
     where?: string;
 }
@@ -633,18 +332,15 @@ interface ReldbIndexDef {
  * DDL（数据定义语言）操作接口
  *
  * 提供表结构管理功能，包括创建/删除表、添加/删除列、创建索引等。
- * 所有操作返回 `HaiResult<void>` 类型。
- *
+ * 结构修改返回 `HaiResult<void>`；hasTable 返回 `HaiResult<boolean>`，以实际签名为准。
  * @example
  * ```ts
- * // 创建表
- * const result = await reldb.ddl.createTable('users', {
- *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
- *     name: { type: 'TEXT', notNull: true }
- * })
- *
- * if (!result.success) {
- *     // 处理错误：创建表失败（可根据 result.error.code / message 做兜底）
+ * import type { DdlOperations } from '@h-ai/reldb'
+ *
+ * async function use(operations: DdlOperations) {
+ *   const result = await operations.createTable('users', { id: { type: 'TEXT', primaryKey: true } })
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
  * }
  * ```
  */
@@ -656,13 +352,11 @@ interface DdlOperations {
      * @param ifNotExists - 是否使用 IF NOT EXISTS（默认 true）
      * @example
      * ```ts
-     * const result = await reldb.ddl.createTable('users', {
-     *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
-     *     name: { type: 'TEXT', notNull: true }
-     * })
-     * if (!result.success) {
-     *     // 创建失败：根据 result.error.code / message 处理
-     * }
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.createTable('users', { id: { type: 'TEXT', primaryKey: true }, name: { type: 'TEXT' } })
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     createTable: (tableName: string, columns: ReldbTableDef, ifNotExists?: boolean) => Promise<HaiResult<void>>;
@@ -672,8 +366,11 @@ interface DdlOperations {
      * @param ifExists - 是否使用 IF EXISTS（默认 true）
      * @example
      * ```ts
-     * await reldb.ddl.dropTable('users')
-     * await reldb.ddl.dropTable('users_backup', false)
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.dropTable('users_backup')
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     dropTable: (tableName: string, ifExists?: boolean) => Promise<HaiResult<void>>;
@@ -684,8 +381,11 @@ interface DdlOperations {
      * @param columnDef - 列定义
      * @example
      * ```ts
-     * await reldb.ddl.addColumn('users', 'age', { type: 'INTEGER' })
-     * await reldb.ddl.addColumn('users', 'email', { type: 'TEXT', unique: true })
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.addColumn('users', 'age', { type: 'INTEGER' })
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     addColumn: (tableName: string, columnName: string, columnDef: ReldbColumnDef) => Promise<HaiResult<void>>;
@@ -695,7 +395,11 @@ interface DdlOperations {
      * @param columnName - 列名
      * @example
      * ```ts
-     * await reldb.ddl.dropColumn('users', 'legacy_field')
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.dropColumn('users', 'legacy_field')
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     dropColumn: (tableName: string, columnName: string) => Promise<HaiResult<void>>;
@@ -705,7 +409,11 @@ interface DdlOperations {
      * @param newName - 新表名
      * @example
      * ```ts
-     * await reldb.ddl.renameTable('users_temp', 'users')
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.renameTable('users_old', 'users')
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     renameTable: (oldName: string, newName: string) => Promise<HaiResult<void>>;
@@ -716,10 +424,11 @@ interface DdlOperations {
      * @param indexDef - 索引定义
      * @example
      * ```ts
-     * await reldb.ddl.createIndex('users', 'idx_users_email', {
-     *     columns: ['email'],
-     *     unique: true,
-     * })
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.createIndex('users', 'users_name_idx', { columns: ['name'] })
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     createIndex: (tableName: string, indexName: string, indexDef: ReldbIndexDef) => Promise<HaiResult<void>>;
@@ -729,7 +438,11 @@ interface DdlOperations {
      * @param ifExists - 是否使用 IF EXISTS（默认 true）
      * @example
      * ```ts
-     * await reldb.ddl.dropIndex('idx_users_email')
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.ddl.dropIndex('users_name_idx')
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     dropIndex: (indexName: string, ifExists?: boolean) => Promise<HaiResult<void>>;
@@ -743,11 +456,11 @@ interface DdlOperations {
      * @param sql - DDL SQL 语句（必须为开发者静态构造，禁止包含用户输入）
      * @example
      * ```ts
-     * // ✅ 安全：静态 SQL
-     * await reldb.ddl.raw('ALTER TABLE users ADD COLUMN status TEXT')
+     * import { reldb } from '@h-ai/reldb'
      *
-     * // ❌ 危险：拼接用户输入
-     * await reldb.ddl.raw(`ALTER TABLE ${userInput} ADD COLUMN status TEXT`)
+     * const result = await reldb.ddl.raw('ALTER TABLE users ADD COLUMN status TEXT')
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
      * ```
      */
     raw: (sql: string) => Promise<HaiResult<void>>;
@@ -756,12 +469,26 @@ interface DdlOperations {
  * 查询结果行类型
  *
  * 约定为键值对象，字段名与 SQL 返回列一致。
+ * @example
+ * ```ts
+ * import type { QueryRow } from '@h-ai/reldb'
+ *
+ * const value: QueryRow = { id: 'u1', name: 'Alice' }
+ * void value
+ * ```
  */
 type QueryRow = Record<string, unknown>;
 /**
  * 执行结果
  *
  * INSERT/UPDATE/DELETE 操作返回的结果。
+ * @example
+ * ```ts
+ * import type { ExecuteResult } from '@h-ai/reldb'
+ *
+ * const value: ExecuteResult = { changes: 1 }
+ * void value
+ * ```
  */
 interface ExecuteResult {
     /** 影响的行数 */
@@ -771,6 +498,13 @@ interface ExecuteResult {
 }
 /**
  * 规范化后的分页参数
+ * @example
+ * ```ts
+ * import type { NormalizedPagination } from '@h-ai/reldb'
+ *
+ * const value: NormalizedPagination = { page: 2, pageSize: 10, offset: 10, limit: 10 }
+ * void value
+ * ```
  */
 interface NormalizedPagination extends PaginationOptions {
     /** SQL offset */
@@ -780,6 +514,13 @@ interface NormalizedPagination extends PaginationOptions {
 }
 /**
  * 分页参数覆盖
+ * @example
+ * ```ts
+ * import type { PaginationOverrides } from '@h-ai/reldb'
+ *
+ * const value: PaginationOverrides = { defaultPageSize: 20, maxPageSize: 100 }
+ * void value
+ * ```
  */
 interface PaginationOverrides {
     /** 默认页码 */
@@ -791,6 +532,13 @@ interface PaginationOverrides {
 }
 /**
  * 分页查询参数
+ * @example
+ * ```ts
+ * import type { PaginationQueryOptions } from '@h-ai/reldb'
+ *
+ * const value: PaginationQueryOptions = { sql: 'SELECT id, name FROM users WHERE active = ?', params: [true], pagination: { page: 2, pageSize: 10 } }
+ * void value
+ * ```
  */
 interface PaginationQueryOptions {
     /** 数据查询 SQL（不含 LIMIT/OFFSET） */
@@ -804,37 +552,104 @@ interface PaginationQueryOptions {
 }
 /**
  * 数据读写操作接口（SQL / 事务共享）
+ * @example
+ * ```ts
+ * import type { DmlOperations } from '@h-ai/reldb'
+ *
+ * async function use(operations: DmlOperations) {
+ *   const result = await operations.query<{ id: string }>('SELECT id FROM users WHERE name = ?', ['Alice'])
+ *   if (!result.success) throw new Error(result.error.message)
+ *   return result.data
+ * }
+ * ```
  */
 interface DmlOperations {
-    /** 查询多行 */
+    /**
+     * 查询多行
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.sql.query<{ id: string }>('SELECT id FROM users WHERE name = ?', ['Alice'])
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
+     */
     query: <T = QueryRow>(sql: string, params?: unknown[]) => Promise<HaiResult<T[]>>;
-    /** 查询单行 */
+    /**
+     * 查询单行
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.sql.get<{ id: string }>('SELECT id FROM users WHERE name = ?', ['Alice'])
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
+     */
     get: <T = QueryRow>(sql: string, params?: unknown[]) => Promise<HaiResult<T | null>>;
-    /** 执行修改语句（INSERT/UPDATE/DELETE） */
+    /**
+     * 执行修改语句（INSERT/UPDATE/DELETE）
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.sql.execute('UPDATE users SET name = ? WHERE id = ?', ['Alice', 'u1'])
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
+     */
     execute: (sql: string, params?: unknown[]) => Promise<HaiResult<ExecuteResult>>;
-    /** 批量执行多条语句（在同一事务上下文中） */
+    /**
+     * 批量执行多条语句（在同一事务上下文中）
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.sql.batch([{ sql: 'UPDATE users SET name = ? WHERE id = ?', params: ['Alice', 'u1'] }])
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
+     */
     batch: (statements: Array<{
         sql: string;
         params?: unknown[];
     }>) => Promise<HaiResult<void>>;
-    /** 分页查询 */
+    /**
+     * 分页查询
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.sql.queryPage<{ id: string }>({ sql: 'SELECT id FROM users', pagination: { page: 1, pageSize: 10 } })
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
+     */
     queryPage: <T = QueryRow>(options: PaginationQueryOptions) => Promise<HaiResult<PaginatedResult<T>>>;
 }
-/** CRUD 查询条件 */
+/**
+ * CRUD 查询条件
+ * @example
+ * ```ts
+ * import type { CrudQueryOptions } from '@h-ai/reldb'
+ *
+ * const value: CrudQueryOptions = { where: 'name = ?', params: ['Alice'], orderBy: 'id ASC', limit: 10 }
+ * void value
+ * ```
+ */
 interface CrudQueryOptions {
     /**
      * WHERE 子句（不包含 WHERE 关键字）
      *
      * **⚠️ 安全警告：** `where` 为原始 SQL 片段，**禁止**将用户输入直接拼接。
      * 动态值必须通过 `params` 占位符（`?`）传入。
-     *
      * @example
      * ```ts
-     * // ✅ 安全：占位符 + params
-     * crud.findAll({ where: 'status = ? AND age > ?', params: ['active', 18] })
+     * import type { CrudQueryOptions } from '@h-ai/reldb'
      *
-     * // ❌ 危险：拼接用户输入
-     * crud.findAll({ where: `name = '${userInput}'` })
+     * const options: CrudQueryOptions = { where: 'name = ?', params: ['Alice'] }
+     * void options // 值走绑定参数；SQL 结构由开发者静态编写。
      * ```
      */
     where?: string;
@@ -847,13 +662,29 @@ interface CrudQueryOptions {
     /** OFFSET */
     offset?: number;
 }
-/** CRUD 分页查询条件 */
+/**
+ * CRUD 分页查询条件
+ * @example
+ * ```ts
+ * import type { CrudPageOptions } from '@h-ai/reldb'
+ *
+ * const value: CrudPageOptions = { where: 'active = ?', params: [true], pagination: { page: 1, pageSize: 20 } }
+ * void value
+ * ```
+ */
 interface CrudPageOptions {
     /**
      * WHERE 子句（不包含 WHERE 关键字）
      *
      * **⚠️ 安全警告：** `where` 为原始 SQL 片段，**禁止**将用户输入直接拼接。
      * 动态值必须通过 `params` 占位符（`?`）传入。
+     * @example
+     * ```ts
+     * import type { CrudQueryOptions } from '@h-ai/reldb'
+     *
+     * const options: CrudQueryOptions = { where: 'name = ?', params: ['Alice'] }
+     * void options // 值走绑定参数；SQL 结构由开发者静态编写。
+     * ```
      */
     where?: string;
     /** 参数列表 */
@@ -865,19 +696,44 @@ interface CrudPageOptions {
     /** 分页参数覆盖 */
     overrides?: PaginationOverrides;
 }
-/** CRUD 统计条件 */
+/**
+ * CRUD 统计条件
+ * @example
+ * ```ts
+ * import type { ReldbCrudCountOptions } from '@h-ai/reldb'
+ *
+ * const value: ReldbCrudCountOptions = { where: 'active = ?', params: [true] }
+ * void value
+ * ```
+ */
 interface ReldbCrudCountOptions {
     /**
      * WHERE 子句（不包含 WHERE 关键字）
      *
      * **⚠️ 安全警告：** `where` 为原始 SQL 片段，**禁止**将用户输入直接拼接。
      * 动态值必须通过 `params` 占位符（`?`）传入。
+     * @example
+     * ```ts
+     * import type { CrudQueryOptions } from '@h-ai/reldb'
+     *
+     * const options: CrudQueryOptions = { where: 'name = ?', params: ['Alice'] }
+     * void options // 值走绑定参数；SQL 结构由开发者静态编写。
+     * ```
      */
     where?: string;
     /** 参数列表 */
     params?: unknown[];
 }
-/** CRUD 配置 */
+/**
+ * CRUD 配置
+ * @example
+ * ```ts
+ * import type { CrudConfig } from '@h-ai/reldb'
+ *
+ * const config: CrudConfig<{ id: string }> = { table: 'users', dbType: 'postgresql', select: ['id'], createColumns: ['id'], updateColumns: [] }
+ * void config
+ * ```
+ */
 interface CrudConfig<TItem> {
     /** 表名 */
     table: string;
@@ -894,7 +750,16 @@ interface CrudConfig<TItem> {
     /** 数据库类型 */
     dbType: DbType;
 }
-/** CRUD 字段定义 */
+/**
+ * CRUD 字段定义
+ * @example
+ * ```ts
+ * import type { ReldbCrudFieldDefinition } from '@h-ai/reldb'
+ *
+ * const value: ReldbCrudFieldDefinition = { fieldName: 'name', columnName: 'name', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true }
+ * void value
+ * ```
+ */
 interface ReldbCrudFieldDefinition {
     /** 对象字段名 */
     fieldName: string;
@@ -909,7 +774,20 @@ interface ReldbCrudFieldDefinition {
     /** 是否允许更新 */
     update: boolean;
 }
-/** BaseReldbCrudRepository 配置 */
+/**
+ * BaseReldbCrudRepository 配置
+ * @example
+ * ```ts
+ * import type { BaseReldbCrudRepositoryConfig } from '@h-ai/reldb'
+ *
+ * const config: BaseReldbCrudRepositoryConfig<{ id: string }> = {
+ *   table: 'users', idField: 'id', fields: [
+ *     { fieldName: 'id', columnName: 'id', def: { type: 'TEXT', primaryKey: true }, select: true, create: true, update: false },
+ *   ],
+ * }
+ * void config
+ * ```
+ */
 interface BaseReldbCrudRepositoryConfig<TItem> {
     /** 表名 */
     table: string;
@@ -926,7 +804,19 @@ interface BaseReldbCrudRepositoryConfig<TItem> {
     /** 当前时间提供者（默认 Date.now） */
     nowProvider?: () => number;
 }
-/** CRUD 仓库接口 */
+/**
+ * CRUD 仓库接口
+ * @example
+ * ```ts
+ * import type { ReldbCrudRepository } from '@h-ai/reldb'
+ *
+ * async function use(operations: ReldbCrudRepository<{ id: string }>) {
+ *   const result = await operations.findById('u1')
+ *   if (!result.success) throw new Error(result.error.message)
+ *   return result.data
+ * }
+ * ```
+ */
 interface ReldbCrudRepository<TItem> {
     create: (data: Record<string, unknown>, tx?: DmlWithTxOperations) => Promise<HaiResult<ExecuteResult>>;
     createMany: (items: Array<Record<string, unknown>>, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
@@ -941,13 +831,37 @@ interface ReldbCrudRepository<TItem> {
     exists: (options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations) => Promise<HaiResult<boolean>>;
     existsById: (id: unknown, tx?: DmlWithTxOperations) => Promise<HaiResult<boolean>>;
 }
-/** CRUD 管理器（统一入口） */
+/**
+ * CRUD 管理器（统一入口）
+ * @example
+ * ```ts
+ * import type { CrudManager } from '@h-ai/reldb'
+ *
+ * async function use(operations: CrudManager) {
+ *   const result = await operations.table<{ id: string }>({ table: 'users', dbType: 'postgresql' }).findById('u1')
+ *   if (!result.success) throw new Error(result.error.message)
+ *   return result.data
+ * }
+ * ```
+ */
 interface CrudManager {
     /** 获取单表 CRUD 仓库 */
     table: <TItem>(config: CrudConfig<TItem>) => ReldbCrudRepository<TItem>;
 }
 /**
  * 事务句柄接口（分步事务）
+ * @example
+ * ```ts
+ * import type { DmlWithTxOperations } from '@h-ai/reldb'
+ *
+ * async function use(operations: DmlWithTxOperations) {
+ *   const result = await operations.execute('UPDATE users SET name = ? WHERE id = ?', ['Alice', 'u1'])
+ *   if (!result.success) throw new Error(result.error.message)
+ *   const committed = await operations.commit()
+ *   if (!committed.success) throw new Error(committed.error.message)
+ *   return result.data.changes
+ * }
+ * ```
  */
 interface DmlWithTxOperations extends DmlOperations {
     /** CRUD 管理器 */
@@ -961,18 +875,36 @@ interface DmlWithTxOperations extends DmlOperations {
  * 事务回调函数类型
  *
  * @param tx - 事务内操作对象
- * @returns 业务返回值（将被包装为 HaiResult）
+ * @returns 业务返回值（将被包装为 HaiResult）；callback 抛错才回滚，返回失败 HaiResult 不会被自动展开。
  * @example
  * ```ts
- * const result = await reldb.tx.wrap(async (tx) => {
- *     await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户A'])
- *     return await tx.get('SELECT * FROM users WHERE name = ?', ['用户A'])
- * })
+ * import type { TxWrapCallback } from '@h-ai/reldb'
+ *
+ * const insert: TxWrapCallback<number> = async (tx) => {
+ *   const result = await tx.execute('INSERT INTO users (id, name) VALUES (?, ?)', ['u1', 'Alice'])
+ *   if (!result.success) throw new Error(result.error.message) // 显式抛错触发 wrap 回滚。
+ *   return result.data.changes
+ * }
+ * void insert
  * ```
  */
 type TxWrapCallback<T> = (tx: DmlWithTxOperations) => Promise<T>;
 /**
  * 事务管理器
+ * @example
+ * ```ts
+ * import type { TxManager } from '@h-ai/reldb'
+ *
+ * async function use(operations: TxManager) {
+ *   const result = await operations.wrap(async (tx) => {
+ *     const changed = await tx.execute('UPDATE users SET name = ? WHERE id = ?', ['Alice', 'u1'])
+ *     if (!changed.success) throw new Error(changed.error.message)
+ *     return changed.data.changes
+ *   })
+ *   if (!result.success) throw new Error(result.error.message)
+ *   return result.data
+ * }
+ * ```
  */
 interface TxManager {
     /** 开启事务（分步事务） */
@@ -984,30 +916,21 @@ interface TxManager {
  * 数据库函数接口
  *
  * 统一的数据库访问入口，通过 `reldb` 对象提供所有数据库操作。
- *
  * @example
  * ```ts
  * import { reldb } from '@h-ai/reldb'
  *
- * // 初始化
- * await reldb.init({ type: 'sqlite', database: ':memory:' })
- *
- * // 检查状态
- * if (reldb.isInitialized) {
- *     // 可读取当前数据库类型：reldb.config?.type
+ * const initialized = await reldb.init({ type: 'sqlite', database: ':memory:' }) // 仅示例/测试。
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const created = await reldb.ddl.createTable('users', { id: { type: 'TEXT', primaryKey: true }, name: { type: 'TEXT' } })
+ *   if (!created.success) throw new Error(created.error.message)
+ *   const inserted = await reldb.sql.execute('INSERT INTO users (id, name) VALUES (?, ?)', ['u1', 'Alice'])
+ *   if (!inserted.success) throw new Error(inserted.error.message)
+ * } finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
  * }
- *
- * // 使用 DDL
- * await reldb.ddl.createTable('users', { ... })
- *
- * // 使用 SQL
- * await reldb.sql.query('SELECT * FROM users')
- *
- * // 使用事务
- * await reldb.tx.wrap(async (tx) => { ... })
- *
- * // 关闭连接
- * await reldb.close()
  * ```
  */
 interface ReldbFunctions {
@@ -1016,6 +939,14 @@ interface ReldbFunctions {
      *
      * @param config - 数据库配置
      * @returns 初始化结果
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.init({ type: 'sqlite', database: ':memory:' })
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
      */
     init: (config: ReldbConfigInput) => Promise<HaiResult<void>>;
     /** DDL 操作（表结构管理） */
@@ -1026,7 +957,7 @@ interface ReldbFunctions {
     readonly crud: CrudManager;
     /** 事务管理器 */
     readonly tx: TxManager;
-    /** 当前数据库配置（未初始化时为 null） */
+    /** 当前数据库脱敏配置快照（未初始化时为 null） */
     readonly config: ReldbConfig | null;
     /** 是否已初始化 */
     readonly isInitialized: boolean;
@@ -1044,49 +975,29 @@ interface ReldbFunctions {
      * 返回的 SQL 片段可嵌入 `reldb.sql.query` / `reldb.sql.execute` 等调用。
      *
      * 未初始化时默认返回 SQLite 格式的构建器；初始化后自动匹配当前数据库类型。
-     *
      * @example
      * ```ts
-     * // 提取 JSON 字段值（用于 WHERE 条件）
-     * const { sql, params } = reldb.json.extract('settings', '$.theme')
-     * const rows = await reldb.sql.query(
-     *   `SELECT * FROM users WHERE ${sql} = ?`,
-     *   [...params, '"dark"'],
-     * )
-     *
-     * // 设置 JSON 字段路径
-     * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
-     * await reldb.sql.execute(
-     *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
-     *   [...params, userId],
-     * )
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const expression = reldb.json.set('settings', '$.theme', 'dark')
+     * const result = await reldb.sql.execute(`UPDATE users SET settings = ${expression.sql} WHERE id = ?`, [...expression.params, 'u1'])
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     readonly json: ReldbJsonOps;
-    /** 关闭数据库连接 */
-    close: () => Promise<HaiResult<void>>;
-}
-/**
- * 数据库 Provider 接口
- *
- * 内部使用，定义各数据库驱动需要实现的接口。
- * 每个数据库类型（SQLite、PostgreSQL、MySQL）都有对应的 Provider 实现。
- */
-interface ReldbProvider {
-    /** DDL 操作（表结构管理） */
-    readonly ddl: DdlOperations;
-    /** SQL 操作（数据查询和修改） */
-    readonly sql: DmlOperations;
-    /** CRUD 管理器 */
-    readonly crud: CrudManager;
-    /** 事务管理器 */
-    readonly tx: TxManager;
-    /** 连接数据库 */
-    connect: (config: ReldbConfig) => Promise<HaiResult<void>>;
-    /** 关闭连接 */
+    /**
+     * 等待初始化/在途事务并关闭连接；清理失败后操作不可用，资源保留供重试。
+     * @returns 资源全部释放时成功；未初始化时同样成功。
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     *
+     * const result = await reldb.close()
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data
+     * ```
+     */
     close: () => Promise<HaiResult<void>>;
-    /** 是否已连接 */
-    isConnected: () => boolean;
 }
 
 /**
@@ -1107,21 +1018,24 @@ interface ReldbProvider {
  * - 自动填充主键、createdAt、updatedAt
  * - 跨数据库类型值转换（BOOLEAN / TIMESTAMP / JSON）
  * - 支持事务上下文（所有方法均接受可选 tx 参数）
- *
  * @example
  * ```ts
- * class UserRepository extends BaseReldbCrudRepository<User> {
+ * import { BaseReldbCrudRepository, type ReldbFunctions } from '@h-ai/reldb'
+ *
+ * type User = { id: string, name: string }
+ * class Users extends BaseReldbCrudRepository<User> {
  *   constructor(db: ReldbFunctions) {
- *     super(db, {
- *       table: 'users',
- *       fields: [
- *         { fieldName: 'id', columnName: 'id', def: { type: 'INTEGER', primaryKey: true, autoIncrement: true }, select: true, create: false, update: false },
- *         { fieldName: 'name', columnName: 'name', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
- *         { fieldName: 'createdAt', columnName: 'created_at', def: { type: 'TIMESTAMP' }, select: true, create: true, update: false },
- *       ],
- *     })
+ *     super(db, { table: 'users', fields: [
+ *       { fieldName: 'id', columnName: 'id', def: { type: 'TEXT', primaryKey: true }, select: true, create: true, update: false },
+ *       { fieldName: 'name', columnName: 'name', def: { type: 'TEXT' }, select: true, create: true, update: true },
+ *     ] })
  *   }
  * }
+ * async function create(db: ReldbFunctions) { // db 已初始化。
+ *   const result = await new Users(db).create({ name: 'Alice' })
+ *   if (!result.success) throw new Error(result.error.message)
+ *   return result.data
+ * }
  * ```
  */
 declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudRepository<TItem> {
@@ -1239,11 +1153,15 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      */
     private buildUpdatePayload;
     /**
-     * 等待初始化完成
+     * 等待初始化完成（自动建表等）
+     *
+     * 内置 CRUD 方法均已在执行前调用；自定义方法若通过 `this.sql()` 直接执行原始
+     * SQL（尤其是写操作或在事务中），应先 `await this.ensureReady()` 以避免表尚未
+     * 建好时（例如刚 dropTable 后、或后端建表较慢时）产生「表不存在」的竞态失败。
      *
      * @returns 初始化结果
      */
-    private ensureReady;
+    protected ensureReady(): Promise<HaiResult<void>>;
     /**
      * 创建单条记录
      *
@@ -1252,6 +1170,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param data - 业务字段与值的映射
      * @param tx - 可选事务句柄
      * @returns 插入结果（含 changes、lastInsertRowid）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.create({ name: 'Alice' })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     create(data: Record<string, unknown>, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
     /**
@@ -1262,6 +1191,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param items - 待插入的业务数据数组
      * @param tx - 可选事务句柄
      * @returns 批量插入结果
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.createMany([{ name: 'Alice' }, { name: 'Bob' }])
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     createMany(items: Array<Record<string, unknown>>, tx?: DmlWithTxOperations): Promise<HaiResult<void>>;
     /**
@@ -1289,6 +1229,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param data - 业务字段与值的映射
      * @param tx - 可选事务句柄
      * @returns 执行结果（含 changes）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.createOrUpdate({ id: 'u1', name: 'Alice' })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     createOrUpdate(data: Record<string, unknown>, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
     /**
@@ -1297,6 +1248,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param id - 主键值
      * @param tx - 可选事务句柄
      * @returns 业务模型对象或 null（未找到）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.findById('u1')
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     findById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<TItem | null>>;
     /**
@@ -1307,6 +1269,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param id - 主键值
      * @param tx - 可选事务句柄
      * @returns 业务模型对象（不存在时返回错误）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.getById('u1')
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     getById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<TItem>>;
     /**
@@ -1315,6 +1288,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param options - 查询条件（where、orderBy、limit、offset）
      * @param tx - 可选事务句柄
      * @returns 业务模型数组
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.findAll({ where: 'name = ?', params: ['Alice'] })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     findAll(options?: CrudQueryOptions, tx?: DmlWithTxOperations): Promise<HaiResult<TItem[]>>;
     /**
@@ -1323,6 +1307,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param options - 分页查询条件（where、orderBy、pagination、overrides）
      * @param tx - 可选事务句柄
      * @returns 分页结果（含 items、total、page、pageSize）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.findPage({ pagination: { page: 1, pageSize: 10 }, orderBy: 'id ASC' })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     findPage(options: CrudPageOptions, tx?: DmlWithTxOperations): Promise<HaiResult<PaginatedResult<TItem>>>;
     /**
@@ -1334,6 +1329,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param data - 待更新的业务字段
      * @param tx - 可选事务句柄
      * @returns 更新结果（含 changes）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.updateById('u1', { name: 'Bob' })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     updateById(id: unknown, data: Record<string, unknown>, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
     /**
@@ -1342,6 +1348,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param id - 主键值
      * @param tx - 可选事务句柄
      * @returns 删除结果（含 changes）
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.deleteById('u1')
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     deleteById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
     /**
@@ -1350,6 +1367,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param options - 查询条件（where、params）
      * @param tx - 可选事务句柄
      * @returns 记录数
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.count({ where: 'name = ?', params: ['Alice'] })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     count(options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations): Promise<HaiResult<number>>;
     /**
@@ -1358,6 +1386,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param options - 查询条件（where、params）
      * @param tx - 可选事务句柄
      * @returns 是否存在
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.exists({ where: 'name = ?', params: ['Alice'] })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     exists(options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations): Promise<HaiResult<boolean>>;
     /**
@@ -1366,6 +1405,17 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @param id - 主键值
      * @param tx - 可选事务句柄
      * @returns 是否存在
+     * @example
+     * ```ts
+     * import type { ReldbCrudRepository } from '@h-ai/reldb'
+     *
+     * async function use(repo: ReldbCrudRepository<{ id: string, name: string }>) {
+     *   const result = await repo.existsById('u1')
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * void use
+     * ```
      */
     existsById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<boolean>>;
 }
@@ -1389,37 +1439,78 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
  * - `reldb.json` - JSON 路径操作 SQL 构建器（提取、设置、插入、删除、合并）
  * - `reldb.config` - 当前配置
  * - `reldb.isInitialized` - 初始化状态
- *
  * @example
  * ```ts
  * import { reldb } from '@h-ai/reldb'
  *
- * // 初始化
- * await reldb.init({ type: 'sqlite', database: ':memory:' })
- *
- * // DDL 操作
- * await reldb.ddl.createTable('users', {
- *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
- *     name: { type: 'TEXT', notNull: true }
- * })
- *
- * // SQL 操作
- * await reldb.sql.execute('INSERT INTO users (name) VALUES (?)', ['张三'])
- * const users = await reldb.sql.query('SELECT * FROM users')
- *
- * // 事务操作
- * await reldb.tx.wrap(async (tx) => {
- *     await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
- *     await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
- *     return 'done'
- * })
- *
- * // 关闭连接
- * await reldb.close()
+ * const initialized = await reldb.init({ type: 'sqlite', database: ':memory:' }) // 仅示例/测试。
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const created = await reldb.ddl.createTable('users', { id: { type: 'TEXT', primaryKey: true }, name: { type: 'TEXT' } })
+ *   if (!created.success) throw new Error(created.error.message)
+ *   const inserted = await reldb.sql.execute('INSERT INTO users (id, name) VALUES (?, ?)', ['u1', 'Alice'])
+ *   if (!inserted.success) throw new Error(inserted.error.message)
+ * } finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 declare const reldb: ReldbFunctions;
 
+/** 模块维护自己的迁移；这里只提供跨数据库列检查、版本账本和执行边界。 */
+
+/**
+ * 一个可重入的模块升级步骤；只接收代码中固定的 SQL 与表名。
+ * @example
+ * ```ts
+ * import type { SchemaMigration } from '@h-ai/reldb'
+ * const steps: SchemaMigration[] = []
+ * ```
+ */
+interface SchemaMigration {
+    version: number;
+    name: string;
+    needed: (sql: DmlOperations) => Promise<HaiResult<boolean>>;
+    apply: (sql: DmlOperations) => Promise<HaiResult<unknown>>;
+}
+/**
+ * 只读预检结果；生产升级需先停旧写入并备份数据库与共享缓存。
+ * @example
+ * ```ts
+ * import type { SchemaMigrationPlan } from '@h-ai/reldb'
+ * function changes(plan: SchemaMigrationPlan) { return plan.changes }
+ * ```
+ */
+interface SchemaMigrationPlan {
+    module: string;
+    currentVersion: number;
+    targetVersion: number;
+    changes: string[];
+    requiresExclusiveAccess: boolean;
+}
+/**
+ * 查询真实列名；不创建表，不把查询错误当成新安装。
+ * @example
+ * ```ts
+ * import { reldb, schemaColumns } from '@h-ai/reldb'
+ * const columns = await schemaColumns(reldb, 'hai_iam_users')
+ * ```
+ */
+declare function schemaColumns(db: ReldbFunctions, table: string, sql?: DmlOperations): Promise<HaiResult<string[]>>;
+/**
+ * 预检或执行模块维护的版本迁移。SQLite/PostgreSQL 原子提交；MySQL DDL 隐式提交，步骤须可重入。
+ * 失败不记录目标版本；重启重新检查真实结构。新版本账本拒绝旧代码向下迁移。
+ * @example
+ * ```ts
+ * import { reldb, migrateSchema } from '@h-ai/reldb'
+ * const plan = await migrateSchema(reldb, 'example', [], { dryRun: true })
+ * ```
+ */
+declare function migrateSchema(db: ReldbFunctions, module: string, steps: readonly SchemaMigration[], options?: {
+    dryRun?: boolean;
+}): Promise<HaiResult<SchemaMigrationPlan>>;
+
 /**
  * @h-ai/reldb — 安全工具
  *
@@ -1435,14 +1526,13 @@ declare const reldb: ReldbFunctions;
  *
  * @param name - 待校验的标识符
  * @returns 校验通过时返回 ok(name)；不合法时返回错误 HaiResult
- *
  * @example
  * ```ts
- * const result = validateIdentifier('users')
- * // result.success === true
+ * import { validateIdentifier } from '@h-ai/reldb'
  *
- * const bad = validateIdentifier('users; DROP TABLE')
- * // bad.success === false
+ * const checked = validateIdentifier('users')
+ * if (!checked.success) throw new Error(checked.error.message)
+ * void checked.data
  * ```
  */
 declare function validateIdentifier(name: string): HaiResult<string>;
@@ -1453,6 +1543,13 @@ declare function validateIdentifier(name: string): HaiResult<string>;
  *
  * @param names - 待校验的标识符数组
  * @returns 全部合法时返回 ok(undefined)；否则返回第一个不合法项的错误
+ * @example
+ * ```ts
+ * import { validateIdentifiers } from '@h-ai/reldb'
+ *
+ * const checked = validateIdentifiers(['users', 'id'])
+ * if (!checked.success) throw new Error(checked.error.message)
+ * ```
  */
 declare function validateIdentifiers(names: string[]): HaiResult<void>;
 /**
@@ -1464,11 +1561,13 @@ declare function validateIdentifiers(names: string[]): HaiResult<void>;
  *
  * @param name - 已校验的标识符
  * @returns 双引号包裹的安全标识符
- *
  * @example
  * ```ts
- * quoteIdentifier('users')  // '"users"'
- * quoteIdentifier('order')  // '"order"'  （安全引用 SQL 保留字）
+ * import { quoteIdentifier, validateIdentifier } from '@h-ai/reldb'
+ *
+ * const checked = validateIdentifier('order')
+ * if (!checked.success) throw new Error(checked.error.message)
+ * void quoteIdentifier(checked.data)
  * ```
  */
 declare function quoteIdentifier(name: string): string;
@@ -1480,13 +1579,13 @@ declare function quoteIdentifier(name: string): string;
  *
  * @param value - 原始字符串
  * @returns 转义后的安全字符串
- *
  * @example
  * ```ts
- * escapeSqlString("it's") // "it''s"
- * escapeSqlString("normal") // "normal"
+ * import { escapeSqlString } from '@h-ai/reldb'
+ *
+ * void escapeSqlString("it's") // it''s；仅用于可信 DDL 字面量，业务值使用占位符。
  * ```
  */
 declare function escapeSqlString(value: string): string;
 
-export { BaseReldbCrudRepository, type BaseReldbCrudRepositoryConfig, type ColumnType, type CrudConfig, type CrudManager, type CrudPageOptions, type CrudQueryOptions, type DbType, type DdlOperations, type DmlOperations, type DmlWithTxOperations, type ExecuteResult, HaiReldbError, type JsonSqlExpr, type MysqlConfig, MysqlConfigSchema, MysqlOptionsSchema, type NormalizedPagination, type PaginationOverrides, type PaginationQueryOptions, type PoolConfig, PoolConfigSchema, type PostgresqlConfig, PostgresqlConfigSchema, type QueryRow, type ReldbColumnDef, type ReldbConfig, type ReldbConfigInput, ReldbConfigSchema, type ReldbCrudCountOptions, type ReldbCrudFieldDefinition, type ReldbCrudRepository, type ReldbFunctions, type ReldbIndexDef, type ReldbJsonOps, type ReldbProvider, type ReldbTableDef, ReldbTypeSchema, type SqliteConfig, SqliteConfigSchema, SqliteOptionsSchema, type SslConfig, SslConfigSchema, type TxManager, type TxWrapCallback, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };
+export { BaseReldbCrudRepository, type BaseReldbCrudRepositoryConfig, type ColumnType, type CrudConfig, type CrudManager, type CrudPageOptions, type CrudQueryOptions, DbType, type DdlOperations, type DmlOperations, type DmlWithTxOperations, type ExecuteResult, HaiReldbError, type JsonSqlExpr, type NormalizedPagination, type PaginationOverrides, type PaginationQueryOptions, type QueryRow, type ReldbColumnDef, ReldbConfig, ReldbConfigInput, type ReldbCrudCountOptions, type ReldbCrudFieldDefinition, type ReldbCrudRepository, type ReldbFunctions, type ReldbIndexDef, type ReldbJsonOps, type ReldbTableDef, type SchemaMigration, type SchemaMigrationPlan, type TxManager, type TxWrapCallback, createJsonOps, escapeSqlString, migrateSchema, parseJsonPath, quoteIdentifier, reldb, schemaColumns, validateIdentifier, validateIdentifiers };