@h-ai/reldb 0.1.0-alpha5

package/dist/index.js

@@ -0,0 +1,2603 @@
+import { z } from 'zod';
+import { core, ok, err } from '@h-ai/core';
+import { createRequire } from 'module';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var ReldbTypeSchema = z.enum(["sqlite", "postgresql", "mysql"]);
+var PoolConfigSchema = z.object({
+  /** 最小连接数（默认 1） */
+  min: z.number().int().min(0).default(1),
+  /** 最大连接数（默认 10） */
+  max: z.number().int().min(1).default(10),
+  /** 空闲连接超时时间，单位毫秒（默认 30000） */
+  idleTimeout: z.number().int().min(0).default(3e4),
+  /** 获取连接超时时间，单位毫秒（默认 10000） */
+  acquireTimeout: z.number().int().min(0).default(1e4)
+});
+var SslConfigSchema = z.union([
+  z.boolean(),
+  z.enum(["require", "prefer", "allow", "disable"]),
+  z.record(z.string(), z.unknown())
+]);
+var SqliteOptionsSchema = z.object({
+  /** 是否启用 WAL 模式（默认 true），可提高并发读写性能 */
+  walMode: z.boolean().default(true),
+  /** 是否只读模式（默认 false） */
+  readonly: z.boolean().default(false)
+});
+var MysqlOptionsSchema = z.object({
+  /** 字符集（默认 utf8mb4），推荐使用 utf8mb4 支持完整 Unicode */
+  charset: z.string().default("utf8mb4"),
+  /** 时区设置，如 '+08:00' */
+  timezone: z.string().optional()
+});
+var NetworkConfigSchema = z.object({
+  /**
+   * 连接字符串（可选）
+   * 如果提供 url，将优先使用，忽略 host/port 等字段
+   */
+  url: z.string().optional(),
+  /** 数据库主机地址（默认 localhost） */
+  host: z.string().default("localhost"),
+  /**
+   * 数据库端口
+   * - PostgreSQL 默认 5432
+   * - MySQL 默认 3306
+   */
+  port: z.number().int().min(1).max(65535).optional(),
+  /** 数据库名称 */
+  database: z.string(),
+  /** 数据库用户名 */
+  user: z.string().optional(),
+  /** 数据库密码 */
+  password: z.string().optional(),
+  /** SSL/TLS 连接配置 */
+  ssl: SslConfigSchema.optional(),
+  /** 连接池配置 */
+  pool: PoolConfigSchema.optional()
+});
+var SqliteConfigSchema = z.object({
+  type: z.literal("sqlite"),
+  /** 数据库文件路径（如 './data.db'）或 ':memory:'（内存数据库） */
+  database: z.string(),
+  /** SQLite 特定选项 */
+  sqlite: SqliteOptionsSchema.optional()
+});
+var PostgresqlConfigSchema = NetworkConfigSchema.extend({
+  type: z.literal("postgresql")
+});
+var MysqlConfigSchema = NetworkConfigSchema.extend({
+  type: z.literal("mysql"),
+  /** MySQL 特定选项 */
+  mysql: MysqlOptionsSchema.optional()
+});
+var ReldbConfigSchema = z.discriminatedUnion("type", [
+  SqliteConfigSchema,
+  PostgresqlConfigSchema,
+  MysqlConfigSchema
+]);
+
+// messages/en-US.json
+var en_US_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  reldb_notInitialized: "Database not initialized, please call db.init() first",
+  reldb_initFailed: "Failed to initialize database: {error}",
+  reldb_closeFailed: "Failed to close database: {error}",
+  reldb_unsupportedType: "Unsupported database type: {type}",
+  reldb_ddlFailed: "DDL operation failed: {error}",
+  reldb_queryFailed: "Query failed: {error}",
+  reldb_executeFailed: "Execute failed: {error}",
+  reldb_batchFailed: "Batch execute failed: {error}",
+  reldb_postgresTxFailed: "Transaction failed: {error}",
+  reldb_postgresOnlyPostgresql: "PostgreSQL Provider only supports postgresql type",
+  reldb_postgresConnectionFailed: "Failed to connect to PostgreSQL: {error}",
+  reldb_sqliteOnlySqlite: "SQLite Provider only supports sqlite type",
+  reldb_sqliteNeedPath: "SQLite requires database path (database field)",
+  reldb_sqliteConnectionFailed: "Failed to connect to SQLite: {error}",
+  reldb_sqliteTxFailed: "Transaction failed: {error}",
+  reldb_sqliteCreateTableFailed: "Failed to create table {tableName}: {error}",
+  reldb_sqliteDropTableFailed: "Failed to drop table {tableName}: {error}",
+  reldb_sqliteAddColumnFailed: "Failed to add column {columnName} to table {tableName}: {error}",
+  reldb_sqliteDropColumnFailed: "Failed to drop column {columnName} from table {tableName}: {error}",
+  reldb_sqliteRenameTableFailed: "Failed to rename table {oldName} to {newName}: {error}",
+  reldb_sqliteCreateIndexFailed: "Failed to create index {indexName}: {error}",
+  reldb_sqliteDropIndexFailed: "Failed to drop index {indexName}: {error}",
+  reldb_sqliteExecDdlFailed: "Failed to execute DDL: {error}",
+  reldb_sqliteQueryFailed: "Query failed: {error}",
+  reldb_sqliteExecuteFailed: "Execute failed: {error}",
+  reldb_sqliteBatchFailed: "Batch execute failed: {error}",
+  reldb_mysqlOnlyMysql: "MySQL Provider only supports mysql type",
+  reldb_mysqlConnectionFailed: "Failed to connect to MySQL: {error}",
+  reldb_mysqlTxFailed: "Transaction failed: {error}",
+  reldb_crudEmptyPayload: "CRUD payload is empty, please provide data",
+  reldb_crudNoValidColumns: "CRUD payload has no valid columns",
+  reldb_crudRecordNotFound: "Record not found: {id}",
+  reldb_invalidIdentifier: "Invalid SQL identifier: {name} (only letters, digits and underscores allowed)",
+  reldb_configError: "Database config validation failed: {error}",
+  reldb_txFailed: "Transaction failed: {error}"
+};
+
+// messages/zh-CN.json
+var zh_CN_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  reldb_notInitialized: "\u6570\u636E\u5E93\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u8C03\u7528 db.init()",
+  reldb_initFailed: "\u521D\u59CB\u5316\u6570\u636E\u5E93\u5931\u8D25: {error}",
+  reldb_closeFailed: "\u5173\u95ED\u6570\u636E\u5E93\u5931\u8D25: {error}",
+  reldb_unsupportedType: "\u4E0D\u652F\u6301\u7684\u6570\u636E\u5E93\u7C7B\u578B: {type}",
+  reldb_ddlFailed: "DDL \u64CD\u4F5C\u5931\u8D25: {error}",
+  reldb_queryFailed: "\u67E5\u8BE2\u5931\u8D25: {error}",
+  reldb_executeFailed: "\u6267\u884C\u5931\u8D25: {error}",
+  reldb_batchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25: {error}",
+  reldb_postgresTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25: {error}",
+  reldb_postgresOnlyPostgresql: "PostgreSQL Provider \u4EC5\u652F\u6301 postgresql \u7C7B\u578B",
+  reldb_postgresConnectionFailed: "\u8FDE\u63A5 PostgreSQL \u5931\u8D25: {error}",
+  reldb_sqliteOnlySqlite: "SQLite Provider \u4EC5\u652F\u6301 sqlite \u7C7B\u578B",
+  reldb_sqliteNeedPath: "SQLite \u9700\u8981\u63D0\u4F9B\u6570\u636E\u5E93\u8DEF\u5F84\uFF08database \u5B57\u6BB5\uFF09",
+  reldb_sqliteConnectionFailed: "\u8FDE\u63A5 SQLite \u5931\u8D25: {error}",
+  reldb_sqliteTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25: {error}",
+  reldb_sqliteCreateTableFailed: "\u521B\u5EFA\u8868 {tableName} \u5931\u8D25: {error}",
+  reldb_sqliteDropTableFailed: "\u5220\u9664\u8868 {tableName} \u5931\u8D25: {error}",
+  reldb_sqliteAddColumnFailed: "\u5411\u8868 {tableName} \u6DFB\u52A0\u5217 {columnName} \u5931\u8D25: {error}",
+  reldb_sqliteDropColumnFailed: "\u4ECE\u8868 {tableName} \u5220\u9664\u5217 {columnName} \u5931\u8D25: {error}",
+  reldb_sqliteRenameTableFailed: "\u91CD\u547D\u540D\u8868 {oldName} \u4E3A {newName} \u5931\u8D25: {error}",
+  reldb_sqliteCreateIndexFailed: "\u521B\u5EFA\u7D22\u5F15 {indexName} \u5931\u8D25: {error}",
+  reldb_sqliteDropIndexFailed: "\u5220\u9664\u7D22\u5F15 {indexName} \u5931\u8D25: {error}",
+  reldb_sqliteExecDdlFailed: "\u6267\u884C DDL \u5931\u8D25: {error}",
+  reldb_sqliteQueryFailed: "\u67E5\u8BE2\u5931\u8D25: {error}",
+  reldb_sqliteExecuteFailed: "\u6267\u884C\u5931\u8D25: {error}",
+  reldb_sqliteBatchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25: {error}",
+  reldb_mysqlOnlyMysql: "MySQL Provider \u4EC5\u652F\u6301 mysql \u7C7B\u578B",
+  reldb_mysqlConnectionFailed: "\u8FDE\u63A5 MySQL \u5931\u8D25: {error}",
+  reldb_mysqlTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25: {error}",
+  reldb_crudEmptyPayload: "CRUD \u6570\u636E\u4E3A\u7A7A\uFF0C\u8BF7\u63D0\u4F9B\u6570\u636E",
+  reldb_crudNoValidColumns: "CRUD \u6570\u636E\u6CA1\u6709\u6709\u6548\u5217",
+  reldb_crudRecordNotFound: "\u8BB0\u5F55\u4E0D\u5B58\u5728: {id}",
+  reldb_invalidIdentifier: "\u975E\u6CD5\u7684 SQL \u6807\u8BC6\u7B26: {name}\uFF08\u4EC5\u5141\u8BB8\u5B57\u6BCD\u3001\u6570\u5B57\u548C\u4E0B\u5212\u7EBF\uFF09",
+  reldb_configError: "\u6570\u636E\u5E93\u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A{error}",
+  reldb_txFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25: {error}"
+};
+
+// src/reldb-i18n.ts
+var reldbM = core.i18n.createMessageGetter({
+  "zh-CN": zh_CN_default,
+  "en-US": en_US_default
+});
+var ReldbErrorInfo = {
+  CONNECTION_FAILED: "001:500",
+  QUERY_FAILED: "002:500",
+  CONSTRAINT_VIOLATION: "003:409",
+  TRANSACTION_FAILED: "004:500",
+  MIGRATION_FAILED: "005:500",
+  RECORD_NOT_FOUND: "006:404",
+  DUPLICATE_ENTRY: "007:409",
+  DEADLOCK: "008:500",
+  TIMEOUT: "009:504",
+  POOL_EXHAUSTED: "010:503",
+  NOT_INITIALIZED: "011:500",
+  DDL_FAILED: "012:500",
+  UNSUPPORTED_TYPE: "013:400",
+  CONFIG_ERROR: "014:500"
+};
+var HaiReldbError = core.error.buildHaiErrorsDef("reldb", ReldbErrorInfo);
+
+// src/reldb-crud-repository.ts
+var BaseReldbCrudRepository = class {
+  /** 底层 CRUD 仓库实例（基于 reldb-crud-kernel 创建） */
+  crud;
+  /** 数据库服务对象 */
+  db;
+  /** 字段定义列表 */
+  fields;
+  /** 主键字段名（对象侧） */
+  idField;
+  /** 主键列名（数据库侧） */
+  idColumn;
+  /** 主键生成器 */
+  generateId;
+  /** 当前时间提供者（默认 Date.now） */
+  nowProvider;
+  /** 初始化 Promise（自动建表等） */
+  initPromise;
+  /** 可查询列 */
+  selectColumns;
+  /** 可插入列 */
+  createColumns;
+  /** 可更新列 */
+  updateColumns;
+  /** 表名 */
+  table;
+  /** 当前数据库类型（延迟读取，确保获取初始化后的值） */
+  get dbType() {
+    return this.db.config.type;
+  }
+  /**
+   * 创建 BaseReldbCrudRepository
+   *
+   * 初始化字段映射、构建表结构（默认自动建表）并配置底层 CRUD 仓库。
+   *
+   * @param db - 数据库服务对象
+   * @param config - BaseReldbCrudRepository 配置（表名、字段定义、主键策略等）
+   */
+  constructor(db, config) {
+    this.db = db;
+    this.table = config.table;
+    this.fields = config.fields;
+    this.idColumn = config.idColumn ?? "id";
+    this.idField = config.idField ?? this.resolveIdField(config.fields, this.idColumn);
+    this.generateId = config.generateId ?? this.defaultIdGenerator();
+    this.nowProvider = config.nowProvider ?? (() => Date.now());
+    const tableDef = this.buildReldbTableDef(config.fields);
+    const createTable = config.createTableIfNotExists !== false ? this.db.ddl.createTable(config.table, tableDef, true) : Promise.resolve(ok(void 0));
+    this.initPromise = createTable;
+    this.selectColumns = this.fields.filter((field) => field.select).map((field) => field.columnName);
+    this.createColumns = this.fields.filter((field) => field.create).map((field) => field.columnName);
+    const updateColumns = this.fields.filter((field) => field.update).map((field) => field.columnName);
+    const updatedAtField = this.fields.find((field) => this.isUpdatedAtField(field));
+    this.updateColumns = updatedAtField && !updateColumns.includes(updatedAtField.columnName) ? [...updateColumns, updatedAtField.columnName] : updateColumns;
+    this.crud = this.db.crud.table({
+      table: config.table,
+      idColumn: this.idColumn,
+      select: this.selectColumns,
+      createColumns: this.createColumns,
+      updateColumns: this.updateColumns,
+      mapRow: (row) => this.mapRow(row),
+      get dbType() {
+        return db.config.type;
+      }
+    });
+  }
+  /**
+   * 获取 SQL 操作对象（自动选择 reldb.sql 或 tx）
+   *
+   * 当传入事务句柄时，自动使用事务内 DataOperations；否则使用 reldb.sql。
+   *
+   * @param tx - 可选事务句柄
+   * @returns DataOperations 实例
+   */
+  sql(tx) {
+    return tx ?? this.db.sql;
+  }
+  /**
+   * 解析主键字段
+   *
+   * 优先使用声明为主键的字段；如果未声明主键，则回退到列名匹配。
+   *
+   * @param fields - 字段定义列表
+   * @param idColumn - 主键列名
+   * @returns 主键字段名（可能为空）
+   */
+  resolveIdField(fields, idColumn) {
+    const primary = fields.find((field) => field.def.primaryKey);
+    if (primary) {
+      return primary.fieldName;
+    }
+    const byColumn = fields.find((field) => field.columnName === idColumn);
+    return byColumn?.fieldName;
+  }
+  /**
+   * 生成默认主键生成器
+   *
+   * 在运行环境支持 `crypto.randomUUID` 时返回 UUID 生成函数，否则返回 undefined。
+   */
+  defaultIdGenerator() {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+      return () => crypto.randomUUID();
+    }
+    return void 0;
+  }
+  /**
+   * 构建表结构定义
+   *
+   * @param fields - 字段定义列表
+   * @returns 表结构定义
+   */
+  buildReldbTableDef(fields) {
+    const entries = fields.map((field) => [field.columnName, this.normalizeReldbColumnDef(field.def)]);
+    return Object.fromEntries(entries);
+  }
+  /**
+   * 归一化列定义
+   *
+   * 用于处理不同数据库对默认值的兼容差异（例如 BOOLEAN）。
+   */
+  normalizeReldbColumnDef(def) {
+    if (def.defaultValue === void 0 || def.defaultValue === null) {
+      return def;
+    }
+    if (def.type !== "BOOLEAN" || typeof def.defaultValue === "string") {
+      return def;
+    }
+    const normalized = { ...def };
+    if (this.dbType === "postgresql") {
+      normalized.defaultValue = Boolean(def.defaultValue);
+      return normalized;
+    }
+    normalized.defaultValue = def.defaultValue ? 1 : 0;
+    return normalized;
+  }
+  /**
+   * 判断是否为创建时间字段
+   */
+  isCreatedAtField(field) {
+    return field.fieldName === "createdAt" || field.columnName === "created_at";
+  }
+  /**
+   * 判断是否为更新时间字段
+   */
+  isUpdatedAtField(field) {
+    return field.fieldName === "updatedAt" || field.columnName === "updated_at";
+  }
+  /**
+   * 将数据库值转换为业务值
+   *
+   * @param value - 数据库原始值
+   * @param def - 字段定义
+   * @returns 业务侧值（可能为 undefined）
+   */
+  fromDbValue(value, def) {
+    if (value === null || value === void 0) {
+      return void 0;
+    }
+    if (def.type === "BOOLEAN") {
+      return Boolean(value);
+    }
+    if (def.type === "TIMESTAMP") {
+      if (value instanceof Date) {
+        return value;
+      }
+      if (typeof value === "number") {
+        return new Date(value);
+      }
+      const parsed = Date.parse(String(value));
+      return Number.isNaN(parsed) ? void 0 : new Date(parsed);
+    }
+    if (def.type === "JSON") {
+      if (typeof value === "string") {
+        try {
+          return JSON.parse(value);
+        } catch {
+          return void 0;
+        }
+      }
+      return value;
+    }
+    return value;
+  }
+  /**
+   * 将业务值转换为数据库值
+   *
+   * @param value - 业务侧值
+   * @param def - 字段定义
+   * @returns 适配数据库的值
+   */
+  toDbValue(value, def) {
+    if (value === void 0) {
+      return void 0;
+    }
+    if (value === null) {
+      return null;
+    }
+    if (def.type === "BOOLEAN") {
+      if (this.dbType === "postgresql") {
+        return Boolean(value);
+      }
+      return value ? 1 : 0;
+    }
+    if (def.type === "TIMESTAMP") {
+      if (this.dbType === "sqlite") {
+        if (value instanceof Date) {
+          return value.getTime();
+        }
+        if (typeof value === "number") {
+          return value;
+        }
+        const parsed = Date.parse(String(value));
+        return Number.isNaN(parsed) ? value : parsed;
+      }
+      if (value instanceof Date) {
+        return value;
+      }
+      if (typeof value === "number") {
+        return new Date(value);
+      }
+      return value;
+    }
+    if (def.type === "JSON") {
+      if (typeof value === "string") {
+        return value;
+      }
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+  /**
+   * 将查询行映射为业务模型
+   */
+  mapRow(row) {
+    const result = {};
+    for (const field of this.fields) {
+      if (!field.select) {
+        continue;
+      }
+      const value = this.fromDbValue(row[field.columnName], field.def);
+      result[field.fieldName] = value;
+    }
+    return result;
+  }
+  /**
+   * 构建创建数据的列值映射
+   *
+   * 处理主键生成、默认值、createdAt/updatedAt 填充等规则。
+   */
+  buildCreatePayload(data) {
+    const payload = {};
+    const now = this.nowProvider();
+    let generatedId;
+    const idFieldDef = this.fields.find((field) => field.fieldName === this.idField);
+    if (this.idField && !idFieldDef?.def.autoIncrement) {
+      const currentId = data[this.idField];
+      if (currentId !== void 0) ; else if (this.generateId) {
+        generatedId = this.generateId();
+      }
+    }
+    for (const field of this.fields) {
+      if (!field.create) {
+        continue;
+      }
+      let value = data[field.fieldName];
+      if (value === void 0 && field.def.autoIncrement) {
+        continue;
+      }
+      if (field.fieldName === this.idField && value === void 0 && generatedId !== void 0) {
+        value = generatedId;
+      }
+      if (value === void 0) {
+        if (this.isCreatedAtField(field) || this.isUpdatedAtField(field)) {
+          value = now;
+        } else if (field.def.defaultValue !== void 0 && typeof field.def.defaultValue !== "string") {
+          value = field.def.defaultValue;
+        }
+      }
+      if (value === void 0) {
+        continue;
+      }
+      payload[field.columnName] = this.toDbValue(value, field.def);
+    }
+    return payload;
+  }
+  /**
+   * 构建更新数据的列值映射
+   *
+   * 当没有任何可更新字段时返回 null。
+   */
+  buildUpdatePayload(data) {
+    const payload = {};
+    const now = this.nowProvider();
+    for (const field of this.fields) {
+      if (!field.update) {
+        continue;
+      }
+      const value = data[field.fieldName];
+      if (value === void 0) {
+        continue;
+      }
+      payload[field.columnName] = this.toDbValue(value, field.def);
+    }
+    if (Object.keys(payload).length === 0) {
+      return null;
+    }
+    const updatedAtField = this.fields.find((field) => this.isUpdatedAtField(field));
+    if (updatedAtField) {
+      payload[updatedAtField.columnName] = this.toDbValue(now, updatedAtField.def);
+    }
+    return payload;
+  }
+  /**
+   * 等待初始化完成
+   *
+   * @returns 初始化结果
+   */
+  async ensureReady() {
+    const result = await this.initPromise;
+    if (!result.success) {
+      return result;
+    }
+    return ok(void 0);
+  }
+  /**
+   * 创建单条记录
+   *
+   * 自动处理主键生成、createdAt/updatedAt 填充、字段类型转换。
+   *
+   * @param data - 业务字段与值的映射
+   * @param tx - 可选事务句柄
+   * @returns 插入结果（含 changes、lastInsertRowid）
+   */
+  async create(data, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    const payload = this.buildCreatePayload(data);
+    if (Object.keys(payload).length === 0) {
+      return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudEmptyPayload"));
+    }
+    return this.crud.create(payload, tx);
+  }
+  /**
+   * 批量创建记录
+   *
+   * 每条记录均通过 buildCreatePayload 处理，然后以 batch 方式写入。
+   *
+   * @param items - 待插入的业务数据数组
+   * @param tx - 可选事务句柄
+   * @returns 批量插入结果
+   */
+  async createMany(items, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    const payloads = items.map((item) => this.buildCreatePayload(item));
+    return this.crud.createMany(payloads, tx);
+  }
+  /**
+   * 创建或更新单条记录（upsert）
+   *
+   * 主键存在时更新可更新字段，否则插入新记录。
+   * 自动处理主键生成、createdAt/updatedAt 填充、字段类型转换。
+   * 更新时仅写入用户显式提供的可更新字段，不会用默认值覆盖已有数据。
+   *
+   * ### 为什么不复用 this.crud.createOrUpdate（kernel）
+   *
+   * Kernel 的 createOrUpdate 使用 `excluded.col` / `VALUES(col)` 引用 INSERT 值作为
+   * UPDATE 值，即 INSERT 和 UPDATE 共享同一组数据。但 Repository 层的 INSERT 负载和
+   * UPDATE 负载语义不同：
+   *
+   * - **INSERT 负载**（buildCreatePayload）：包含自动生成的主键、createdAt、updatedAt、
+   *   字段默认值（如 `status: 'active'`）等应用层填充值。
+   * - **UPDATE 负载**（buildUpdatePayload）：仅包含用户显式传入的可更新字段 + updatedAt，
+   *   不包含 createdAt（避免覆盖原始创建时间）、不包含应用默认值（避免覆盖已有数据）。
+   *
+   * 若复用 kernel，冲突更新时会将 INSERT 的 createdAt、默认值等一并写入，破坏已有记录。
+   * 因此 Repository 自行构建两份独立负载，使用 `col = ?` 参数化占位分别传入 INSERT 值
+   * 和 UPDATE 值，通过 this.sql(tx).execute() 直接执行。
+   *
+   * @param data - 业务字段与值的映射
+   * @param tx - 可选事务句柄
+   * @returns 执行结果（含 changes）
+   */
+  async createOrUpdate(data, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    const dbType = this.dbType;
+    const createPayload = this.buildCreatePayload(data);
+    if (this.idField && data[this.idField] !== void 0) {
+      const idFieldDef = this.fields.find((f) => f.fieldName === this.idField);
+      if (idFieldDef && !(idFieldDef.columnName in createPayload)) {
+        createPayload[idFieldDef.columnName] = this.toDbValue(data[this.idField], idFieldDef.def);
+      }
+    }
+    if (Object.keys(createPayload).length === 0) {
+      return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudEmptyPayload"));
+    }
+    const insertColumns = Object.keys(createPayload);
+    const insertValues = Object.values(createPayload);
+    const placeholders = insertColumns.map(() => "?").join(", ");
+    const updatePayload = this.buildUpdatePayload(data);
+    if (!updatePayload || Object.keys(updatePayload).length === 0) {
+      const sql2 = `INSERT INTO ${this.table} (${insertColumns.join(", ")}) VALUES (${placeholders})`;
+      return this.sql(tx).execute(sql2, insertValues);
+    }
+    const updateColumns = Object.keys(updatePayload);
+    const updateValues = Object.values(updatePayload);
+    const updateSet = updateColumns.map((col) => `${col} = ?`).join(", ");
+    let sql;
+    if (dbType === "mysql") {
+      sql = `INSERT INTO ${this.table} (${insertColumns.join(", ")}) VALUES (${placeholders}) ON DUPLICATE KEY UPDATE ${updateSet}`;
+    } else {
+      sql = `INSERT INTO ${this.table} (${insertColumns.join(", ")}) VALUES (${placeholders}) ON CONFLICT(${this.idColumn}) DO UPDATE SET ${updateSet}`;
+    }
+    return this.sql(tx).execute(sql, [...insertValues, ...updateValues]);
+  }
+  /**
+   * 根据主键查找单条记录
+   *
+   * @param id - 主键值
+   * @param tx - 可选事务句柄
+   * @returns 业务模型对象或 null（未找到）
+   */
+  async findById(id, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.findById(id, tx);
+  }
+  /**
+   * 根据主键获取单条记录（必须存在）
+   *
+   * 与 findById 不同，当记录不存在时返回 RECORD_NOT_FOUND 错误。
+   *
+   * @param id - 主键值
+   * @param tx - 可选事务句柄
+   * @returns 业务模型对象（不存在时返回错误）
+   */
+  async getById(id, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.getById(id, tx);
+  }
+  /**
+   * 条件查询多条记录
+   *
+   * @param options - 查询条件（where、orderBy、limit、offset）
+   * @param tx - 可选事务句柄
+   * @returns 业务模型数组
+   */
+  async findAll(options, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.findAll(options, tx);
+  }
+  /**
+   * 分页查询记录
+   *
+   * @param options - 分页查询条件（where、orderBy、pagination、overrides）
+   * @param tx - 可选事务句柄
+   * @returns 分页结果（含 items、total、page、pageSize）
+   */
+  async findPage(options, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.findPage(options, tx);
+  }
+  /**
+   * 根据主键更新记录
+   *
+   * 自动填充 updatedAt 字段。无可更新字段时返回 CONFIG_ERROR。
+   *
+   * @param id - 主键值
+   * @param data - 待更新的业务字段
+   * @param tx - 可选事务句柄
+   * @returns 更新结果（含 changes）
+   */
+  async updateById(id, data, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    const payload = this.buildUpdatePayload(data);
+    if (!payload) {
+      return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudEmptyPayload"));
+    }
+    return this.crud.updateById(id, payload, tx);
+  }
+  /**
+   * 根据主键删除记录
+   *
+   * @param id - 主键值
+   * @param tx - 可选事务句柄
+   * @returns 删除结果（含 changes）
+   */
+  async deleteById(id, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.deleteById(id, tx);
+  }
+  /**
+   * 统计符合条件的记录数
+   *
+   * @param options - 查询条件（where、params）
+   * @param tx - 可选事务句柄
+   * @returns 记录数
+   */
+  async count(options, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.count(options, tx);
+  }
+  /**
+   * 检查是否存在符合条件的记录
+   *
+   * @param options - 查询条件（where、params）
+   * @param tx - 可选事务句柄
+   * @returns 是否存在
+   */
+  async exists(options, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.exists(options, tx);
+  }
+  /**
+   * 根据主键检查记录是否存在
+   *
+   * @param id - 主键值
+   * @param tx - 可选事务句柄
+   * @returns 是否存在
+   */
+  async existsById(id, tx) {
+    const ready = await this.ensureReady();
+    if (!ready.success) {
+      return ready;
+    }
+    return this.crud.existsById(id, tx);
+  }
+};
+
+// src/reldb-json.ts
+function parseJsonPath(path) {
+  let remaining = path.startsWith("$") ? path.slice(1) : path;
+  const segments = [];
+  while (remaining.length > 0) {
+    if (remaining.startsWith("[")) {
+      const end = remaining.indexOf("]");
+      if (end === -1)
+        break;
+      let segment = remaining.slice(1, end);
+      if (segment.startsWith('"') && segment.endsWith('"') || segment.startsWith("'") && segment.endsWith("'")) {
+        segment = segment.slice(1, -1);
+      }
+      segments.push(segment);
+      remaining = remaining.slice(end + 1);
+    } else if (remaining.startsWith(".")) {
+      remaining = remaining.slice(1);
+      if (remaining.startsWith("["))
+        continue;
+      const match = remaining.match(/^([^.[]+)/);
+      if (match) {
+        segments.push(match[1]);
+        remaining = remaining.slice(match[1].length);
+      }
+    } else {
+      break;
+    }
+  }
+  return segments;
+}
+function createSqliteJsonOps() {
+  return {
+    extract(column, path) {
+      return {
+        sql: `json_extract(${column}, ?)`,
+        params: [path]
+      };
+    },
+    set(column, path, value) {
+      return {
+        sql: `json_set(${column}, ?, json(?))`,
+        params: [path, JSON.stringify(value)]
+      };
+    },
+    insert(column, path, value) {
+      return {
+        sql: `json_insert(${column}, ?, json(?))`,
+        params: [path, JSON.stringify(value)]
+      };
+    },
+    remove(column, path) {
+      return {
+        sql: `json_remove(${column}, ?)`,
+        params: [path]
+      };
+    },
+    merge(column, patch) {
+      return {
+        sql: `json_patch(${column}, ?)`,
+        params: [JSON.stringify(patch)]
+      };
+    }
+  };
+}
+function createPostgresJsonOps() {
+  return {
+    extract(column, path) {
+      const segments = parseJsonPath(path);
+      return {
+        sql: `${column} #> ?::text[]`,
+        params: [segments]
+      };
+    },
+    set(column, path, value) {
+      const segments = parseJsonPath(path);
+      return {
+        sql: `jsonb_set(${column}, ?::text[], ?::jsonb)`,
+        params: [segments, JSON.stringify(value)]
+      };
+    },
+    insert(column, path, value) {
+      const segments = parseJsonPath(path);
+      return {
+        sql: `jsonb_insert(${column}, ?::text[], ?::jsonb)`,
+        params: [segments, JSON.stringify(value)]
+      };
+    },
+    remove(column, path) {
+      const segments = parseJsonPath(path);
+      return {
+        sql: `${column} #- ?::text[]`,
+        params: [segments]
+      };
+    },
+    merge(column, patch) {
+      return {
+        sql: `${column} || ?::jsonb`,
+        params: [JSON.stringify(patch)]
+      };
+    }
+  };
+}
+function createMysqlJsonOps() {
+  return {
+    extract(column, path) {
+      return {
+        sql: `JSON_EXTRACT(${column}, ?)`,
+        params: [path]
+      };
+    },
+    set(column, path, value) {
+      return {
+        sql: `JSON_SET(${column}, ?, CAST(? AS JSON))`,
+        params: [path, JSON.stringify(value)]
+      };
+    },
+    insert(column, path, value) {
+      return {
+        sql: `JSON_INSERT(${column}, ?, CAST(? AS JSON))`,
+        params: [path, JSON.stringify(value)]
+      };
+    },
+    remove(column, path) {
+      return {
+        sql: `JSON_REMOVE(${column}, ?)`,
+        params: [path]
+      };
+    },
+    merge(column, patch) {
+      return {
+        sql: `JSON_MERGE_PATCH(${column}, CAST(? AS JSON))`,
+        params: [JSON.stringify(patch)]
+      };
+    }
+  };
+}
+function createJsonOps(dbType) {
+  switch (dbType) {
+    case "sqlite":
+      return createSqliteJsonOps();
+    case "postgresql":
+      return createPostgresJsonOps();
+    case "mysql":
+      return createMysqlJsonOps();
+  }
+}
+
+// src/reldb-pagination.ts
+var DEFAULT_PAGE = 1;
+var DEFAULT_PAGE_SIZE = 20;
+var MAX_PAGE_SIZE = 200;
+function normalizePage(value, fallback) {
+  if (!value || value < 1) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+function normalizePageSize(value, fallback, maxSize) {
+  if (!value || value < 1) {
+    return fallback;
+  }
+  return Math.min(Math.floor(value), maxSize);
+}
+function normalizePagination(options, overrides) {
+  const defaultPage = overrides?.defaultPage ?? DEFAULT_PAGE;
+  const defaultPageSize = overrides?.defaultPageSize ?? DEFAULT_PAGE_SIZE;
+  const maxPageSize = overrides?.maxPageSize ?? MAX_PAGE_SIZE;
+  const page = normalizePage(options?.page, defaultPage);
+  const pageSize = normalizePageSize(options?.pageSize, defaultPageSize, maxPageSize);
+  const offset = (page - 1) * pageSize;
+  return {
+    page,
+    pageSize,
+    offset,
+    limit: pageSize
+  };
+}
+function buildPaginatedResult(items, total, pagination2) {
+  return {
+    items,
+    total,
+    page: pagination2.page,
+    pageSize: pagination2.pageSize
+  };
+}
+var pagination = {
+  normalize: normalizePagination,
+  build: buildPaginatedResult
+};
+function parseCount(row) {
+  if (!row) {
+    return 0;
+  }
+  if ("total" in row) {
+    return Number(row.total ?? 0);
+  }
+  if ("__total__" in row) {
+    return Number(row.__total__ ?? 0);
+  }
+  if ("cnt" in row) {
+    return Number(row.cnt ?? 0);
+  }
+  const value = Object.values(row)[0];
+  if (typeof value === "bigint") {
+    return Number(value);
+  }
+  return Number(value ?? 0);
+}
+var VALID_IDENTIFIER_RE = /^[a-z_]\w{0,127}$/i;
+function validateIdentifier(name) {
+  if (VALID_IDENTIFIER_RE.test(name)) {
+    return ok(name);
+  }
+  return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_invalidIdentifier", { params: { name } }));
+}
+function validateIdentifiers(names) {
+  for (const name of names) {
+    const result = validateIdentifier(name);
+    if (!result.success) {
+      return err(result.error);
+    }
+  }
+  return ok(void 0);
+}
+function quoteIdentifier(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+function escapeSqlString(value) {
+  return value.replace(/'/g, "''");
+}
+
+// src/reldb-crud-kernel.ts
+var logger = core.logger.child({ module: "reldb", scope: "crud-kernel" });
+function buildSelectColumns(select) {
+  if (!select || select.length === 0) {
+    return "*";
+  }
+  return select.join(", ");
+}
+function pickColumns(data, allowList) {
+  const keys = Object.keys(data);
+  const columns = allowList ? keys.filter((key) => allowList.includes(key)) : keys;
+  const values = columns.map((key) => data[key]);
+  return { columns, values };
+}
+function createFailReldbCrudRepository(failedResult) {
+  const failResult = () => Promise.resolve(failedResult);
+  return {
+    create: () => failResult(),
+    createMany: () => failResult(),
+    createOrUpdate: () => failResult(),
+    findById: () => failResult(),
+    getById: () => failResult(),
+    findAll: () => failResult(),
+    findPage: () => failResult(),
+    updateById: () => failResult(),
+    deleteById: () => failResult(),
+    count: () => failResult(),
+    exists: () => failResult(),
+    existsById: () => failResult()
+  };
+}
+function createCrud(ops, config) {
+  const table = config.table;
+  const idColumn = config.idColumn ?? "id";
+  const selectColumns = buildSelectColumns(config.select);
+  const mapRow = config.mapRow ?? ((row) => row);
+  const dbType = config.dbType;
+  const tableValid = validateIdentifier(table);
+  if (!tableValid.success) {
+    return createFailReldbCrudRepository(tableValid);
+  }
+  const idColumnValid = validateIdentifier(idColumn);
+  if (!idColumnValid.success) {
+    return createFailReldbCrudRepository(idColumnValid);
+  }
+  if (config.select) {
+    const selectValid = validateIdentifiers(config.select);
+    if (!selectValid.success) {
+      return createFailReldbCrudRepository(selectValid);
+    }
+  }
+  if (config.createColumns) {
+    const createColsValid = validateIdentifiers(config.createColumns);
+    if (!createColsValid.success) {
+      return createFailReldbCrudRepository(createColsValid);
+    }
+  }
+  if (config.updateColumns) {
+    const updateColsValid = validateIdentifiers(config.updateColumns);
+    if (!updateColsValid.success) {
+      return createFailReldbCrudRepository(updateColsValid);
+    }
+  }
+  const buildWhereClause = (where) => where ? ` WHERE ${where}` : "";
+  const buildOrderClause = (orderBy) => {
+    if (!orderBy)
+      return "";
+    const parts = orderBy.split(",").map((s) => s.trim()).filter(Boolean);
+    const safeParts = [];
+    for (const part of parts) {
+      const match = part.match(/^(\w+)(?:\s+(ASC|DESC))?$/i);
+      if (!match) {
+        logger.debug("Skipped invalid orderBy segment", { table, segment: part });
+        continue;
+      }
+      const colName = match[1];
+      const direction = match[2] ?? "";
+      const colValid = validateIdentifier(colName);
+      if (!colValid.success) {
+        logger.debug("Skipped invalid orderBy identifier", { table, column: colName });
+        continue;
+      }
+      safeParts.push(direction ? `${colName} ${direction.toUpperCase()}` : colName);
+    }
+    if (safeParts.length === 0)
+      return "";
+    return ` ORDER BY ${safeParts.join(", ")}`;
+  };
+  const buildLimitOffset = (limit, offset) => {
+    const parts = [];
+    if (typeof limit === "number") {
+      parts.push(` LIMIT ${limit}`);
+    }
+    if (typeof offset === "number") {
+      parts.push(` OFFSET ${offset}`);
+    }
+    return parts.join("");
+  };
+  const createPayloadError = () => err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudEmptyPayload"));
+  const createColumnsError = () => err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudNoValidColumns"));
+  const resolveOps = (tx) => tx ?? ops;
+  return {
+    /**
+     * 创建单条记录
+     *
+     * @param data - 列名与值的映射（会根据 createColumns 白名单过滤）
+     * @param tx - 可选事务句柄
+     * @returns 插入结果（含 changes、lastInsertRowid）
+     */
+    async create(data, tx) {
+      if (!data || Object.keys(data).length === 0) {
+        return createPayloadError();
+      }
+      const { columns, values } = pickColumns(data, config.createColumns);
+      if (columns.length === 0) {
+        return createColumnsError();
+      }
+      const colValid = validateIdentifiers(columns);
+      if (!colValid.success) {
+        return err(colValid.error);
+      }
+      const placeholders = columns.map(() => "?").join(", ");
+      const sql = `INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders})`;
+      return resolveOps(tx).execute(sql, values);
+    },
+    /**
+     * 批量创建记录
+     *
+     * 所有记录在同一 batch 中执行，任意一条失败则整体失败。
+     *
+     * @param items - 待插入的数据数组
+     * @param tx - 可选事务句柄
+     * @returns 批量插入结果
+     */
+    async createMany(items, tx) {
+      if (!items || items.length === 0) {
+        return ok(void 0);
+      }
+      const statements = [];
+      for (const item of items) {
+        if (!item || Object.keys(item).length === 0) {
+          return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudEmptyPayload"));
+        }
+        const { columns, values } = pickColumns(item, config.createColumns);
+        if (columns.length === 0) {
+          return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_crudNoValidColumns"));
+        }
+        const colValid = validateIdentifiers(columns);
+        if (!colValid.success) {
+          return err(colValid.error);
+        }
+        const placeholders = columns.map(() => "?").join(", ");
+        const sql = `INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders})`;
+        statements.push({ sql, params: values });
+      }
+      return resolveOps(tx).batch(statements);
+    },
+    /**
+     * 创建或更新单条记录（upsert）
+     *
+     * 主键冲突时更新 updateColumns 中存在的列，否则插入新记录。
+     *
+     * @param data - 列名与值的映射
+     * @param tx - 可选事务句柄
+     * @returns 执行结果（含 changes）
+     */
+    async createOrUpdate(data, tx) {
+      if (!data || Object.keys(data).length === 0) {
+        return createPayloadError();
+      }
+      const { columns, values } = pickColumns(data, config.createColumns);
+      if (columns.length === 0) {
+        return createColumnsError();
+      }
+      const colValid = validateIdentifiers(columns);
+      if (!colValid.success) {
+        return err(colValid.error);
+      }
+      const placeholders = columns.map(() => "?").join(", ");
+      const updateCols = (config.updateColumns ?? columns).filter((col) => col !== idColumn && columns.includes(col));
+      if (updateCols.length === 0) {
+        const sql2 = `INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders})`;
+        return resolveOps(tx).execute(sql2, values);
+      }
+      let sql;
+      if (dbType === "mysql") {
+        const updateSet = updateCols.map((col) => `${col} = VALUES(${col})`).join(", ");
+        sql = `INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders}) ON DUPLICATE KEY UPDATE ${updateSet}`;
+      } else {
+        const updateSet = updateCols.map((col) => `${col} = excluded.${col}`).join(", ");
+        sql = `INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders}) ON CONFLICT(${idColumn}) DO UPDATE SET ${updateSet}`;
+      }
+      return resolveOps(tx).execute(sql, values);
+    },
+    /**
+     * 根据主键查找单条记录
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 记录对象或 null（未找到）
+     */
+    async findById(id, tx) {
+      const sql = `SELECT ${selectColumns} FROM ${table} WHERE ${idColumn} = ?`;
+      const result = await resolveOps(tx).get(sql, [id]);
+      if (!result.success) {
+        return result;
+      }
+      return ok(result.data ? mapRow(result.data) : null);
+    },
+    /**
+     * 根据主键获取单条记录（必须存在）
+     *
+     * 与 findById 不同，当记录不存在时返回 RECORD_NOT_FOUND 错误。
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 记录对象（不存在时返回错误）
+     */
+    async getById(id, tx) {
+      const findResult = await this.findById(id, tx);
+      if (!findResult.success) {
+        return findResult;
+      }
+      if (findResult.data === null) {
+        return err(HaiReldbError.RECORD_NOT_FOUND, reldbM("reldb_crudRecordNotFound", { params: { id: String(id) } }));
+      }
+      return ok(findResult.data);
+    },
+    /**
+     * 条件查询多条记录
+     *
+     * @param options - 查询条件（where、orderBy、limit、offset）
+     * @param tx - 可选事务句柄
+     * @returns 记录数组
+     */
+    async findAll(options = {}, tx) {
+      const whereClause = buildWhereClause(options.where);
+      const orderClause = buildOrderClause(options.orderBy);
+      const limitClause = buildLimitOffset(options.limit, options.offset);
+      const sql = `SELECT ${selectColumns} FROM ${table}${whereClause}${orderClause}${limitClause}`;
+      const result = await resolveOps(tx).query(sql, options.params);
+      if (!result.success) {
+        return result;
+      }
+      return ok(result.data.map((row) => mapRow(row)));
+    },
+    /**
+     * 分页查询记录
+     *
+     * @param options - 分页查询条件（where、orderBy、pagination、overrides）
+     * @param tx - 可选事务句柄
+     * @returns 分页结果（含 items、total、page、pageSize）
+     */
+    async findPage(options, tx) {
+      const whereClause = buildWhereClause(options.where);
+      const orderClause = buildOrderClause(options.orderBy);
+      const sql = `SELECT ${selectColumns} FROM ${table}${whereClause}${orderClause}`;
+      const pageResult = await resolveOps(tx).queryPage({
+        sql,
+        params: options.params,
+        pagination: options.pagination,
+        overrides: options.overrides
+      });
+      if (!pageResult.success) {
+        return pageResult;
+      }
+      return ok({
+        ...pageResult.data,
+        items: pageResult.data.items.map((row) => mapRow(row))
+      });
+    },
+    /**
+     * 根据主键更新记录
+     *
+     * 主键列不可更新，会自动排除。
+     *
+     * @param id - 主键值
+     * @param data - 待更新的列值映射（会根据 updateColumns 白名单过滤）
+     * @param tx - 可选事务句柄
+     * @returns 更新结果（含 changes）
+     */
+    async updateById(id, data, tx) {
+      if (!data || Object.keys(data).length === 0) {
+        return createPayloadError();
+      }
+      const allowList = (config.updateColumns ?? []).filter((column) => column !== idColumn);
+      const { columns } = pickColumns(data, allowList.length > 0 ? allowList : void 0);
+      const filtered = columns.filter((column) => column !== idColumn);
+      if (filtered.length === 0) {
+        return createColumnsError();
+      }
+      const colValid = validateIdentifiers(filtered);
+      if (!colValid.success) {
+        return err(colValid.error);
+      }
+      const setClause = filtered.map((column) => `${column} = ?`).join(", ");
+      const sql = `UPDATE ${table} SET ${setClause} WHERE ${idColumn} = ?`;
+      const params = [...filtered.map((column) => data[column]), id];
+      return resolveOps(tx).execute(sql, params);
+    },
+    /**
+     * 根据主键删除记录
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 删除结果（含 changes）
+     */
+    async deleteById(id, tx) {
+      const sql = `DELETE FROM ${table} WHERE ${idColumn} = ?`;
+      return resolveOps(tx).execute(sql, [id]);
+    },
+    /**
+     * 统计符合条件的记录数
+     *
+     * @param options - 查询条件（where、params）
+     * @param tx - 可选事务句柄
+     * @returns 记录数
+     */
+    async count(options = {}, tx) {
+      const whereClause = buildWhereClause(options.where);
+      const sql = `SELECT COUNT(*) as cnt FROM ${table}${whereClause}`;
+      const result = await resolveOps(tx).get(sql, options.params);
+      if (!result.success) {
+        return result;
+      }
+      return ok(parseCount(result.data ?? null));
+    },
+    /**
+     * 检查是否存在符合条件的记录
+     *
+     * @param options - 查询条件（where、params）
+     * @param tx - 可选事务句柄
+     * @returns 是否存在
+     */
+    async exists(options = {}, tx) {
+      const whereClause = buildWhereClause(options.where);
+      const sql = `SELECT 1 as exist_flag FROM ${table}${whereClause} LIMIT 1`;
+      const result = await resolveOps(tx).get(sql, options.params);
+      if (!result.success) {
+        return result;
+      }
+      return ok(Boolean(result.data));
+    },
+    /**
+     * 根据主键检查记录是否存在
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 是否存在
+     */
+    async existsById(id, tx) {
+      const sql = `SELECT 1 as exist_flag FROM ${table} WHERE ${idColumn} = ? LIMIT 1`;
+      const result = await resolveOps(tx).get(sql, [id]);
+      if (!result.success) {
+        return result;
+      }
+      return ok(Boolean(result.data));
+    }
+  };
+}
+function createTxHandle(baseDmlOps, callbacks) {
+  let active = true;
+  const ensureActive = () => {
+    if (!active) {
+      return err(HaiReldbError.TRANSACTION_FAILED, callbacks.errorMessage("transaction finished"));
+    }
+    return ok(void 0);
+  };
+  const guardedOps = {
+    async query(sql, params) {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      return baseDmlOps.query(sql, params);
+    },
+    async get(sql, params) {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      return baseDmlOps.get(sql, params);
+    },
+    async execute(sql, params) {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      return baseDmlOps.execute(sql, params);
+    },
+    async batch(statements) {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      return baseDmlOps.batch(statements);
+    },
+    async queryPage(options) {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      return baseDmlOps.queryPage(options);
+    }
+  };
+  const crudManager = {
+    table: (config) => createCrud(guardedOps, config)
+  };
+  return {
+    ...guardedOps,
+    crud: crudManager,
+    async commit() {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      try {
+        await callbacks.commit();
+        active = false;
+        return ok(void 0);
+      } catch (error) {
+        active = false;
+        return err(HaiReldbError.TRANSACTION_FAILED, callbacks.errorMessage(String(error)), error);
+      } finally {
+        callbacks.release();
+      }
+    },
+    async rollback() {
+      const check = ensureActive();
+      if (!check.success)
+        return check;
+      try {
+        await callbacks.rollback();
+        active = false;
+        return ok(void 0);
+      } catch (error) {
+        active = false;
+        return err(HaiReldbError.TRANSACTION_FAILED, callbacks.errorMessage(String(error)), error);
+      } finally {
+        callbacks.release();
+      }
+    }
+  };
+}
+function createTxWrap(beginTx) {
+  return async (fn) => {
+    const txResult = await beginTx();
+    if (!txResult.success)
+      return txResult;
+    try {
+      const result = await fn(txResult.data);
+      const commitResult = await txResult.data.commit();
+      if (!commitResult.success) {
+        return commitResult;
+      }
+      return ok(result);
+    } catch (error) {
+      await txResult.data.rollback();
+      return err(HaiReldbError.TRANSACTION_FAILED, reldbM("reldb_txFailed", { params: { error: String(error) } }), error);
+    }
+  };
+}
+
+// src/providers/reldb-provider-base.ts
+async function wrapOp(ctx, fn, errorDef, errorLabel, errorMeta) {
+  if (!ctx.isConnected()) {
+    return err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized"));
+  }
+  try {
+    return await fn();
+  } catch (error) {
+    ctx.logger.error(errorLabel, { ...errorMeta, error });
+    return err(errorDef, reldbM("reldb_queryFailed", { params: { error: String(error) } }), error);
+  }
+}
+function createBaseDdlOps(ctx, raw) {
+  return {
+    createTable(tableName, columns, ifNotExists = true) {
+      const v1 = validateIdentifier(tableName);
+      if (!v1.success)
+        return Promise.resolve(v1);
+      const v2 = validateIdentifiers(Object.keys(columns));
+      if (!v2.success)
+        return Promise.resolve(v2);
+      return wrapOp(ctx, () => raw.createTable(tableName, columns, ifNotExists), HaiReldbError.DDL_FAILED, "DDL: createTable failed", { tableName });
+    },
+    dropTable(tableName, ifExists = true) {
+      const v = validateIdentifier(tableName);
+      if (!v.success)
+        return Promise.resolve(v);
+      return wrapOp(ctx, () => raw.dropTable(tableName, ifExists), HaiReldbError.DDL_FAILED, "DDL: dropTable failed", { tableName });
+    },
+    addColumn(tableName, columnName, columnDef) {
+      const v1 = validateIdentifier(tableName);
+      if (!v1.success)
+        return Promise.resolve(v1);
+      const v2 = validateIdentifier(columnName);
+      if (!v2.success)
+        return Promise.resolve(v2);
+      return wrapOp(ctx, () => raw.addColumn(tableName, columnName, columnDef), HaiReldbError.DDL_FAILED, "DDL: addColumn failed", { tableName, columnName });
+    },
+    dropColumn(tableName, columnName) {
+      const v1 = validateIdentifier(tableName);
+      if (!v1.success)
+        return Promise.resolve(v1);
+      const v2 = validateIdentifier(columnName);
+      if (!v2.success)
+        return Promise.resolve(v2);
+      return wrapOp(ctx, () => raw.dropColumn(tableName, columnName), HaiReldbError.DDL_FAILED, "DDL: dropColumn failed", { tableName, columnName });
+    },
+    renameTable(oldName, newName) {
+      const v1 = validateIdentifier(oldName);
+      if (!v1.success)
+        return Promise.resolve(v1);
+      const v2 = validateIdentifier(newName);
+      if (!v2.success)
+        return Promise.resolve(v2);
+      return wrapOp(ctx, () => raw.renameTable(oldName, newName), HaiReldbError.DDL_FAILED, "DDL: renameTable failed", { oldName, newName });
+    },
+    createIndex(tableName, indexName, indexDef) {
+      const v1 = validateIdentifier(tableName);
+      if (!v1.success)
+        return Promise.resolve(v1);
+      const v2 = validateIdentifier(indexName);
+      if (!v2.success)
+        return Promise.resolve(v2);
+      const v3 = validateIdentifiers(indexDef.columns);
+      if (!v3.success)
+        return Promise.resolve(v3);
+      return wrapOp(ctx, () => raw.createIndex(tableName, indexName, indexDef), HaiReldbError.DDL_FAILED, "DDL: createIndex failed", { tableName, indexName });
+    },
+    dropIndex(indexName, ifExists = true) {
+      const v = validateIdentifier(indexName);
+      if (!v.success)
+        return Promise.resolve(v);
+      return wrapOp(ctx, () => raw.dropIndex(indexName, ifExists), HaiReldbError.DDL_FAILED, "DDL: dropIndex failed", { indexName });
+    },
+    raw(sql) {
+      return wrapOp(ctx, () => raw.raw(sql), HaiReldbError.DDL_FAILED, "DDL: raw failed");
+    }
+  };
+}
+function createBaseDmlOps(ctx, raw) {
+  return {
+    query: (sql, params) => wrapOp(ctx, () => raw.query(sql, params), HaiReldbError.QUERY_FAILED, "DML: query failed"),
+    get: (sql, params) => wrapOp(ctx, () => raw.get(sql, params), HaiReldbError.QUERY_FAILED, "DML: get failed"),
+    execute: (sql, params) => wrapOp(ctx, () => raw.execute(sql, params), HaiReldbError.QUERY_FAILED, "DML: execute failed"),
+    batch: (stmts) => wrapOp(ctx, () => raw.batch(stmts), HaiReldbError.QUERY_FAILED, "DML: batch failed"),
+    queryPage: (options) => wrapOp(ctx, () => raw.queryPage(options), HaiReldbError.QUERY_FAILED, "DML: queryPage failed")
+  };
+}
+function createBaseTxManager(ctx, beginTx) {
+  const begin = () => wrapOp(ctx, beginTx, HaiReldbError.TRANSACTION_FAILED, "TX: begin failed");
+  return {
+    begin,
+    wrap: createTxWrap(begin)
+  };
+}
+function createBaseCrudManager(ops) {
+  return {
+    table: (config) => createCrud(ops, config)
+  };
+}
+async function queryPageAsync(queryRows, options) {
+  const pagination2 = normalizePagination(options.pagination, options.overrides);
+  const countSql = `SELECT COUNT(*) as cnt FROM (${options.sql}) AS t`;
+  const countRows = await queryRows(countSql, options.params);
+  const total = countRows.length > 0 ? parseCount(countRows[0]) : 0;
+  const dataSql = `${options.sql} LIMIT ? OFFSET ?`;
+  const dataParams = [...options.params ?? [], pagination2.limit, pagination2.offset];
+  const rows = await queryRows(dataSql, dataParams);
+  return buildPaginatedResult(rows, total, pagination2);
+}
+
+// src/providers/reldb-ddl-builder.ts
+function buildColumnSqlBase(name, def, options) {
+  const parts = [options.quoteId(name)];
+  parts.push(options.mapType(def));
+  if (options.inlinePrimaryKey && def.primaryKey) {
+    parts.push("PRIMARY KEY");
+  }
+  if (options.extraConstraints) {
+    parts.push(...options.extraConstraints(def));
+  }
+  if (def.notNull && !def.primaryKey) {
+    parts.push("NOT NULL");
+  }
+  if (def.unique && !def.primaryKey) {
+    parts.push("UNIQUE");
+  }
+  if (def.defaultValue !== void 0) {
+    const custom = options.formatDefault?.(def);
+    if (custom === null) ; else if (custom !== void 0) {
+      parts.push(custom);
+    } else if (def.defaultValue === null) {
+      parts.push("DEFAULT NULL");
+    } else if (typeof def.defaultValue === "string") {
+      if (def.defaultValue.startsWith("(") && def.defaultValue.endsWith(")")) {
+        parts.push(`DEFAULT ${def.defaultValue}`);
+      } else {
+        parts.push(`DEFAULT '${escapeSqlString(def.defaultValue)}'`);
+      }
+    } else {
+      parts.push(`DEFAULT ${def.defaultValue}`);
+    }
+  }
+  if (options.inlinePrimaryKey && def.references) {
+    parts.push(`REFERENCES ${quoteIdentifier(def.references.table)}(${quoteIdentifier(def.references.column)})`);
+    if (def.references.onDelete) {
+      parts.push(`ON DELETE ${def.references.onDelete}`);
+    }
+    if (def.references.onUpdate) {
+      parts.push(`ON UPDATE ${def.references.onUpdate}`);
+    }
+  }
+  return parts.join(" ");
+}
+function buildDefaultCreateTableSql(buildColumnSql, quotedTable, columns, ifNotExists) {
+  const columnDefs = Object.entries(columns).map(([name, def]) => buildColumnSql(name, def)).join(", ");
+  const ifNotExistsClause = ifNotExists ? "IF NOT EXISTS " : "";
+  return `CREATE TABLE ${ifNotExistsClause}${quotedTable} (${columnDefs})`;
+}
+function buildDefaultCreateIndexSql(quoteId, quotedTable, quotedIndex, indexDef) {
+  const uniqueClause = indexDef.unique ? "UNIQUE " : "";
+  const columns = indexDef.columns.map((c) => quoteId(c)).join(", ");
+  const whereClause = indexDef.where ? ` WHERE ${indexDef.where}` : "";
+  return `CREATE ${uniqueClause}INDEX IF NOT EXISTS ${quotedIndex} ON ${quotedTable} (${columns})${whereClause}`;
+}
+function buildDefaultRenameTableSql(quotedOld, quotedNew) {
+  return `ALTER TABLE ${quotedOld} RENAME TO ${quotedNew}`;
+}
+function buildDefaultDropIndexSql(quoteId, indexName, ifExists) {
+  const ifExistsClause = ifExists ? "IF EXISTS " : "";
+  return `DROP INDEX ${ifExistsClause}${quoteId(indexName)}`;
+}
+
+// src/providers/reldb-provider-mysql.ts
+var logger2 = core.logger.child({ module: "reldb", scope: "mysql" });
+function createMysqlProvider() {
+  let pool = null;
+  const ctx = {
+    isConnected: () => pool !== null,
+    logger: logger2
+  };
+  function mysqlQuoteId(name) {
+    return `\`${name}\``;
+  }
+  function mysqlTxErrorMessage(detail) {
+    return reldbM("reldb_mysqlTxFailed", { params: { error: detail } });
+  }
+  async function findIndexTableName(queryFn, indexName) {
+    try {
+      const [rows] = await queryFn(
+        "SELECT TABLE_NAME as name FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA = DATABASE() AND INDEX_NAME = ? LIMIT 1",
+        [indexName]
+      );
+      const data = rows;
+      return ok(data[0]?.name ?? null);
+    } catch (error) {
+      return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_queryFailed", { params: { error: String(error) } }), error);
+    }
+  }
+  function mapMysqlType(def) {
+    switch (def.type) {
+      case "TEXT":
+        return "VARCHAR(255)";
+      case "INTEGER":
+        return def.autoIncrement ? "BIGINT" : "INT";
+      case "REAL":
+        return "DOUBLE";
+      case "BLOB":
+        return "BLOB";
+      case "BOOLEAN":
+        return "TINYINT(1)";
+      case "TIMESTAMP":
+        return "DATETIME";
+      case "JSON":
+        return "JSON";
+      default:
+        return "TEXT";
+    }
+  }
+  function mysqlBuildColumnSql(name, def) {
+    return buildColumnSqlBase(name, def, {
+      quoteId: mysqlQuoteId,
+      mapType: mapMysqlType,
+      inlinePrimaryKey: false,
+      extraConstraints: (d) => {
+        const extras = [];
+        if (d.primaryKey)
+          extras.push("NOT NULL");
+        if (d.autoIncrement)
+          extras.push("AUTO_INCREMENT");
+        return extras;
+      },
+      formatDefault: (d) => {
+        if (d.defaultValue === void 0)
+          return void 0;
+        if (d.autoIncrement)
+          return null;
+        if (typeof d.defaultValue === "string" && (d.defaultValue === "NOW()" || d.defaultValue === "CURRENT_TIMESTAMP")) {
+          return `DEFAULT ${d.defaultValue}`;
+        }
+        if (typeof d.defaultValue === "boolean") {
+          return `DEFAULT ${d.defaultValue ? 1 : 0}`;
+        }
+        return void 0;
+      }
+    });
+  }
+  function mysqlBuildCreateTableSql(quotedTable, columns, ifNotExists) {
+    const columnDefs = [];
+    let primaryKeyCol = null;
+    for (const [name, def] of Object.entries(columns)) {
+      columnDefs.push(mysqlBuildColumnSql(name, def));
+      if (def.primaryKey) {
+        primaryKeyCol = name;
+      }
+    }
+    if (primaryKeyCol) {
+      columnDefs.push(`PRIMARY KEY (${mysqlQuoteId(primaryKeyCol)})`);
+    }
+    for (const [name, def] of Object.entries(columns)) {
+      if (def.references) {
+        let fkSql = `FOREIGN KEY (${mysqlQuoteId(name)}) REFERENCES ${mysqlQuoteId(def.references.table)}(${mysqlQuoteId(def.references.column)})`;
+        if (def.references.onDelete) {
+          fkSql += ` ON DELETE ${def.references.onDelete}`;
+        }
+        if (def.references.onUpdate) {
+          fkSql += ` ON UPDATE ${def.references.onUpdate}`;
+        }
+        columnDefs.push(fkSql);
+      }
+    }
+    const ifNotExistsClause = ifNotExists ? "IF NOT EXISTS " : "";
+    return `CREATE TABLE ${ifNotExistsClause}${quotedTable} (${columnDefs.join(", ")}) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`;
+  }
+  const rawDdl = {
+    async createTable(name, columns, ifNotExists = true) {
+      const quotedTable = mysqlQuoteId(name);
+      const sql = mysqlBuildCreateTableSql(quotedTable, columns, ifNotExists);
+      await pool.query(sql);
+      return ok(void 0);
+    },
+    async dropTable(name, ifExists) {
+      const ifExistsClause = ifExists ? "IF EXISTS " : "";
+      await pool.query(`DROP TABLE ${ifExistsClause}${mysqlQuoteId(name)}`);
+      return ok(void 0);
+    },
+    async addColumn(table, column, def) {
+      const colSql = mysqlBuildColumnSql(column, def);
+      await pool.query(`ALTER TABLE ${mysqlQuoteId(table)} ADD COLUMN ${colSql}`);
+      return ok(void 0);
+    },
+    async dropColumn(table, column) {
+      await pool.query(`ALTER TABLE ${mysqlQuoteId(table)} DROP COLUMN ${mysqlQuoteId(column)}`);
+      return ok(void 0);
+    },
+    async renameTable(oldName, newName) {
+      await pool.query(`RENAME TABLE ${mysqlQuoteId(oldName)} TO ${mysqlQuoteId(newName)}`);
+      return ok(void 0);
+    },
+    async createIndex(table, index, def) {
+      const uniqueClause = def.unique ? "UNIQUE " : "";
+      const columns = def.columns.map((c) => mysqlQuoteId(c)).join(", ");
+      await pool.query(`CREATE ${uniqueClause}INDEX ${mysqlQuoteId(index)} ON ${mysqlQuoteId(table)} (${columns})`);
+      return ok(void 0);
+    },
+    async dropIndex(index, ifExists) {
+      const tableResult = await findIndexTableName((s, v) => pool.query(s, v), index);
+      if (!tableResult.success)
+        return tableResult;
+      if (!tableResult.data) {
+        if (ifExists)
+          return ok(void 0);
+        return err(HaiReldbError.DDL_FAILED, reldbM("reldb_ddlFailed", { params: { error: `index not found: ${index}` } }));
+      }
+      await pool.query(`DROP INDEX ${mysqlQuoteId(index)} ON ${mysqlQuoteId(tableResult.data)}`);
+      return ok(void 0);
+    },
+    async raw(sql) {
+      await pool.query(sql);
+      return ok(void 0);
+    }
+  };
+  const rawDml = {
+    async query(sql, params) {
+      const [rows] = await pool.query(sql, params);
+      return ok(rows);
+    },
+    async get(sql, params) {
+      const [rows] = await pool.query(sql, params);
+      return ok(rows[0] ?? null);
+    },
+    async execute(sql, params) {
+      const [result] = await pool.execute(sql, params);
+      return ok({ changes: result.affectedRows, lastInsertRowid: result.insertId });
+    },
+    async batch(statements) {
+      let connection = null;
+      try {
+        connection = await pool.getConnection();
+        await connection.beginTransaction();
+        for (const { sql: s, params } of statements) {
+          await connection.execute(s, params);
+        }
+        await connection.commit();
+        return ok(void 0);
+      } catch (error) {
+        if (connection) {
+          await connection.rollback().catch(() => {
+          });
+        }
+        return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_batchFailed", { params: { error: String(error) } }), error);
+      } finally {
+        if (connection) {
+          connection.release();
+        }
+      }
+    },
+    async queryPage(options) {
+      const result = await queryPageAsync(
+        async (sql, params) => {
+          const [rows] = await pool.query(sql, params);
+          return rows;
+        },
+        options
+      );
+      return ok(result);
+    }
+  };
+  function createMysqlTxDmlOps(conn) {
+    return {
+      async query(sql, params) {
+        const [rows] = await conn.query(sql, params);
+        return ok(rows);
+      },
+      async get(sql, params) {
+        const [rows] = await conn.query(sql, params);
+        return ok(rows[0] ?? null);
+      },
+      async execute(sql, params) {
+        const [result] = await conn.execute(sql, params);
+        return ok({ changes: result.affectedRows, lastInsertRowid: result.insertId });
+      },
+      async batch(statements) {
+        for (const { sql: s, params } of statements) {
+          await conn.execute(s, params);
+        }
+        return ok(void 0);
+      },
+      async queryPage(options) {
+        const result = await queryPageAsync(
+          async (sql, params) => {
+            const [rows] = await conn.query(sql, params);
+            return rows;
+          },
+          options
+        );
+        return ok(result);
+      }
+    };
+  }
+  async function beginTx() {
+    let connection = null;
+    try {
+      connection = await pool.getConnection();
+      await connection.beginTransaction();
+    } catch (error) {
+      if (connection) {
+        connection.release();
+      }
+      return err(HaiReldbError.TRANSACTION_FAILED, mysqlTxErrorMessage(String(error)), error);
+    }
+    const txDmlOps = createMysqlTxDmlOps(connection);
+    return ok(createTxHandle(txDmlOps, {
+      commit: async () => {
+        await connection.commit();
+      },
+      rollback: async () => {
+        await connection.rollback();
+      },
+      release: () => connection.release(),
+      errorMessage: mysqlTxErrorMessage
+    }));
+  }
+  const dmlOps = createBaseDmlOps(ctx, rawDml);
+  return {
+    async connect(config) {
+      if (config.type !== "mysql") {
+        return err(HaiReldbError.UNSUPPORTED_TYPE, reldbM("reldb_mysqlOnlyMysql"));
+      }
+      try {
+        const mysql = __require("mysql2/promise");
+        pool = mysql.createPool({
+          uri: config.url,
+          host: config.host,
+          port: config.port,
+          database: config.database,
+          user: config.user,
+          password: config.password,
+          ssl: config.ssl,
+          connectionLimit: config.pool?.max ?? 10,
+          waitForConnections: true,
+          queueLimit: 0,
+          charset: config.mysql?.charset ?? "utf8mb4"
+        });
+        await pool.query("SELECT 1");
+        logger2.info("Connected to MySQL", { host: config.host, port: config.port, database: config.database });
+        return ok(void 0);
+      } catch (error) {
+        pool = null;
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_mysqlConnectionFailed", { params: { error: String(error) } }), error);
+      }
+    },
+    async close() {
+      if (pool) {
+        try {
+          await pool.end();
+        } catch (error) {
+          pool = null;
+          return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_mysqlConnectionFailed", { params: { error: String(error) } }), error);
+        }
+        pool = null;
+        logger2.info("Disconnected from MySQL");
+      }
+      return ok(void 0);
+    },
+    isConnected: () => ctx.isConnected(),
+    ddl: createBaseDdlOps(ctx, rawDdl),
+    sql: dmlOps,
+    crud: createBaseCrudManager(dmlOps),
+    tx: createBaseTxManager(ctx, beginTx)
+  };
+}
+var logger3 = core.logger.child({ module: "reldb", scope: "postgres" });
+function createPostgresProvider() {
+  let pool = null;
+  const ctx = {
+    isConnected: () => pool !== null,
+    logger: logger3
+  };
+  function convertPlaceholders(sql) {
+    let index = 0;
+    return sql.replace(/\?/g, () => `$${++index}`);
+  }
+  function pgTxErrorMessage(detail) {
+    return reldbM("reldb_postgresTxFailed", { params: { error: detail } });
+  }
+  function mapPgType(def) {
+    switch (def.type) {
+      case "TEXT":
+        return "TEXT";
+      case "INTEGER":
+        return def.autoIncrement ? "BIGSERIAL" : "INTEGER";
+      case "REAL":
+        return "DOUBLE PRECISION";
+      case "BLOB":
+        return "BYTEA";
+      case "BOOLEAN":
+        return "BOOLEAN";
+      case "TIMESTAMP":
+        return "TIMESTAMP";
+      case "JSON":
+        return "JSONB";
+      default:
+        return "TEXT";
+    }
+  }
+  function pgBuildColumnSql(name, def) {
+    return buildColumnSqlBase(name, def, {
+      quoteId: quoteIdentifier,
+      mapType: mapPgType,
+      inlinePrimaryKey: true,
+      formatDefault: (d) => {
+        if (d.defaultValue === void 0)
+          return void 0;
+        if (typeof d.defaultValue === "string" && (d.defaultValue === "NOW()" || d.defaultValue === "CURRENT_TIMESTAMP")) {
+          return `DEFAULT ${d.defaultValue}`;
+        }
+        return void 0;
+      }
+    });
+  }
+  async function pgQueryRows(queryFn, sql, params) {
+    const result = await queryFn(convertPlaceholders(sql), params);
+    return result.rows;
+  }
+  const rawDdl = {
+    async createTable(name, columns, ifNotExists = true) {
+      const quotedTable = quoteIdentifier(name);
+      const sql = buildDefaultCreateTableSql(pgBuildColumnSql, quotedTable, columns, ifNotExists);
+      await pool.query(sql);
+      return ok(void 0);
+    },
+    async dropTable(name, ifExists) {
+      const ifExistsClause = ifExists ? "IF EXISTS " : "";
+      await pool.query(`DROP TABLE ${ifExistsClause}${quoteIdentifier(name)}`);
+      return ok(void 0);
+    },
+    async addColumn(table, column, def) {
+      const colSql = pgBuildColumnSql(column, def);
+      await pool.query(`ALTER TABLE ${quoteIdentifier(table)} ADD COLUMN ${colSql}`);
+      return ok(void 0);
+    },
+    async dropColumn(table, column) {
+      await pool.query(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN ${quoteIdentifier(column)}`);
+      return ok(void 0);
+    },
+    async renameTable(oldName, newName) {
+      await pool.query(buildDefaultRenameTableSql(quoteIdentifier(oldName), quoteIdentifier(newName)));
+      return ok(void 0);
+    },
+    async createIndex(table, index, def) {
+      const sql = buildDefaultCreateIndexSql(quoteIdentifier, quoteIdentifier(table), quoteIdentifier(index), def);
+      await pool.query(sql);
+      return ok(void 0);
+    },
+    async dropIndex(index, ifExists = true) {
+      const sql = buildDefaultDropIndexSql(quoteIdentifier, index, ifExists);
+      await pool.query(sql);
+      return ok(void 0);
+    },
+    async raw(sql) {
+      await pool.query(sql);
+      return ok(void 0);
+    }
+  };
+  const rawDml = {
+    async query(sql, params) {
+      const rows = await pgQueryRows((t, v) => pool.query(t, v), sql, params);
+      return ok(rows);
+    },
+    async get(sql, params) {
+      const rows = await pgQueryRows((t, v) => pool.query(t, v), sql, params);
+      return ok(rows[0] ?? null);
+    },
+    async execute(sql, params) {
+      const result = await pool.query(convertPlaceholders(sql), params);
+      return ok({ changes: result.rowCount ?? 0 });
+    },
+    async batch(statements) {
+      let client = null;
+      try {
+        client = await pool.connect();
+        await client.query("BEGIN");
+        for (const { sql: s, params } of statements) {
+          await client.query(convertPlaceholders(s), params);
+        }
+        await client.query("COMMIT");
+        return ok(void 0);
+      } catch (error) {
+        if (client) {
+          await client.query("ROLLBACK").catch(() => {
+          });
+        }
+        return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_batchFailed", { params: { error: String(error) } }), error);
+      } finally {
+        if (client) {
+          client.release();
+        }
+      }
+    },
+    async queryPage(options) {
+      const result = await queryPageAsync(
+        async (sql, params) => {
+          const r = await pool.query(convertPlaceholders(sql), params);
+          return r.rows;
+        },
+        options
+      );
+      return ok(result);
+    }
+  };
+  function createPgTxDmlOps(client) {
+    const queryFn = (text, values) => client.query(text, values);
+    return {
+      async query(sql, params) {
+        const rows = await pgQueryRows(queryFn, sql, params);
+        return ok(rows);
+      },
+      async get(sql, params) {
+        const rows = await pgQueryRows(queryFn, sql, params);
+        return ok(rows[0] ?? null);
+      },
+      async execute(sql, params) {
+        const result = await queryFn(convertPlaceholders(sql), params);
+        return ok({ changes: result.rowCount ?? 0 });
+      },
+      async batch(statements) {
+        for (const { sql: s, params } of statements) {
+          await queryFn(convertPlaceholders(s), params);
+        }
+        return ok(void 0);
+      },
+      async queryPage(options) {
+        const result = await queryPageAsync(
+          async (sql, params) => {
+            const r = await queryFn(convertPlaceholders(sql), params);
+            return r.rows;
+          },
+          options
+        );
+        return ok(result);
+      }
+    };
+  }
+  async function beginTx() {
+    let client = null;
+    try {
+      client = await pool.connect();
+      await client.query("BEGIN");
+    } catch (error) {
+      if (client) {
+        client.release();
+      }
+      return err(HaiReldbError.TRANSACTION_FAILED, pgTxErrorMessage(String(error)), error);
+    }
+    const txDmlOps = createPgTxDmlOps(client);
+    return ok(createTxHandle(txDmlOps, {
+      commit: async () => {
+        await client.query("COMMIT");
+      },
+      rollback: async () => {
+        await client.query("ROLLBACK");
+      },
+      release: () => client.release(),
+      errorMessage: pgTxErrorMessage
+    }));
+  }
+  const dmlOps = createBaseDmlOps(ctx, rawDml);
+  return {
+    async connect(config) {
+      if (config.type !== "postgresql") {
+        return err(HaiReldbError.UNSUPPORTED_TYPE, reldbM("reldb_postgresOnlyPostgresql"));
+      }
+      try {
+        const { Pool } = __require("pg");
+        pool = new Pool({
+          connectionString: config.url,
+          host: config.host,
+          port: config.port,
+          database: config.database,
+          user: config.user,
+          password: config.password,
+          ssl: config.ssl,
+          min: config.pool?.min,
+          max: config.pool?.max ?? 10,
+          idleTimeoutMillis: config.pool?.idleTimeout,
+          connectionTimeoutMillis: config.pool?.acquireTimeout
+        });
+        await pool.query("SELECT 1");
+        logger3.info("Connected to PostgreSQL", { host: config.host, port: config.port, database: config.database });
+        return ok(void 0);
+      } catch (error) {
+        pool = null;
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_postgresConnectionFailed", { params: { error: String(error) } }), error);
+      }
+    },
+    async close() {
+      if (pool) {
+        try {
+          await pool.end();
+        } catch (error) {
+          pool = null;
+          return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_postgresConnectionFailed", { params: { error: String(error) } }), error);
+        }
+        pool = null;
+        logger3.info("Disconnected from PostgreSQL");
+      }
+      return ok(void 0);
+    },
+    isConnected: () => ctx.isConnected(),
+    ddl: createBaseDdlOps(ctx, rawDdl),
+    sql: dmlOps,
+    crud: createBaseCrudManager(dmlOps),
+    tx: createBaseTxManager(ctx, beginTx)
+  };
+}
+var require2 = createRequire(import.meta.url);
+var logger4 = core.logger.child({ module: "reldb", scope: "sqlite" });
+function createSqliteProvider() {
+  let database = null;
+  let txChain = Promise.resolve();
+  const TX_LOCK_TIMEOUT_MS = 3e4;
+  async function acquireTxLock() {
+    let release;
+    const current = new Promise((resolve) => {
+      release = resolve;
+    });
+    const prev = txChain;
+    txChain = txChain.then(() => current);
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        release();
+        reject(new Error(`SQLite transaction lock acquisition timed out after ${TX_LOCK_TIMEOUT_MS}ms`));
+      }, TX_LOCK_TIMEOUT_MS);
+    });
+    try {
+      await Promise.race([prev, timeoutPromise]);
+    } finally {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+    }
+    return release;
+  }
+  const ctx = {
+    isConnected: () => database !== null && database.open,
+    logger: logger4
+  };
+  function mapSqliteType(def) {
+    switch (def.type) {
+      case "TEXT":
+      case "JSON":
+        return "TEXT";
+      case "INTEGER":
+      case "BOOLEAN":
+        return "INTEGER";
+      case "REAL":
+        return "REAL";
+      case "BLOB":
+        return "BLOB";
+      case "TIMESTAMP":
+        return "INTEGER";
+      // Unix timestamp
+      default:
+        return "TEXT";
+    }
+  }
+  function sqliteBuildColumnSql(name, def) {
+    return buildColumnSqlBase(name, def, {
+      quoteId: quoteIdentifier,
+      mapType: mapSqliteType,
+      inlinePrimaryKey: true,
+      extraConstraints: (d) => {
+        const extras = [];
+        if (d.primaryKey && d.autoIncrement)
+          extras.push("AUTOINCREMENT");
+        return extras;
+      }
+    });
+  }
+  function sqliteTxErrorMessage(detail) {
+    return reldbM("reldb_sqliteTxFailed", { params: { error: detail } });
+  }
+  const rawDdl = {
+    async createTable(name, columns, ifNotExists = true) {
+      const quotedTable = quoteIdentifier(name);
+      const sql = buildDefaultCreateTableSql(sqliteBuildColumnSql, quotedTable, columns, ifNotExists);
+      database.exec(sql);
+      return ok(void 0);
+    },
+    async dropTable(name, ifExists) {
+      const ifExistsClause = ifExists ? "IF EXISTS " : "";
+      database.exec(`DROP TABLE ${ifExistsClause}${quoteIdentifier(name)}`);
+      return ok(void 0);
+    },
+    async addColumn(table, column, def) {
+      const colSql = sqliteBuildColumnSql(column, def);
+      database.exec(`ALTER TABLE ${quoteIdentifier(table)} ADD COLUMN ${colSql}`);
+      return ok(void 0);
+    },
+    async dropColumn(table, column) {
+      database.exec(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN ${quoteIdentifier(column)}`);
+      return ok(void 0);
+    },
+    async renameTable(oldName, newName) {
+      database.exec(buildDefaultRenameTableSql(quoteIdentifier(oldName), quoteIdentifier(newName)));
+      return ok(void 0);
+    },
+    async createIndex(table, index, def) {
+      const sql = buildDefaultCreateIndexSql(quoteIdentifier, quoteIdentifier(table), quoteIdentifier(index), def);
+      database.exec(sql);
+      return ok(void 0);
+    },
+    async dropIndex(index, ifExists = true) {
+      const sql = buildDefaultDropIndexSql(quoteIdentifier, index, ifExists);
+      database.exec(sql);
+      return ok(void 0);
+    },
+    async raw(sql) {
+      database.exec(sql);
+      return ok(void 0);
+    }
+  };
+  const rawDml = {
+    async query(sql, params) {
+      const stmt = database.prepare(sql);
+      const rows = params ? stmt.all(...params) : stmt.all();
+      return ok(rows);
+    },
+    async get(sql, params) {
+      const stmt = database.prepare(sql);
+      const row = params ? stmt.get(...params) : stmt.get();
+      return ok(row ?? null);
+    },
+    async execute(sql, params) {
+      const stmt = database.prepare(sql);
+      const result = params ? stmt.run(...params) : stmt.run();
+      return ok({ changes: result.changes, lastInsertRowid: result.lastInsertRowid });
+    },
+    async batch(statements) {
+      const releaseTxLock = await acquireTxLock();
+      try {
+        const db = database;
+        const transaction = db.transaction(() => {
+          for (const { sql: s, params } of statements) {
+            const stmt = db.prepare(s);
+            if (params)
+              stmt.run(...params);
+            else stmt.run();
+          }
+        });
+        transaction();
+        return ok(void 0);
+      } catch (error) {
+        return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_sqliteBatchFailed", { params: { error: String(error) } }), error);
+      } finally {
+        releaseTxLock();
+      }
+    },
+    async queryPage(options) {
+      const result = await queryPageAsync(
+        async (sqlStr, params) => {
+          const stmt = database.prepare(sqlStr);
+          return params ? stmt.all(...params) : stmt.all();
+        },
+        options
+      );
+      return ok(result);
+    }
+  };
+  function createSqliteTxDmlOps(db) {
+    return {
+      async query(sql, params) {
+        const stmt = db.prepare(sql);
+        return ok(params ? stmt.all(...params) : stmt.all());
+      },
+      async get(sql, params) {
+        const stmt = db.prepare(sql);
+        return ok((params ? stmt.get(...params) : stmt.get()) ?? null);
+      },
+      async execute(sql, params) {
+        const stmt = db.prepare(sql);
+        const result = params ? stmt.run(...params) : stmt.run();
+        return ok({ changes: result.changes, lastInsertRowid: result.lastInsertRowid });
+      },
+      async batch(statements) {
+        for (const { sql: s, params } of statements) {
+          const stmt = db.prepare(s);
+          if (params)
+            stmt.run(...params);
+          else stmt.run();
+        }
+        return ok(void 0);
+      },
+      async queryPage(options) {
+        const result = await queryPageAsync(
+          async (sqlStr, params) => {
+            const stmt = db.prepare(sqlStr);
+            return params ? stmt.all(...params) : stmt.all();
+          },
+          options
+        );
+        return ok(result);
+      }
+    };
+  }
+  async function beginTx() {
+    const db = database;
+    let released = false;
+    const releaseTxLock = await acquireTxLock();
+    const finishTransaction = () => {
+      if (!released) {
+        released = true;
+        releaseTxLock();
+      }
+    };
+    try {
+      db.exec("BEGIN TRANSACTION");
+    } catch (error) {
+      finishTransaction();
+      return err(HaiReldbError.TRANSACTION_FAILED, sqliteTxErrorMessage(String(error)), error);
+    }
+    const txDmlOps = createSqliteTxDmlOps(db);
+    return ok(createTxHandle(txDmlOps, {
+      commit: async () => {
+        db.exec("COMMIT");
+      },
+      rollback: async () => {
+        db.exec("ROLLBACK");
+      },
+      release: () => finishTransaction(),
+      errorMessage: sqliteTxErrorMessage
+    }));
+  }
+  const dmlOps = createBaseDmlOps(ctx, rawDml);
+  return {
+    async connect(config) {
+      if (config.type !== "sqlite") {
+        return err(HaiReldbError.UNSUPPORTED_TYPE, reldbM("reldb_sqliteOnlySqlite"));
+      }
+      if (!config.database) {
+        return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_sqliteNeedPath"));
+      }
+      try {
+        const Database = require2("better-sqlite3");
+        const sqliteOptions = {
+          walMode: true,
+          readonly: false,
+          ...config.sqlite ?? {}
+        };
+        database = new Database(config.database, {
+          readonly: sqliteOptions.readonly ?? false
+        });
+        if (sqliteOptions.walMode !== false) {
+          database.pragma("journal_mode = WAL");
+        }
+        logger4.info("Connected to SQLite", { database: config.database });
+        return ok(void 0);
+      } catch (error) {
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_sqliteConnectionFailed", { params: { error: String(error) } }), error);
+      }
+    },
+    async close() {
+      if (database) {
+        try {
+          database.close();
+        } catch (error) {
+          database = null;
+          return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_sqliteConnectionFailed", { params: { error: String(error) } }), error);
+        }
+        database = null;
+        logger4.info("Disconnected from SQLite");
+      }
+      return ok(void 0);
+    },
+    isConnected: () => ctx.isConnected(),
+    ddl: createBaseDdlOps(ctx, rawDdl),
+    sql: dmlOps,
+    crud: createBaseCrudManager(dmlOps),
+    tx: createBaseTxManager(ctx, beginTx)
+  };
+}
+
+// src/reldb-main.ts
+var logger5 = core.logger.child({ module: "reldb", scope: "main" });
+var currentProvider = null;
+var currentConfig = null;
+var currentJsonOps = null;
+var initInProgress = false;
+function createProvider(config) {
+  switch (config.type) {
+    case "sqlite":
+      return createSqliteProvider();
+    case "postgresql":
+      return createPostgresProvider();
+    case "mysql":
+      return createMysqlProvider();
+  }
+}
+var notInitialized = core.module.createNotInitializedKit(
+  HaiReldbError.NOT_INITIALIZED,
+  () => reldbM("reldb_notInitialized")
+);
+var notInitializedDdl = notInitialized.proxy();
+var notInitializedSql = notInitialized.proxy();
+var notInitializedCrud = createBaseCrudManager(notInitializedSql);
+var notInitializedJson = createJsonOps("sqlite");
+var notInitializedTx = {
+  begin: async () => notInitialized.result(),
+  wrap: async () => notInitialized.result()
+};
+var reldb = {
+  /**
+   * 初始化数据库连接
+   *
+   * @param config - 数据库配置（允许部分字段，内部会补齐默认值）
+   * @returns 初始化结果，失败时包含错误信息
+   */
+  async init(config) {
+    if (initInProgress) {
+      logger5.warn("RelDB module init is already in progress, skipping concurrent call");
+      return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_configError", { params: { error: "init already in progress" } }));
+    }
+    initInProgress = true;
+    try {
+      if (currentProvider) {
+        logger5.warn("RelDB module is already initialized, reinitializing");
+        await reldb.close();
+      }
+      logger5.info("Initializing RelDB module");
+      const parseResult = ReldbConfigSchema.safeParse(config);
+      if (!parseResult.success) {
+        logger5.error("RelDB config validation failed", { error: parseResult.error.message });
+        return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_configError", { params: { error: parseResult.error.message } }), parseResult.error);
+      }
+      const parsed = parseResult.data;
+      try {
+        const provider = createProvider(parsed);
+        const connectResult = await provider.connect(parsed);
+        if (!connectResult.success) {
+          logger5.error("RelDB module initialization failed", {
+            code: connectResult.error.code,
+            message: connectResult.error.message
+          });
+          return connectResult;
+        }
+        currentProvider = provider;
+        currentConfig = parsed;
+        currentJsonOps = createJsonOps(parsed.type);
+        logger5.info("RelDB module initialized", { type: parsed.type });
+        return ok(void 0);
+      } catch (error) {
+        logger5.error("RelDB module initialization failed", { error });
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_initFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
+      }
+    } finally {
+      initInProgress = false;
+    }
+  },
+  /**
+   * 获取 DDL 操作接口
+   *
+   * 未初始化时返回占位对象（所有调用返回 NOT_INITIALIZED）。
+   */
+  get ddl() {
+    return currentProvider?.ddl ?? notInitializedDdl;
+  },
+  /**
+   * 获取 SQL 操作接口
+   *
+   * 未初始化时返回占位对象（所有调用返回 NOT_INITIALIZED）。
+   */
+  get sql() {
+    return currentProvider?.sql ?? notInitializedSql;
+  },
+  /**
+   * 获取 CRUD 管理器
+   *
+   * 通过 `reldb.crud.table(config)` 获取单表 CRUD 仓库。
+   * 未初始化时返回占位对象（所有调用返回 NOT_INITIALIZED）。
+   */
+  get crud() {
+    return currentProvider?.crud ?? notInitializedCrud;
+  },
+  /** 事务管理器 */
+  get tx() {
+    return currentProvider?.tx ?? notInitializedTx;
+  },
+  /** 获取当前配置（未初始化时为 null） */
+  get config() {
+    return currentConfig;
+  },
+  /** 检查是否已初始化 */
+  get isInitialized() {
+    return currentProvider !== null && currentProvider.isConnected();
+  },
+  /**
+   * 获取分页工具
+   *
+   * 提供 `reldb.pagination.normalize()` 和 `reldb.pagination.build()` 两个纯函数，
+   * 用于自定义分页场景（无需数据库连接）。
+   */
+  get pagination() {
+    return pagination;
+  },
+  /**
+   * 获取 JSON 路径操作 SQL 构建器
+   *
+   * 根据当前数据库类型返回对应的 JSON 操作实现。
+   * 未初始化时返回 SQLite 格式的构建器作为默认值。
+   *
+   * 构建器方法均为纯函数，返回 `{ sql, params }` 可直接嵌入 SQL 查询。
+   *
+   * @example
+   * ```ts
+   * // 提取 JSON 字段值
+   * 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],
+   * )
+   * ```
+   */
+  get json() {
+    return currentJsonOps ?? notInitializedJson;
+  },
+  /**
+   * 关闭数据库连接
+   *
+   * 多次调用安全，未初始化时直接返回。
+   */
+  async close() {
+    if (!currentProvider) {
+      currentConfig = null;
+      currentJsonOps = null;
+      logger5.info("RelDB module already closed, skipping");
+      return ok(void 0);
+    }
+    logger5.info("Closing RelDB module");
+    try {
+      const closeResult = await currentProvider.close();
+      if (!closeResult.success) {
+        logger5.error("RelDB module close failed", { code: closeResult.error.code, message: closeResult.error.message });
+        return closeResult;
+      }
+      logger5.info("RelDB module closed");
+      return ok(void 0);
+    } catch (error) {
+      logger5.error("RelDB module close failed", { error });
+      return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_closeFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
+    } finally {
+      currentProvider = null;
+      currentConfig = null;
+      currentJsonOps = null;
+    }
+  }
+};
+
+export { BaseReldbCrudRepository, HaiReldbError, MysqlConfigSchema, MysqlOptionsSchema, PoolConfigSchema, PostgresqlConfigSchema, ReldbConfigSchema, ReldbTypeSchema, SqliteConfigSchema, SqliteOptionsSchema, SslConfigSchema, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map