@h-ai/reldb 0.1.0-alpha9 → 1.0.0-beta.2

package/dist/index.js

@@ -1,147 +1,124 @@
-import { z } from 'zod';
-import { core, ok, err } from '@h-ai/core';
+import { ReldbConfigSchema, MysqlPoolConfigSchema } from './chunk-SDS2ZT3V.js';
+export { MysqlConfigSchema, MysqlOptionsSchema, MysqlPoolConfigSchema, MysqlSslConfigSchema, PoolConfigSchema, PostgresqlConfigSchema, ReldbConfigSchema, ReldbOperationLogConfigSchema, ReldbTypeSchema, SqliteConfigSchema, SqliteOptionsSchema, SslConfigSchema } from './chunk-SDS2ZT3V.js';
+import { core, ok, err, HaiCommonError } from '@h-ai/core';
+import process from 'process';
 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
-]);
+import { isIP } from 'net';
+import { performance as performance$1 } from 'perf_hooks';
+import { setTimeout as setTimeout$1 } from 'timers/promises';
+import { existsSync } from 'fs';
+import { Worker } from 'worker_threads';
 
 // 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_ddlFailed: "DDL operation failed: {error}",
-  reldb_queryFailed: "Query failed: {error}",
-  reldb_batchFailed: "Batch execute failed: {error}",
-  reldb_postgresTxFailed: "Transaction failed: {error}",
+  reldb_initFailed: "Failed to initialize database",
+  reldb_closeFailed: "Failed to close database",
+  reldb_ddlFailed: "DDL operation failed",
+  reldb_queryFailed: "Query failed",
+  reldb_duplicateEntry: "Record already exists",
+  reldb_batchFailed: "Batch execute failed",
+  reldb_postgresTxFailed: "Transaction failed",
   reldb_postgresOnlyPostgresql: "PostgreSQL Provider only supports postgresql type",
-  reldb_postgresConnectionFailed: "Failed to connect to PostgreSQL: {error}",
+  reldb_postgresConnectionFailed: "Failed to connect to PostgreSQL",
   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_sqliteBatchFailed: "Batch execute failed: {error}",
+  reldb_sqliteConnectionFailed: "Failed to connect to SQLite",
+  reldb_sqliteTxFailed: "Transaction failed",
+  reldb_sqliteBatchFailed: "Batch execute failed",
   reldb_mysqlOnlyMysql: "MySQL Provider only supports mysql type",
-  reldb_mysqlConnectionFailed: "Failed to connect to MySQL: {error}",
-  reldb_mysqlTxFailed: "Transaction failed: {error}",
+  reldb_mysqlConnectionFailed: "Failed to connect to MySQL",
+  reldb_mysqlTxFailed: "Transaction failed",
+  reldb_mysqlPoolQueueFull: "MySQL connection acquisition queue is full",
+  reldb_mysqlPoolAcquireTimeout: "MySQL connection acquisition deadline exceeded",
+  reldb_mysqlPoolReleaseFailed: "MySQL connection release failed; close the database before retrying",
+  reldb_mysqlTlsDnsRequired: "MySQL hostname verification requires a DNS hostname matching the certificate; the current driver cannot verify an IP address identity",
   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}"
+  reldb_configError: "Database config validation failed",
+  reldb_txFailed: "Transaction failed",
+  reldb_sharedBackendRequired: "Production mode requires a shared backend; local files and memory backends are for development or explicit end-to-end tests.",
+  reldb_jsonPatchObjectRequired: "JSON merge patch must be an object"
+};
+
+// messages/ja-JP.json
+var ja_JP_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  reldb_notInitialized: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u304C\u521D\u671F\u5316\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u5148\u306Bdb.init()\u3092\u547C\u3073\u51FA\u3057\u3066\u304F\u3060\u3055\u3044",
+  reldb_initFailed: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u521D\u671F\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_closeFailed: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u7D42\u4E86\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_ddlFailed: "DDL\u64CD\u4F5C\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_queryFailed: "\u30AF\u30A8\u30EA\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_duplicateEntry: "\u30EC\u30B3\u30FC\u30C9\u306F\u65E2\u306B\u5B58\u5728\u3057\u307E\u3059",
+  reldb_batchFailed: "\u30D0\u30C3\u30C1\u5B9F\u884C\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_postgresTxFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_postgresOnlyPostgresql: "PostgreSQL\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u306Fpostgresql\u578B\u306E\u307F\u306B\u5BFE\u5FDC\u3057\u3066\u3044\u307E\u3059",
+  reldb_postgresConnectionFailed: "PostgreSQL\u3078\u306E\u63A5\u7D9A\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_sqliteOnlySqlite: "SQLite\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u306Fsqlite\u578B\u306E\u307F\u306B\u5BFE\u5FDC\u3057\u3066\u3044\u307E\u3059",
+  reldb_sqliteNeedPath: "SQLite\u306B\u306F\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u30D1\u30B9\uFF08database\u30D5\u30A3\u30FC\u30EB\u30C9\uFF09\u304C\u5FC5\u8981\u3067\u3059",
+  reldb_sqliteConnectionFailed: "SQLite\u3078\u306E\u63A5\u7D9A\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_sqliteTxFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_sqliteBatchFailed: "\u30D0\u30C3\u30C1\u5B9F\u884C\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_mysqlOnlyMysql: "MySQL\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u306Fmysql\u578B\u306E\u307F\u306B\u5BFE\u5FDC\u3057\u3066\u3044\u307E\u3059",
+  reldb_mysqlConnectionFailed: "MySQL\u3078\u306E\u63A5\u7D9A\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_mysqlTxFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_mysqlPoolQueueFull: "MySQL \u63A5\u7D9A\u53D6\u5F97\u30AD\u30E5\u30FC\u304C\u6E80\u676F\u3067\u3059",
+  reldb_mysqlPoolAcquireTimeout: "MySQL \u63A5\u7D9A\u53D6\u5F97\u306E\u5F85\u6A5F\u671F\u9650\u3092\u8D85\u904E\u3057\u307E\u3057\u305F",
+  reldb_mysqlPoolReleaseFailed: "MySQL \u63A5\u7D9A\u306E\u89E3\u653E\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002\u518D\u8A66\u884C\u3059\u308B\u524D\u306B\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u3092\u7D42\u4E86\u3057\u3066\u304F\u3060\u3055\u3044",
+  reldb_mysqlTlsDnsRequired: "MySQL \u306E\u30DB\u30B9\u30C8\u540D\u691C\u8A3C\u306B\u306F\u8A3C\u660E\u66F8\u3068\u4E00\u81F4\u3059\u308B DNS \u30DB\u30B9\u30C8\u540D\u304C\u5FC5\u8981\u3067\u3059\u3002\u73FE\u5728\u306E\u30C9\u30E9\u30A4\u30D0\u30FC\u3067\u306F IP \u30A2\u30C9\u30EC\u30B9\u306E\u8B58\u5225\u60C5\u5831\u3092\u691C\u8A3C\u3067\u304D\u307E\u305B\u3093",
+  reldb_crudEmptyPayload: "CRUD\u30DA\u30A4\u30ED\u30FC\u30C9\u304C\u7A7A\u3067\u3059\u3002\u30C7\u30FC\u30BF\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044",
+  reldb_crudNoValidColumns: "CRUD\u30DA\u30A4\u30ED\u30FC\u30C9\u306B\u6709\u52B9\u306A\u5217\u304C\u3042\u308A\u307E\u305B\u3093",
+  reldb_crudRecordNotFound: "\u30EC\u30B3\u30FC\u30C9\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093: {id}",
+  reldb_invalidIdentifier: "SQL\u8B58\u5225\u5B50\u304C\u7121\u52B9\u3067\u3059: {name}\uFF08\u82F1\u6570\u5B57\u3068\u30A2\u30F3\u30C0\u30FC\u30B9\u30B3\u30A2\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059\uFF09",
+  reldb_configError: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u8A2D\u5B9A\u306E\u691C\u8A3C\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_txFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reldb_sharedBackendRequired: "\u672C\u756A\u74B0\u5883\u306B\u306F\u5171\u6709\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u304C\u5FC5\u8981\u3067\u3059\u3002\u30ED\u30FC\u30AB\u30EB\u30D5\u30A1\u30A4\u30EB\u3068\u30E1\u30E2\u30EA\u30FC\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u306F\u958B\u767A\u74B0\u5883\u307E\u305F\u306F\u660E\u793A\u7684\u306A E2E \u30C6\u30B9\u30C8\u3067\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059\u3002",
+  reldb_jsonPatchObjectRequired: "JSON \u30DE\u30FC\u30B8\u30D1\u30C3\u30C1\u306F\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044"
 };
 
 // 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_ddlFailed: "DDL \u64CD\u4F5C\u5931\u8D25: {error}",
-  reldb_queryFailed: "\u67E5\u8BE2\u5931\u8D25: {error}",
-  reldb_batchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25: {error}",
-  reldb_postgresTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25: {error}",
+  reldb_initFailed: "\u521D\u59CB\u5316\u6570\u636E\u5E93\u5931\u8D25",
+  reldb_closeFailed: "\u5173\u95ED\u6570\u636E\u5E93\u5931\u8D25",
+  reldb_ddlFailed: "DDL \u64CD\u4F5C\u5931\u8D25",
+  reldb_queryFailed: "\u67E5\u8BE2\u5931\u8D25",
+  reldb_duplicateEntry: "\u8BB0\u5F55\u5DF2\u5B58\u5728",
+  reldb_batchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25",
+  reldb_postgresTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25",
   reldb_postgresOnlyPostgresql: "PostgreSQL Provider \u4EC5\u652F\u6301 postgresql \u7C7B\u578B",
-  reldb_postgresConnectionFailed: "\u8FDE\u63A5 PostgreSQL \u5931\u8D25: {error}",
+  reldb_postgresConnectionFailed: "\u8FDE\u63A5 PostgreSQL \u5931\u8D25",
   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_sqliteBatchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25: {error}",
+  reldb_sqliteConnectionFailed: "\u8FDE\u63A5 SQLite \u5931\u8D25",
+  reldb_sqliteTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25",
+  reldb_sqliteBatchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25",
   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_mysqlConnectionFailed: "\u8FDE\u63A5 MySQL \u5931\u8D25",
+  reldb_mysqlTxFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25",
+  reldb_mysqlPoolQueueFull: "MySQL \u8FDE\u63A5\u83B7\u53D6\u7B49\u5F85\u961F\u5217\u5DF2\u6EE1",
+  reldb_mysqlPoolAcquireTimeout: "MySQL \u8FDE\u63A5\u83B7\u53D6\u5DF2\u8D85\u8FC7\u622A\u6B62\u671F\u9650",
+  reldb_mysqlPoolReleaseFailed: "MySQL \u8FDE\u63A5\u5F52\u8FD8\u5931\u8D25\uFF0C\u8BF7\u5173\u95ED\u6570\u636E\u5E93\u540E\u91CD\u8BD5",
+  reldb_mysqlTlsDnsRequired: "MySQL \u5F53\u524D\u9A71\u52A8\u7684\u4E3B\u673A\u8EAB\u4EFD\u9A8C\u8BC1\u8981\u6C42\u4F7F\u7528\u4E0E\u8BC1\u4E66\u5339\u914D\u7684 DNS \u4E3B\u673A\u540D\uFF0C\u4E0D\u80FD\u9A8C\u8BC1 IP \u5730\u5740\u8EAB\u4EFD",
   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}"
+  reldb_configError: "\u6570\u636E\u5E93\u914D\u7F6E\u6821\u9A8C\u5931\u8D25",
+  reldb_txFailed: "\u4E8B\u52A1\u6267\u884C\u5931\u8D25",
+  reldb_sharedBackendRequired: "\u751F\u4EA7\u6A21\u5F0F\u9700\u8981\u8DE8\u8282\u70B9\u5171\u4EAB\u540E\u7AEF\uFF1B\u672C\u673A\u6587\u4EF6\u6216\u5185\u5B58\u540E\u7AEF\u4EC5\u7528\u4E8E\u5F00\u53D1\u548C\u663E\u5F0F\u7AEF\u5230\u7AEF\u6D4B\u8BD5\u3002",
+  reldb_jsonPatchObjectRequired: "JSON \u5408\u5E76\u8865\u4E01\u5FC5\u987B\u662F\u5BF9\u8C61"
 };
 
 // src/reldb-i18n.ts
 var reldbM = core.i18n.createMessageGetter({
   "zh-CN": zh_CN_default,
-  "en-US": en_US_default
+  "en-US": en_US_default,
+  "ja-JP": ja_JP_default
 });
 var ReldbErrorInfo = {
   // ─── 通用 001-009 ───
@@ -399,12 +376,13 @@ var BaseReldbCrudRepository = class {
    */
   mapRow(row) {
     const result = {};
+    const resultRecord = result;
     for (const field of this.fields) {
       if (!field.select) {
         continue;
       }
       const value = this.fromDbValue(row[field.columnName], field.def);
-      result[field.fieldName] = value;
+      resultRecord[field.fieldName] = value;
     }
     return result;
   }
@@ -477,7 +455,11 @@ var BaseReldbCrudRepository = class {
     return payload;
   }
   /**
-   * 等待初始化完成
+   * 等待初始化完成（自动建表等）
+   *
+   * 内置 CRUD 方法均已在执行前调用；自定义方法若通过 `this.sql()` 直接执行原始
+   * SQL（尤其是写操作或在事务中），应先 `await this.ensureReady()` 以避免表尚未
+   * 建好时（例如刚 dropTable 后、或后端建表较慢时）产生「表不存在」的竞态失败。
    *
    * @returns 初始化结果
    */
@@ -496,6 +478,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async create(data, tx) {
     const ready = await this.ensureReady();
@@ -516,6 +509,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async createMany(items, tx) {
     const ready = await this.ensureReady();
@@ -550,6 +554,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async createOrUpdate(data, tx) {
     const ready = await this.ensureReady();
@@ -592,6 +607,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async findById(id, tx) {
     const ready = await this.ensureReady();
@@ -608,6 +634,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async getById(id, tx) {
     const ready = await this.ensureReady();
@@ -622,6 +659,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async findAll(options, tx) {
     const ready = await this.ensureReady();
@@ -636,6 +684,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async findPage(options, tx) {
     const ready = await this.ensureReady();
@@ -653,6 +712,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async updateById(id, data, tx) {
     const ready = await this.ensureReady();
@@ -671,6 +741,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async deleteById(id, tx) {
     const ready = await this.ensureReady();
@@ -685,6 +766,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async count(options, tx) {
     const ready = await this.ensureReady();
@@ -699,6 +791,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async exists(options, tx) {
     const ready = await this.ensureReady();
@@ -713,6 +816,17 @@ var BaseReldbCrudRepository = class {
    * @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
+   * ```
    */
   async existsById(id, tx) {
     const ready = await this.ensureReady();
@@ -724,6 +838,7 @@ var BaseReldbCrudRepository = class {
 };
 
 // src/reldb-json.ts
+var JSON_PATH_OBJECT_SEGMENT_REGEX = /^([^.[]+)/;
 function parseJsonPath(path) {
   let remaining = path.startsWith("$") ? path.slice(1) : path;
   const segments = [];
@@ -742,7 +857,7 @@ function parseJsonPath(path) {
       remaining = remaining.slice(1);
       if (remaining.startsWith("["))
         continue;
-      const match = remaining.match(/^([^.[]+)/);
+      const match = remaining.match(JSON_PATH_OBJECT_SEGMENT_REGEX);
       if (match) {
         segments.push(match[1]);
         remaining = remaining.slice(match[1].length);
@@ -787,6 +902,46 @@ function createSqliteJsonOps() {
     }
   };
 }
+function buildPostgresMergePatch(column, patch) {
+  const normalized = JSON.parse(JSON.stringify(patch));
+  if (!normalized || typeof normalized !== "object" || Array.isArray(normalized))
+    throw new TypeError(reldbM("reldb_jsonPatchObjectRequired"));
+  const steps = [];
+  const pending = Object.entries(normalized).reverse().map(([key, value]) => ({ path: [key], value }));
+  while (pending.length > 0) {
+    const entry = pending.pop();
+    const object = entry.value !== null && typeof entry.value === "object" && !Array.isArray(entry.value);
+    steps.push({ path: entry.path, value: object ? {} : entry.value, object });
+    if (object) {
+      for (const [key, value] of Object.entries(entry.value).reverse())
+        pending.push({ path: [...entry.path, key], value });
+    }
+  }
+  return {
+    sql: `(WITH RECURSIVE
+      patch_steps AS (
+        SELECT ordinality AS step,
+          ARRAY(SELECT jsonb_array_elements_text(item->'path')) AS path,
+          item->'value' AS value, (item->>'object')::boolean AS object
+        FROM jsonb_array_elements(?::jsonb) WITH ORDINALITY AS input(item, ordinality)
+      ),
+      merged(step, document) AS (
+        SELECT 0::bigint, CASE WHEN jsonb_typeof(${column}) = 'object' THEN ${column} ELSE '{}'::jsonb END
+        UNION ALL
+        SELECT patch_steps.step,
+          CASE
+            WHEN patch_steps.object THEN jsonb_set(merged.document, patch_steps.path,
+              CASE WHEN jsonb_typeof(merged.document #> patch_steps.path) = 'object'
+                THEN merged.document #> patch_steps.path ELSE '{}'::jsonb END, true)
+            WHEN patch_steps.value = 'null'::jsonb THEN merged.document #- patch_steps.path
+            ELSE jsonb_set(merged.document, patch_steps.path, patch_steps.value, true)
+          END
+        FROM merged JOIN patch_steps ON patch_steps.step = merged.step + 1
+      )
+      SELECT document FROM merged ORDER BY step DESC LIMIT 1)`,
+    params: [JSON.stringify(steps)]
+  };
+}
 function createPostgresJsonOps() {
   return {
     extract(column, path) {
@@ -818,10 +973,7 @@ function createPostgresJsonOps() {
       };
     },
     merge(column, patch) {
-      return {
-        sql: `${column} || ?::jsonb`,
-        params: [JSON.stringify(patch)]
-      };
+      return buildPostgresMergePatch(column, patch);
     }
   };
 }
@@ -956,6 +1108,7 @@ function escapeSqlString(value) {
 
 // src/reldb-crud-kernel.ts
 var logger = core.logger.child({ module: "reldb", scope: "crud-kernel" });
+var ORDER_BY_SEGMENT_REGEX = /^(\w+)(?:\s+(ASC|DESC))?$/i;
 function buildSelectColumns(select) {
   if (!select || select.length === 0) {
     return "*";
@@ -1024,7 +1177,7 @@ function createCrud(ops, config) {
     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);
+      const match = part.match(ORDER_BY_SEGMENT_REGEX);
       if (!match) {
         logger.debug("Skipped invalid orderBy segment", { table, segment: part });
         continue;
@@ -1412,15 +1565,87 @@ function createTxWrap(beginTx) {
 }
 
 // src/providers/reldb-provider-base.ts
+function summarizeOperationPayload(payload) {
+  try {
+    if (!payload || typeof payload !== "object")
+      return {};
+    const fields = payload;
+    return {
+      ...typeof fields.sql === "string" ? { sqlLength: fields.sql.length } : {},
+      ...Array.isArray(fields.params) ? { parameterCount: fields.params.length } : {},
+      ...Array.isArray(fields.statements) ? { statementCount: fields.statements.length } : {},
+      ...fields.columns && typeof fields.columns === "object" ? { columnCount: Object.keys(fields.columns).length } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function logReldbOperation(ctx, category, operation, payload) {
+  const config = ctx.operationLog?.();
+  if (!config?.[category]) {
+    return;
+  }
+  ctx.logger[config.level]("RelDB operation executed", {
+    category,
+    operation,
+    payload: config.maxLength <= 0 ? "" : JSON.stringify(summarizeOperationPayload(payload)).slice(0, config.maxLength)
+  });
+}
 async function wrapOp(ctx, fn, errorDef, errorLabel, errorMeta) {
   if (!ctx.isConnected()) {
     return err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized"));
   }
+  const failed = (error, original) => {
+    let definition = original ?? errorDef;
+    const traceId = core.context.get().traceId ?? core.context.get().requestId ?? original?.traceId ?? core.id.uuid();
+    const fields = error && typeof error === "object" ? error : {};
+    if (definition.code === HaiReldbError.QUERY_FAILED.code && (["23505", "ER_DUP_ENTRY", "SQLITE_CONSTRAINT_UNIQUE", "SQLITE_CONSTRAINT_PRIMARYKEY"].includes(String(fields.code)) || fields.errno === 1062))
+      definition = HaiReldbError.DUPLICATE_ENTRY;
+    const secrets = /* @__PURE__ */ new Set();
+    const seen = /* @__PURE__ */ new WeakSet();
+    const collect = (value) => {
+      if (typeof value === "string" && value) {
+        secrets.add(value);
+      } else if (typeof value === "number" || typeof value === "bigint") {
+        secrets.add(String(value));
+      } else if (value && typeof value === "object" && !seen.has(value)) {
+        seen.add(value);
+        Object.values(value).forEach(collect);
+      }
+    };
+    collect(errorMeta?.params);
+    const payloads = [errorMeta, ...Array.isArray(errorMeta?.statements) ? errorMeta.statements : []];
+    for (const payload of payloads) {
+      collect(payload?.params);
+      for (const match of (typeof payload?.sql === "string" ? payload.sql : "").matchAll(/'((?:''|[^'])*)'/g))
+        secrets.add(match[1].replaceAll("''", "'"));
+    }
+    const diagnostic = {};
+    for (const key2 of ["name", "message", "stack", "code", "errno", "sqlState", "detail", "hint", "constraint", "schema", "routine", "severity", "table", "column"]) {
+      const value = error instanceof Error && key2 === "message" ? error.message : error instanceof Error && key2 === "stack" ? error.stack : fields[key2];
+      if (typeof value === "string") {
+        if (["code", "sqlState", "schema", "routine", "severity", "constraint", "table", "column"].includes(key2)) {
+          diagnostic[key2] = core.sanitize.sanitizeText(value);
+        } else {
+          const frames = key2 === "stack" ? value.search(/^\s+at\s/m) : -1;
+          const body = frames < 0 ? value : value.slice(0, frames);
+          diagnostic[key2] = core.sanitize.sanitizeText(body, [...secrets]).replace(/'(?:''|[^'])*'/g, "'[REDACTED]'") + (frames < 0 ? "" : core.sanitize.sanitizeText(value.slice(frames)));
+        }
+      } else if (typeof value === "number") {
+        diagnostic[key2] = value;
+      }
+    }
+    if (!Object.keys(diagnostic).length)
+      diagnostic.message = core.sanitize.sanitizeText(String(error), [...secrets]);
+    ctx.logger.error(errorLabel, { ...summarizeOperationPayload(errorMeta), table: errorMeta?.tableName, column: errorMeta?.columnName, errorCode: definition.code, traceId, error: diagnostic });
+    const key = definition.code === HaiReldbError.DDL_FAILED.code ? "reldb_ddlFailed" : definition.code === HaiReldbError.TRANSACTION_FAILED.code ? "reldb_txFailed" : "reldb_queryFailed";
+    return err({ ...definition, traceId, message: definition.code === HaiReldbError.DUPLICATE_ENTRY.code ? reldbM("reldb_duplicateEntry") : original ? core.sanitize.sanitizeText(original.message, [...secrets]) : reldbM(key), cause: diagnostic });
+  };
   try {
-    return await fn();
+    const result = await fn();
+    return result.success ? result : failed(result.error.cause ?? result.error, result.error);
   } catch (error) {
-    ctx.logger.error(errorLabel, { ...errorMeta, error });
-    return err(errorDef, reldbM("reldb_queryFailed", { params: { error: String(error) } }), error);
+    return failed(error);
   }
 }
 function createBaseDdlOps(ctx, raw) {
@@ -1432,12 +1657,14 @@ function createBaseDdlOps(ctx, raw) {
       const v2 = validateIdentifiers(Object.keys(columns));
       if (!v2.success)
         return Promise.resolve(v2);
+      logReldbOperation(ctx, "write", "ddl.createTable", { tableName, columns, ifNotExists });
       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);
+      logReldbOperation(ctx, "write", "ddl.dropTable", { tableName, ifExists });
       return wrapOp(ctx, () => raw.dropTable(tableName, ifExists), HaiReldbError.DDL_FAILED, "DDL: dropTable failed", { tableName });
     },
     addColumn(tableName, columnName, columnDef) {
@@ -1447,6 +1674,7 @@ function createBaseDdlOps(ctx, raw) {
       const v2 = validateIdentifier(columnName);
       if (!v2.success)
         return Promise.resolve(v2);
+      logReldbOperation(ctx, "write", "ddl.addColumn", { tableName, columnName, columnDef });
       return wrapOp(ctx, () => raw.addColumn(tableName, columnName, columnDef), HaiReldbError.DDL_FAILED, "DDL: addColumn failed", { tableName, columnName });
     },
     dropColumn(tableName, columnName) {
@@ -1456,6 +1684,7 @@ function createBaseDdlOps(ctx, raw) {
       const v2 = validateIdentifier(columnName);
       if (!v2.success)
         return Promise.resolve(v2);
+      logReldbOperation(ctx, "write", "ddl.dropColumn", { tableName, columnName });
       return wrapOp(ctx, () => raw.dropColumn(tableName, columnName), HaiReldbError.DDL_FAILED, "DDL: dropColumn failed", { tableName, columnName });
     },
     renameTable(oldName, newName) {
@@ -1465,6 +1694,7 @@ function createBaseDdlOps(ctx, raw) {
       const v2 = validateIdentifier(newName);
       if (!v2.success)
         return Promise.resolve(v2);
+      logReldbOperation(ctx, "write", "ddl.renameTable", { oldName, newName });
       return wrapOp(ctx, () => raw.renameTable(oldName, newName), HaiReldbError.DDL_FAILED, "DDL: renameTable failed", { oldName, newName });
     },
     createIndex(tableName, indexName, indexDef) {
@@ -1477,30 +1707,66 @@ function createBaseDdlOps(ctx, raw) {
       const v3 = validateIdentifiers(indexDef.columns);
       if (!v3.success)
         return Promise.resolve(v3);
+      logReldbOperation(ctx, "write", "ddl.createIndex", { tableName, indexName, indexDef });
       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);
+      logReldbOperation(ctx, "write", "ddl.dropIndex", { indexName, ifExists });
       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");
+      logReldbOperation(ctx, "write", "ddl.raw", { sql });
+      return wrapOp(ctx, () => raw.raw(sql), HaiReldbError.DDL_FAILED, "DDL: raw failed", { sql });
     }
   };
 }
 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")
+    query: (sql, params) => {
+      logReldbOperation(ctx, "read", "query", { sql, params });
+      return wrapOp(ctx, () => raw.query(sql, params), HaiReldbError.QUERY_FAILED, "DML: query failed", { sql, params });
+    },
+    get: (sql, params) => {
+      logReldbOperation(ctx, "read", "get", { sql, params });
+      return wrapOp(ctx, () => raw.get(sql, params), HaiReldbError.QUERY_FAILED, "DML: get failed", { sql, params });
+    },
+    execute: (sql, params) => {
+      logReldbOperation(ctx, "write", "execute", { sql, params });
+      return wrapOp(ctx, () => raw.execute(sql, params), HaiReldbError.QUERY_FAILED, "DML: execute failed", { sql, params });
+    },
+    batch: (statements) => {
+      logReldbOperation(ctx, "write", "batch", { count: statements.length, statements });
+      return wrapOp(ctx, () => raw.batch(statements), HaiReldbError.QUERY_FAILED, "DML: batch failed", { statements });
+    },
+    queryPage: (options) => {
+      logReldbOperation(ctx, "read", "queryPage", options);
+      return wrapOp(ctx, () => raw.queryPage(options), HaiReldbError.QUERY_FAILED, "DML: queryPage failed", { ...options });
+    }
   };
 }
 function createBaseTxManager(ctx, beginTx) {
-  const begin = () => wrapOp(ctx, beginTx, HaiReldbError.TRANSACTION_FAILED, "TX: begin failed");
+  const begin = async () => {
+    logReldbOperation(ctx, "write", "tx.begin", {});
+    const result = await wrapOp(ctx, beginTx, HaiReldbError.TRANSACTION_FAILED, "TX: begin failed");
+    if (!result.success) {
+      return result;
+    }
+    const tx = result.data;
+    return ok({
+      ...tx,
+      commit: async () => {
+        logReldbOperation(ctx, "write", "tx.commit", {});
+        return tx.commit();
+      },
+      rollback: async () => {
+        logReldbOperation(ctx, "write", "tx.rollback", {});
+        return tx.rollback();
+      }
+    });
+  };
   return {
     begin,
     wrap: createTxWrap(begin)
@@ -1588,9 +1854,149 @@ function buildDefaultDropIndexSql(quoteId, indexName, ifExists) {
 var logger2 = core.logger.child({ module: "reldb", scope: "mysql" });
 function createMysqlProvider() {
   let pool = null;
+  let ready = false;
+  let closing = null;
+  let poolConfig = null;
+  let activeSlots = 0;
+  let slotsDrained = Promise.resolve();
+  let resolveSlots = null;
+  const waiters = [];
+  let currentConfig2 = null;
+  function releaseSlot() {
+    activeSlots--;
+    if (ready && poolConfig) {
+      const maximum = poolConfig.max;
+      while (waiters.length > 0) {
+        if (activeSlots >= maximum)
+          break;
+        waiters.shift().start();
+      }
+    }
+    if (activeSlots === 0) {
+      resolveSlots?.();
+      resolveSlots = null;
+    }
+  }
+  function acquireConnection() {
+    const owned = pool;
+    const limits = poolConfig;
+    if (!ready || !owned || !limits)
+      return Promise.resolve(err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized")));
+    if (activeSlots >= limits.max && waiters.length >= limits.queueLimit)
+      return Promise.resolve(err(HaiReldbError.POOL_EXHAUSTED, reldbM("reldb_mysqlPoolQueueFull")));
+    const deadline = performance$1.now() + limits.acquireTimeout;
+    return new Promise((resolve) => {
+      let completed = false;
+      let timer;
+      const timeoutResult = () => err(HaiReldbError.TIMEOUT, reldbM("reldb_mysqlPoolAcquireTimeout"));
+      const finish = (result) => {
+        if (completed)
+          return;
+        completed = true;
+        clearTimeout(timer);
+        resolve(result);
+      };
+      const waiter = {
+        cancel: () => finish(err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized"))),
+        start: () => {
+          if (!ready || performance$1.now() >= deadline) {
+            finish(ready ? timeoutResult() : err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized")));
+            return;
+          }
+          if (activeSlots++ === 0)
+            slotsDrained = new Promise((resolve2) => {
+              resolveSlots = resolve2;
+            });
+          void Promise.resolve().then(() => owned.getConnection()).then((connection) => {
+            if (completed || !ready || performance$1.now() >= deadline) {
+              try {
+                connection.release();
+              } finally {
+                releaseSlot();
+              }
+              finish(ready ? timeoutResult() : err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized")));
+              return;
+            }
+            let released = false;
+            finish(ok({
+              connection,
+              deadline,
+              release: () => {
+                if (released)
+                  return;
+                released = true;
+                try {
+                  connection.release();
+                } finally {
+                  releaseSlot();
+                }
+              }
+            }));
+          }, (error) => {
+            releaseSlot();
+            finish(err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_mysqlConnectionFailed", { params: { error: String(error) } }), error));
+          }).catch((error) => {
+            ready = false;
+            finish(err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_mysqlConnectionFailed", { params: { error: reldbM("reldb_mysqlPoolReleaseFailed") } }), error));
+            logger2.warn("MySQL connection release failed; pool requires cleanup");
+          });
+        }
+      };
+      timer = setTimeout(() => {
+        const index = waiters.indexOf(waiter);
+        if (index >= 0)
+          waiters.splice(index, 1);
+        finish(timeoutResult());
+      }, limits.acquireTimeout);
+      if (activeSlots < limits.max)
+        waiter.start();
+      else
+        waiters.push(waiter);
+    });
+  }
+  async function withConnection(fn) {
+    const acquired = await acquireConnection();
+    if (!acquired.success)
+      return acquired;
+    try {
+      if (!ready)
+        return err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized"));
+      if (performance$1.now() >= acquired.data.deadline)
+        return err(HaiReldbError.TIMEOUT, reldbM("reldb_mysqlPoolAcquireTimeout"));
+      return await fn(acquired.data.connection);
+    } finally {
+      acquired.data.release();
+    }
+  }
+  function closeResource() {
+    ready = false;
+    currentConfig2 = null;
+    for (const waiter of waiters.splice(0))
+      waiter.cancel();
+    if (closing)
+      return closing;
+    const owned = pool;
+    if (!owned)
+      return Promise.resolve(ok(void 0));
+    closing = (async () => {
+      try {
+        await slotsDrained;
+        await owned.end();
+        pool = null;
+        poolConfig = null;
+        return ok(void 0);
+      } catch (error) {
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_mysqlConnectionFailed", { params: { error: String(error) } }), error);
+      }
+    })().finally(() => {
+      closing = null;
+    });
+    return closing;
+  }
   const ctx = {
-    isConnected: () => pool !== null,
-    logger: logger2
+    isConnected: () => ready && pool !== null,
+    logger: logger2,
+    operationLog: () => currentConfig2?.operationLog
   };
   function mysqlQuoteId(name) {
     return `\`${name}\``;
@@ -1598,17 +2004,15 @@ function createMysqlProvider() {
   function mysqlTxErrorMessage(detail) {
     return reldbM("reldb_mysqlTxFailed", { params: { error: detail } });
   }
-  async function findIndexTableName(queryFn, indexName) {
-    try {
-      const [rows] = await queryFn(
+  async function findIndexTableName(indexName) {
+    return withConnection(async (connection) => {
+      const [rows] = await connection.query(
         "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) {
@@ -1616,6 +2020,8 @@ function createMysqlProvider() {
         return "VARCHAR(255)";
       case "INTEGER":
         return def.autoIncrement ? "BIGINT" : "INT";
+      case "BIGINT":
+        return "BIGINT";
       case "REAL":
         return "DOUBLE";
       case "BLOB":
@@ -1685,39 +2091,39 @@ function createMysqlProvider() {
     const ifNotExistsClause = ifNotExists ? "IF NOT EXISTS " : "";
     return `CREATE TABLE ${ifNotExistsClause}${quotedTable} (${columnDefs.join(", ")}) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`;
   }
+  function executeDdl(sql) {
+    return withConnection(async (connection) => {
+      await connection.query(sql);
+      return ok(void 0);
+    });
+  }
   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);
+      return executeDdl(sql);
     },
     async dropTable(name, ifExists) {
       const ifExistsClause = ifExists ? "IF EXISTS " : "";
-      await pool.query(`DROP TABLE ${ifExistsClause}${mysqlQuoteId(name)}`);
-      return ok(void 0);
+      return executeDdl(`DROP TABLE ${ifExistsClause}${mysqlQuoteId(name)}`);
     },
     async addColumn(table, column, def) {
       const colSql = mysqlBuildColumnSql(column, def);
-      await pool.query(`ALTER TABLE ${mysqlQuoteId(table)} ADD COLUMN ${colSql}`);
-      return ok(void 0);
+      return executeDdl(`ALTER TABLE ${mysqlQuoteId(table)} ADD COLUMN ${colSql}`);
     },
     async dropColumn(table, column) {
-      await pool.query(`ALTER TABLE ${mysqlQuoteId(table)} DROP COLUMN ${mysqlQuoteId(column)}`);
-      return ok(void 0);
+      return executeDdl(`ALTER TABLE ${mysqlQuoteId(table)} DROP COLUMN ${mysqlQuoteId(column)}`);
     },
     async renameTable(oldName, newName) {
-      await pool.query(`RENAME TABLE ${mysqlQuoteId(oldName)} TO ${mysqlQuoteId(newName)}`);
-      return ok(void 0);
+      return executeDdl(`RENAME TABLE ${mysqlQuoteId(oldName)} TO ${mysqlQuoteId(newName)}`);
     },
     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);
+      return executeDdl(`CREATE ${uniqueClause}INDEX ${mysqlQuoteId(index)} ON ${mysqlQuoteId(table)} (${columns})`);
     },
     async dropIndex(index, ifExists) {
-      const tableResult = await findIndexTableName((s, v) => pool.query(s, v), index);
+      const tableResult = await findIndexTableName(index);
       if (!tableResult.success)
         return tableResult;
       if (!tableResult.data) {
@@ -1725,58 +2131,58 @@ function createMysqlProvider() {
           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);
+      return executeDdl(`DROP INDEX ${mysqlQuoteId(index)} ON ${mysqlQuoteId(tableResult.data)}`);
     },
     async raw(sql) {
-      await pool.query(sql);
-      return ok(void 0);
+      return executeDdl(sql);
     }
   };
   const rawDml = {
     async query(sql, params) {
-      const [rows] = await pool.query(sql, params);
-      return ok(rows);
+      return withConnection(async (connection) => {
+        const [rows] = await connection.query(sql, params);
+        return ok(rows);
+      });
     },
     async get(sql, params) {
-      const [rows] = await pool.query(sql, params);
-      return ok(rows[0] ?? null);
+      return withConnection(async (connection) => {
+        const [rows] = await connection.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 });
+      return withConnection(async (connection) => {
+        const [result] = await connection.execute({ sql, values: 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) {
+      return withConnection(async (connection) => {
+        try {
+          await connection.beginTransaction();
+          for (const { sql: s, params } of statements) {
+            await connection.execute({ sql: s, values: params });
+          }
+          await connection.commit();
+          return ok(void 0);
+        } catch (error) {
           await connection.rollback().catch(() => {
           });
+          return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_batchFailed", { params: { error: String(error) } }), error);
         }
-        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);
+      return withConnection(async (connection) => {
+        const result = await queryPageAsync(
+          async (sql, params) => {
+            const [rows] = await connection.query(sql, params);
+            return rows;
+          },
+          options
+        );
+        return ok(result);
+      });
     }
   };
   function createMysqlTxDmlOps(conn) {
@@ -1790,12 +2196,12 @@ function createMysqlProvider() {
         return ok(rows[0] ?? null);
       },
       async execute(sql, params) {
-        const [result] = await conn.execute(sql, params);
+        const [result] = await conn.execute({ sql, values: params });
         return ok({ changes: result.affectedRows, lastInsertRowid: result.insertId });
       },
       async batch(statements) {
         for (const { sql: s, params } of statements) {
-          await conn.execute(s, params);
+          await conn.execute({ sql: s, values: params });
         }
         return ok(void 0);
       },
@@ -1812,25 +2218,36 @@ function createMysqlProvider() {
     };
   }
   async function beginTx() {
-    let connection = null;
+    const acquired = await acquireConnection();
+    if (!acquired.success)
+      return acquired;
+    let connection = acquired.data.connection;
     try {
-      connection = await pool.getConnection();
+      if (!ready || performance$1.now() >= acquired.data.deadline) {
+        acquired.data.release();
+        return ready ? err(HaiReldbError.TIMEOUT, reldbM("reldb_mysqlPoolAcquireTimeout")) : err(HaiReldbError.NOT_INITIALIZED, reldbM("reldb_notInitialized"));
+      }
       await connection.beginTransaction();
     } catch (error) {
-      if (connection) {
-        connection.release();
-      }
+      acquired.data.release();
       return err(HaiReldbError.TRANSACTION_FAILED, mysqlTxErrorMessage(String(error)), error);
     }
     const txDmlOps = createMysqlTxDmlOps(connection);
-    return ok(createTxHandle(txDmlOps, {
+    const guardedTxDmlOps = createBaseDmlOps({ ...ctx, isConnected: () => connection !== null }, txDmlOps);
+    return ok(createTxHandle(guardedTxDmlOps, {
       commit: async () => {
         await connection.commit();
       },
       rollback: async () => {
         await connection.rollback();
       },
-      release: () => connection.release(),
+      release: () => {
+        try {
+          acquired.data.release();
+        } finally {
+          connection = null;
+        }
+      },
       errorMessage: mysqlTxErrorMessage
     }));
   }
@@ -1840,42 +2257,44 @@ function createMysqlProvider() {
       if (config.type !== "mysql") {
         return err(HaiReldbError.UNSUPPORTED_TYPE, reldbM("reldb_mysqlOnlyMysql"));
       }
+      const previousCleanup = await closeResource();
+      if (!previousCleanup.success)
+        return previousCleanup;
+      const host = config.url ? new URL(config.url).hostname : config.host;
+      if (config.ssl && config.ssl.rejectUnauthorized && config.ssl.verifyIdentity && isIP(host.replace(/^\[|\]$/g, ""))) {
+        return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_mysqlTlsDnsRequired"));
+      }
+      if (config.ssl && (!config.ssl.rejectUnauthorized || !config.ssl.verifyIdentity)) {
+        logger2.warn("MySQL TLS server verification is explicitly disabled", {
+          certificateVerification: config.ssl.rejectUnauthorized,
+          hostnameVerification: config.ssl.rejectUnauthorized && config.ssl.verifyIdentity
+        });
+      }
       try {
-        const mysql = __require("mysql2/promise");
+        const mysql = createRequire(import.meta.url)("mysql2/promise");
+        poolConfig = config.pool ?? MysqlPoolConfigSchema.parse({});
         pool = mysql.createPool({
-          uri: config.url,
-          host: config.host,
-          port: config.port,
-          database: config.database,
-          user: config.user,
-          password: config.password,
+          // mysql2 会用非空的分字段覆盖 URI；URL 模式不能传 schema 默认 host 或冲突字段。
+          ...config.url ? { 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,
+          connectionLimit: poolConfig.max,
+          // 排队由本 Provider 管理，超时项可直接移除；驱动绝不保留取消后的等待者。
+          waitForConnections: false,
+          connectTimeout: poolConfig.acquireTimeout,
           charset: config.mysql?.charset ?? "utf8mb4"
         });
         await pool.query("SELECT 1");
-        logger2.info("Connected to MySQL", { host: config.host, port: config.port, database: config.database });
+        ready = true;
+        currentConfig2 = config;
+        logger2.info("Connected to MySQL", config.url ? { target: core.sanitize.sanitizeUrl(config.url) } : { 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);
+        const cleanup = await closeResource();
+        const result = err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_mysqlConnectionFailed", { params: { error: String(error) } }), error);
+        return cleanup.success || result.success ? result : err({ ...result.error, ext: { cleanupPending: true, cleanupError: cleanup.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);
-    },
+    close: closeResource,
     isConnected: () => ctx.isConnected(),
     ddl: createBaseDdlOps(ctx, rawDdl),
     sql: dmlOps,
@@ -1884,15 +2303,143 @@ function createMysqlProvider() {
   };
 }
 var logger3 = core.logger.child({ module: "reldb", scope: "postgres" });
+var PG_DOLLAR_TAG_REGEX = /^\$([A-Z_]\w*)?\$/i;
 function createPostgresProvider() {
   let pool = null;
+  let ready = false;
+  let closing = null;
+  let activeTransactions = 0;
+  let transactionsDrained = Promise.resolve();
+  let resolveTransactions = null;
+  function retainTransaction() {
+    if (activeTransactions++ === 0)
+      transactionsDrained = new Promise((resolve) => {
+        resolveTransactions = resolve;
+      });
+    return () => {
+      if (--activeTransactions === 0) {
+        resolveTransactions?.();
+        resolveTransactions = null;
+      }
+    };
+  }
+  let currentConfig2 = null;
+  function closeResource() {
+    ready = false;
+    currentConfig2 = null;
+    if (closing)
+      return closing;
+    const owned = pool;
+    if (!owned)
+      return Promise.resolve(ok(void 0));
+    closing = (async () => {
+      try {
+        await transactionsDrained;
+        await owned.end();
+        pool = null;
+        return ok(void 0);
+      } catch (error) {
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_postgresConnectionFailed", { params: { error: String(error) } }), error);
+      }
+    })().finally(() => {
+      closing = null;
+    });
+    return closing;
+  }
   const ctx = {
-    isConnected: () => pool !== null,
-    logger: logger3
+    isConnected: () => ready && pool !== null,
+    logger: logger3,
+    operationLog: () => currentConfig2?.operationLog
   };
   function convertPlaceholders(sql) {
+    let out = "";
     let index = 0;
-    return sql.replace(/\?/g, () => `$${++index}`);
+    let i = 0;
+    const len = sql.length;
+    while (i < len) {
+      const ch = sql[i];
+      if (ch === "'") {
+        out += ch;
+        i++;
+        while (i < len) {
+          const c = sql[i];
+          out += c;
+          i++;
+          if (c === "'") {
+            if (sql[i] === "'") {
+              out += sql[i];
+              i++;
+              continue;
+            }
+            break;
+          }
+        }
+        continue;
+      }
+      if (ch === '"') {
+        out += ch;
+        i++;
+        while (i < len) {
+          const c = sql[i];
+          out += c;
+          i++;
+          if (c === '"') {
+            if (sql[i] === '"') {
+              out += sql[i];
+              i++;
+              continue;
+            }
+            break;
+          }
+        }
+        continue;
+      }
+      if (ch === "$") {
+        const tagMatch = sql.slice(i).match(PG_DOLLAR_TAG_REGEX);
+        if (tagMatch) {
+          const tag = tagMatch[0];
+          const end = sql.indexOf(tag, i + tag.length);
+          if (end === -1) {
+            out += sql.slice(i);
+            i = len;
+          } else {
+            out += sql.slice(i, end + tag.length);
+            i = end + tag.length;
+          }
+          continue;
+        }
+      }
+      if (ch === "-" && sql[i + 1] === "-") {
+        const nl = sql.indexOf("\n", i);
+        if (nl === -1) {
+          out += sql.slice(i);
+          i = len;
+        } else {
+          out += sql.slice(i, nl + 1);
+          i = nl + 1;
+        }
+        continue;
+      }
+      if (ch === "/" && sql[i + 1] === "*") {
+        const endIdx = sql.indexOf("*/", i + 2);
+        if (endIdx === -1) {
+          out += sql.slice(i);
+          i = len;
+        } else {
+          out += sql.slice(i, endIdx + 2);
+          i = endIdx + 2;
+        }
+        continue;
+      }
+      if (ch === "?") {
+        out += `$${++index}`;
+        i++;
+        continue;
+      }
+      out += ch;
+      i++;
+    }
+    return out;
   }
   function pgTxErrorMessage(detail) {
     return reldbM("reldb_postgresTxFailed", { params: { error: detail } });
@@ -1903,6 +2450,8 @@ function createPostgresProvider() {
         return "TEXT";
       case "INTEGER":
         return def.autoIncrement ? "BIGSERIAL" : "INTEGER";
+      case "BIGINT":
+        return "BIGINT";
       case "REAL":
         return "DOUBLE PRECISION";
       case "BLOB":
@@ -1936,11 +2485,23 @@ function createPostgresProvider() {
     const result = await queryFn(convertPlaceholders(sql), params);
     return result.rows;
   }
+  async function executeStatement(sql, params) {
+    try {
+      return await pool.query(sql, params);
+    } catch (error) {
+      const kind = /^\s*CREATE\s+(TABLE|(?:UNIQUE\s+)?INDEX)\s+IF\s+NOT\s+EXISTS\s+/i.exec(sql)?.[1]?.toUpperCase();
+      const single = !sql.trim().replace(/;$/, "").includes(";");
+      const catalogConflict = typeof error === "object" && error !== null && "code" in error && (error.code === "23505" && "schema" in error && error.schema === "pg_catalog" && "constraint" in error && (error.constraint === "pg_class_relname_nsp_index" || kind === "TABLE" && error.constraint === "pg_type_typname_nsp_index") || kind === "TABLE" && error.code === "42710" && "routine" in error && (error.routine === "heap_create_with_catalog" || error.routine === "TypeCreate"));
+      if (!kind || !single || !catalogConflict)
+        throw error;
+      return pool.query(sql, params);
+    }
+  }
   const rawDdl = {
     async createTable(name, columns, ifNotExists = true) {
       const quotedTable = quoteIdentifier(name);
       const sql = buildDefaultCreateTableSql(pgBuildColumnSql, quotedTable, columns, ifNotExists);
-      await pool.query(sql);
+      await executeStatement(sql);
       return ok(void 0);
     },
     async dropTable(name, ifExists) {
@@ -1963,7 +2524,7 @@ function createPostgresProvider() {
     },
     async createIndex(table, index, def) {
       const sql = buildDefaultCreateIndexSql(quoteIdentifier, quoteIdentifier(table), quoteIdentifier(index), def);
-      await pool.query(sql);
+      await executeStatement(sql);
       return ok(void 0);
     },
     async dropIndex(index, ifExists = true) {
@@ -1972,7 +2533,7 @@ function createPostgresProvider() {
       return ok(void 0);
     },
     async raw(sql) {
-      await pool.query(sql);
+      await executeStatement(sql);
       return ok(void 0);
     }
   };
@@ -1986,7 +2547,7 @@ function createPostgresProvider() {
       return ok(rows[0] ?? null);
     },
     async execute(sql, params) {
-      const result = await pool.query(convertPlaceholders(sql), params);
+      const result = await executeStatement(convertPlaceholders(sql), params);
       return ok({ changes: result.rowCount ?? 0 });
     },
     async batch(statements) {
@@ -2057,24 +2618,35 @@ function createPostgresProvider() {
   }
   async function beginTx() {
     let client = null;
+    const releaseOwnership = retainTransaction();
     try {
       client = await pool.connect();
       await client.query("BEGIN");
     } catch (error) {
-      if (client) {
-        client.release();
+      try {
+        client?.release();
+      } finally {
+        releaseOwnership();
       }
       return err(HaiReldbError.TRANSACTION_FAILED, pgTxErrorMessage(String(error)), error);
     }
     const txDmlOps = createPgTxDmlOps(client);
-    return ok(createTxHandle(txDmlOps, {
+    const guardedTxDmlOps = createBaseDmlOps({ ...ctx, isConnected: () => client !== null }, txDmlOps);
+    return ok(createTxHandle(guardedTxDmlOps, {
       commit: async () => {
         await client.query("COMMIT");
       },
       rollback: async () => {
         await client.query("ROLLBACK");
       },
-      release: () => client.release(),
+      release: () => {
+        try {
+          client.release();
+        } finally {
+          client = null;
+          releaseOwnership();
+        }
+      },
       errorMessage: pgTxErrorMessage
     }));
   }
@@ -2084,8 +2656,11 @@ function createPostgresProvider() {
       if (config.type !== "postgresql") {
         return err(HaiReldbError.UNSUPPORTED_TYPE, reldbM("reldb_postgresOnlyPostgresql"));
       }
+      const previousCleanup = await closeResource();
+      if (!previousCleanup.success)
+        return previousCleanup;
       try {
-        const { Pool } = __require("pg");
+        const { Pool } = createRequire(import.meta.url)("pg");
         pool = new Pool({
           connectionString: config.url,
           host: config.host,
@@ -2099,27 +2674,34 @@ function createPostgresProvider() {
           idleTimeoutMillis: config.pool?.idleTimeout,
           connectionTimeoutMillis: config.pool?.acquireTimeout
         });
-        await pool.query("SELECT 1");
+        pool.on("error", (error) => {
+          const code = error && typeof error === "object" && "code" in error && typeof error.code === "string" && /^[A-Z0-9_]{1,32}$/.test(error.code) ? error.code : void 0;
+          logger3.warn("PostgreSQL idle connection error; pool will replace connection", {
+            code,
+            name: error instanceof Error ? "Error" : "UnknownError"
+          });
+        });
+        for (let attempt = 0; ; attempt++) {
+          try {
+            await pool.query("SELECT 1");
+            break;
+          } catch (error) {
+            if (attempt >= 2 || typeof error !== "object" || error === null || !("code" in error) || error.code !== "EAI_AGAIN")
+              throw error;
+            await setTimeout$1(250 * (attempt + 1));
+          }
+        }
+        ready = true;
+        currentConfig2 = config;
         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);
+        const cleanup = await closeResource();
+        const result = err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_postgresConnectionFailed", { params: { error: String(error) } }), error);
+        return cleanup.success || result.success ? result : err({ ...result.error, ext: { cleanupPending: true, cleanupError: cleanup.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);
-    },
+    close: closeResource,
     isConnected: () => ctx.isConnected(),
     ddl: createBaseDdlOps(ctx, rawDdl),
     sql: dmlOps,
@@ -2128,10 +2710,234 @@ function createPostgresProvider() {
   };
 }
 var require2 = createRequire(import.meta.url);
+function createSyncSqliteEngine(options) {
+  const Database = require2("better-sqlite3");
+  const db = new Database(options.database, { readonly: options.readonly });
+  let initialized = false;
+  return {
+    async initialize() {
+      if (!initialized && options.walMode !== false) {
+        const deadline = performance.now() + 5e3;
+        let contention;
+        try {
+          for (; ; ) {
+            if (contention && performance.now() >= deadline)
+              throw contention;
+            db.pragma(`busy_timeout = ${Math.max(1, Math.ceil(deadline - performance.now()))}`);
+            try {
+              db.pragma("journal_mode = WAL");
+              break;
+            } catch (error) {
+              if (!error || typeof error !== "object" || !("code" in error) || typeof error.code !== "string" || !/^SQLITE_BUSY(?:_|$)/.test(error.code) || performance.now() >= deadline) {
+                throw error;
+              }
+              contention = error;
+              await setTimeout$1(Math.min(25, Math.max(1, deadline - performance.now())));
+            }
+          }
+        } finally {
+          db.pragma("busy_timeout = 5000");
+        }
+      }
+      initialized = true;
+    },
+    async all(sql, params) {
+      const stmt = db.prepare(sql);
+      return params ? stmt.all(...params) : stmt.all();
+    },
+    async get(sql, params) {
+      const stmt = db.prepare(sql);
+      return (params ? stmt.get(...params) : stmt.get()) ?? null;
+    },
+    async run(sql, params) {
+      const stmt = db.prepare(sql);
+      const result = params ? stmt.run(...params) : stmt.run();
+      return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+    },
+    async exec(sql) {
+      db.exec(sql);
+    },
+    async batch(statements) {
+      const tx = db.transaction((items) => {
+        for (const item of items) {
+          const stmt = db.prepare(item.sql);
+          if (item.params)
+            stmt.run(...item.params);
+          else stmt.run();
+        }
+      });
+      tx(statements);
+    },
+    async close() {
+      initialized = false;
+      if (db.open) {
+        db.close();
+      }
+    },
+    isOpen: () => initialized && db.open
+  };
+}
+function resolveWorkerUrl() {
+  const candidates = [
+    // 源码 / 测试：引擎与 worker 同目录。
+    new URL("./reldb-sqlite-worker.mjs", import.meta.url),
+    // 打包：引擎被并入 dist/index.js，worker 复制到 dist/providers/sqlite/。
+    new URL("./providers/sqlite/reldb-sqlite-worker.mjs", import.meta.url)
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate))
+      return candidate;
+  }
+  return candidates[0];
+}
+function createWorkerSqliteEngine(options, connectTimeoutMs) {
+  const worker = new Worker(resolveWorkerUrl(), {
+    workerData: { database: options.database, readonly: options.readonly, walMode: options.walMode }
+  });
+  let seq = 0;
+  let open = false;
+  let exited = false;
+  let closing = null;
+  const pending = /* @__PURE__ */ new Map();
+  function rejectAll(error) {
+    for (const entry of pending.values())
+      entry.reject(error);
+    pending.clear();
+  }
+  worker.on("message", (msg) => {
+    if (!("id" in msg))
+      return;
+    const entry = pending.get(msg.id);
+    if (!entry)
+      return;
+    pending.delete(msg.id);
+    if (msg.ok)
+      entry.resolve(msg.result);
+    else entry.reject(new Error(msg.error?.message ?? "sqlite worker error"));
+  });
+  worker.on("error", (error) => {
+    open = false;
+    rejectAll(error instanceof Error ? error : new Error(String(error)));
+  });
+  worker.on("exit", (code) => {
+    exited = true;
+    open = false;
+    if (pending.size > 0)
+      rejectAll(new Error(`sqlite worker exited unexpectedly with code ${code}`));
+  });
+  function initialize() {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        finish(new Error(`sqlite worker init timed out after ${connectTimeoutMs}ms`));
+      }, connectTimeoutMs);
+      function finish(error) {
+        clearTimeout(timer);
+        worker.off("message", onHandshake);
+        worker.off("error", onError);
+        worker.off("exit", onExit);
+        if (error) {
+          reject(error);
+        } else {
+          open = true;
+          resolve();
+        }
+      }
+      function onError(error) {
+        finish(error);
+      }
+      function onExit(code) {
+        finish(new Error(`sqlite worker exited before ready with code ${code}`));
+      }
+      function onHandshake(msg) {
+        if (msg?.type === "ready") {
+          finish();
+        } else if (msg?.type === "init-error") {
+          finish(new Error(msg.error?.message ?? "sqlite worker init failed"));
+        }
+      }
+      worker.on("message", onHandshake);
+      worker.once("error", onError);
+      worker.once("exit", onExit);
+      if (exited)
+        finish(new Error("sqlite worker exited before initialization"));
+    });
+  }
+  function post(op, payload) {
+    if (!open)
+      return Promise.reject(new Error("sqlite worker is not open"));
+    const id = ++seq;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      worker.postMessage({ id, op, ...payload });
+    });
+  }
+  return {
+    initialize,
+    // 边界反序列化：worker 通过结构化克隆回传，行/结果类型在此断言。
+    async all(sql, params) {
+      return await post("all", { sql, params });
+    },
+    async get(sql, params) {
+      return await post("get", { sql, params });
+    },
+    async run(sql, params) {
+      return await post("run", { sql, params });
+    },
+    async exec(sql) {
+      await post("exec", { sql });
+    },
+    async batch(statements) {
+      await post("batch", { statements });
+    },
+    close() {
+      if (closing)
+        return closing;
+      const wasOpen = open;
+      const gracefulClose = wasOpen ? post("close", {}) : Promise.resolve();
+      open = false;
+      closing = (async () => {
+        await gracefulClose.catch(() => void 0);
+        if (!exited)
+          await worker.terminate();
+      })().finally(() => {
+        closing = null;
+      });
+      return closing;
+    },
+    isOpen: () => open
+  };
+}
+
+// src/providers/reldb-provider-sqlite.ts
 var logger4 = core.logger.child({ module: "reldb", scope: "sqlite" });
 function createSqliteProvider() {
-  let database = null;
+  let engine = null;
+  let ready = false;
+  let closing = null;
   let txChain = Promise.resolve();
+  let currentConfig2 = null;
+  function closeResource() {
+    ready = false;
+    currentConfig2 = null;
+    if (closing)
+      return closing;
+    const owned = engine;
+    if (!owned)
+      return Promise.resolve(ok(void 0));
+    closing = (async () => {
+      try {
+        await txChain.catch(() => void 0);
+        await owned.close();
+        engine = null;
+        return ok(void 0);
+      } catch (error) {
+        return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_sqliteConnectionFailed", { params: { error: String(error) } }), error);
+      }
+    })().finally(() => {
+      closing = null;
+    });
+    return closing;
+  }
   const TX_LOCK_TIMEOUT_MS = 3e4;
   async function acquireTxLock() {
     let release;
@@ -2157,8 +2963,9 @@ function createSqliteProvider() {
     return release;
   }
   const ctx = {
-    isConnected: () => database !== null && database.open,
-    logger: logger4
+    isConnected: () => ready && engine !== null && engine.isOpen(),
+    logger: logger4,
+    operationLog: () => currentConfig2?.operationLog
   };
   function mapSqliteType(def) {
     switch (def.type) {
@@ -2166,6 +2973,7 @@ function createSqliteProvider() {
       case "JSON":
         return "TEXT";
       case "INTEGER":
+      case "BIGINT":
       case "BOOLEAN":
         return "INTEGER";
       case "REAL":
@@ -2199,71 +3007,59 @@ function createSqliteProvider() {
     async createTable(name, columns, ifNotExists = true) {
       const quotedTable = quoteIdentifier(name);
       const sql = buildDefaultCreateTableSql(sqliteBuildColumnSql, quotedTable, columns, ifNotExists);
-      database.exec(sql);
+      await engine.exec(sql);
       return ok(void 0);
     },
     async dropTable(name, ifExists) {
       const ifExistsClause = ifExists ? "IF EXISTS " : "";
-      database.exec(`DROP TABLE ${ifExistsClause}${quoteIdentifier(name)}`);
+      await engine.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}`);
+      await engine.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)}`);
+      await engine.exec(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN ${quoteIdentifier(column)}`);
       return ok(void 0);
     },
     async renameTable(oldName, newName) {
-      database.exec(buildDefaultRenameTableSql(quoteIdentifier(oldName), quoteIdentifier(newName)));
+      await engine.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);
+      await engine.exec(sql);
       return ok(void 0);
     },
     async dropIndex(index, ifExists = true) {
       const sql = buildDefaultDropIndexSql(quoteIdentifier, index, ifExists);
-      database.exec(sql);
+      await engine.exec(sql);
       return ok(void 0);
     },
     async raw(sql) {
-      database.exec(sql);
+      await engine.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();
+      const rows = await engine.all(sql, params);
       return ok(rows);
     },
     async get(sql, params) {
-      const stmt = database.prepare(sql);
-      const row = params ? stmt.get(...params) : stmt.get();
+      const row = await engine.get(sql, params);
       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 });
+      const result = await engine.run(sql, params);
+      return ok(result);
     },
     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();
+        await engine.batch(statements);
         return ok(void 0);
       } catch (error) {
         return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_sqliteBatchFailed", { params: { error: String(error) } }), error);
@@ -2273,45 +3069,32 @@ function createSqliteProvider() {
     },
     async queryPage(options) {
       const result = await queryPageAsync(
-        async (sqlStr, params) => {
-          const stmt = database.prepare(sqlStr);
-          return params ? stmt.all(...params) : stmt.all();
-        },
+        (sqlStr, params) => engine.all(sqlStr, params),
         options
       );
       return ok(result);
     }
   };
-  function createSqliteTxDmlOps(db) {
+  function createSqliteTxDmlOps(txEngine) {
     return {
       async query(sql, params) {
-        const stmt = db.prepare(sql);
-        return ok(params ? stmt.all(...params) : stmt.all());
+        return ok(await txEngine.all(sql, params));
       },
       async get(sql, params) {
-        const stmt = db.prepare(sql);
-        return ok((params ? stmt.get(...params) : stmt.get()) ?? null);
+        return ok(await txEngine.get(sql, params) ?? 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 });
+        return ok(await txEngine.run(sql, params));
       },
       async batch(statements) {
         for (const { sql: s, params } of statements) {
-          const stmt = db.prepare(s);
-          if (params)
-            stmt.run(...params);
-          else stmt.run();
+          await txEngine.run(s, params);
         }
         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();
-          },
+          (sqlStr, params) => txEngine.all(sqlStr, params),
           options
         );
         return ok(result);
@@ -2319,7 +3102,7 @@ function createSqliteProvider() {
     };
   }
   async function beginTx() {
-    const db = database;
+    const txEngine = engine;
     let released = false;
     const releaseTxLock = await acquireTxLock();
     const finishTransaction = () => {
@@ -2329,18 +3112,19 @@ function createSqliteProvider() {
       }
     };
     try {
-      db.exec("BEGIN TRANSACTION");
+      await txEngine.exec("BEGIN TRANSACTION");
     } catch (error) {
       finishTransaction();
       return err(HaiReldbError.TRANSACTION_FAILED, sqliteTxErrorMessage(String(error)), error);
     }
-    const txDmlOps = createSqliteTxDmlOps(db);
-    return ok(createTxHandle(txDmlOps, {
+    const txDmlOps = createSqliteTxDmlOps(txEngine);
+    const guardedTxDmlOps = createBaseDmlOps({ ...ctx, isConnected: () => txEngine.isOpen() }, txDmlOps);
+    return ok(createTxHandle(guardedTxDmlOps, {
       commit: async () => {
-        db.exec("COMMIT");
+        await txEngine.exec("COMMIT");
       },
       rollback: async () => {
-        db.exec("ROLLBACK");
+        await txEngine.exec("ROLLBACK");
       },
       release: () => finishTransaction(),
       errorMessage: sqliteTxErrorMessage
@@ -2355,38 +3139,35 @@ function createSqliteProvider() {
       if (!config.database) {
         return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_sqliteNeedPath"));
       }
+      const previousCleanup = await closeResource();
+      if (!previousCleanup.success)
+        return previousCleanup;
       try {
-        const Database = require2("better-sqlite3");
         const sqliteOptions = {
           walMode: true,
           readonly: false,
+          executor: "sync",
+          workerConnectTimeoutMs: 1e4,
           ...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 });
+        const engineOptions = {
+          database: config.database,
+          readonly: sqliteOptions.readonly ?? false,
+          walMode: sqliteOptions.walMode !== false
+        };
+        engine = sqliteOptions.executor === "worker" ? createWorkerSqliteEngine(engineOptions, sqliteOptions.workerConnectTimeoutMs ?? 1e4) : createSyncSqliteEngine(engineOptions);
+        await engine.initialize();
+        ready = true;
+        currentConfig2 = config;
+        logger4.info("Connected to SQLite", { database: config.database, executor: sqliteOptions.executor });
         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");
+        const cleanup = await closeResource();
+        const result = err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_sqliteConnectionFailed", { params: { error: String(error) } }), error);
+        return cleanup.success || result.success ? result : err({ ...result.error, ext: { cleanupPending: true, cleanupError: cleanup.error } });
       }
-      return ok(void 0);
     },
+    close: closeResource,
     isConnected: () => ctx.isConnected(),
     ddl: createBaseDdlOps(ctx, rawDdl),
     sql: dmlOps,
@@ -2401,6 +3182,43 @@ var currentProvider = null;
 var currentConfig = null;
 var currentJsonOps = null;
 var initInProgress = false;
+var pendingProvider = null;
+var initCompletion = null;
+var closingPromise = null;
+async function closeOwnedProvider() {
+  if (currentProvider) {
+    pendingProvider = currentProvider;
+    currentProvider = null;
+  }
+  currentConfig = null;
+  currentJsonOps = null;
+  if (!pendingProvider)
+    return ok(void 0);
+  try {
+    const result = await pendingProvider.close();
+    if (!result.success)
+      return err({ ...result.error, ext: { ...result.error.ext, cleanupPending: true } });
+    pendingProvider = null;
+    return ok(void 0);
+  } catch (error) {
+    logger5.error("Provider cleanup failed; retaining resource for retry", { error });
+    return err({ ...HaiReldbError.CONNECTION_FAILED, message: reldbM("reldb_closeFailed", {
+      params: { error: error instanceof Error ? error.message : String(error) }
+    }), cause: error, ext: { cleanupPending: true } });
+  }
+}
+async function failInitialization(result) {
+  const cleanup = await closeOwnedProvider();
+  if (result.success)
+    return result;
+  if (cleanup.success) {
+    const ext = { ...result.error.ext };
+    delete ext.cleanupPending;
+    delete ext.cleanupError;
+    return err({ ...result.error, ext: Object.keys(ext).length > 0 ? ext : void 0 });
+  }
+  return err({ ...result.error, ext: { ...result.error.ext, cleanupPending: true, cleanupError: cleanup.error } });
+}
 function createProvider(config) {
   switch (config.type) {
     case "sqlite":
@@ -2429,18 +3247,29 @@ var reldb = {
    *
    * @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
+   * ```
    */
   async init(config) {
-    if (initInProgress) {
+    if (initInProgress || closingPromise) {
       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;
+    let resolveInit;
+    initCompletion = new Promise((resolve) => {
+      resolveInit = resolve;
+    });
     try {
-      if (currentProvider) {
-        logger5.warn("RelDB module is already initialized, reinitializing");
-        await reldb.close();
-      }
+      const cleanup = await closeOwnedProvider();
+      if (!cleanup.success)
+        return cleanup;
       logger5.info("Initializing RelDB module");
       const parseResult = ReldbConfigSchema.safeParse(config);
       if (!parseResult.success) {
@@ -2448,16 +3277,20 @@ var reldb = {
         return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_configError", { params: { error: parseResult.error.message } }), parseResult.error);
       }
       const parsed = parseResult.data;
+      if (core.module.requiresSharedState(process.env) && parsed.type === "sqlite")
+        return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_sharedBackendRequired"));
       try {
         const provider = createProvider(parsed);
+        pendingProvider = provider;
         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;
+          return await failInitialization(connectResult);
         }
+        pendingProvider = null;
         currentProvider = provider;
         currentConfig = parsed;
         currentJsonOps = createJsonOps(parsed.type);
@@ -2465,10 +3298,12 @@ var reldb = {
         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);
+        return await failInitialization(err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_initFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error));
       }
     } finally {
       initInProgress = false;
+      initCompletion = null;
+      resolveInit();
     }
   },
   /**
@@ -2500,9 +3335,14 @@ var reldb = {
   get tx() {
     return currentProvider?.tx ?? notInitializedTx;
   },
-  /** 获取当前配置（未初始化时为 null） */
+  /** 获取当前脱敏后的配置快照（未初始化时为 null） */
   get config() {
-    return currentConfig;
+    if (!currentConfig)
+      return null;
+    const snapshot = core.sanitize.sanitizeSensitiveFields(currentConfig);
+    if ("ssl" in snapshot && snapshot.ssl && typeof snapshot.ssl === "object" && "key" in snapshot.ssl)
+      snapshot.ssl.key = core.sanitize.defaultSensitiveReplacement;
+    return snapshot;
   },
   /** 检查是否已初始化 */
   get isInitialized() {
@@ -2548,35 +3388,123 @@ var reldb = {
   /**
    * 关闭数据库连接
    *
-   * 多次调用安全，未初始化时直接返回。
+   * 等待初始化和在途事务，停止接收新操作；失败时保留资源供 close/init 重试。
+   * @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
+   * ```
    */
   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;
+    if (!closingPromise) {
+      closingPromise = (async () => {
+        if (initCompletion)
+          await initCompletion;
+        return await closeOwnedProvider();
+      })().finally(() => {
+        closingPromise = null;
+      });
     }
+    return await closingPromise;
   }
 };
+async function schemaColumns(db, table, sql = db.sql) {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(table))
+    return err(HaiCommonError.VALIDATION_ERROR, core.i18n.coreM("core_errorValidation"));
+  const type = db.config?.type;
+  const found = type === "sqlite" ? await sql.query(`PRAGMA table_info(${table})`) : await sql.query(`SELECT column_name AS name FROM information_schema.columns WHERE table_schema=${type === "mysql" ? "DATABASE()" : "current_schema()"} AND table_name=?`, [table]);
+  return found.success ? ok(found.data.map((row) => row.name)) : found;
+}
+async function migrateSchema(db, module, steps, options = {}) {
+  if (!db.isInitialized || !/^[a-z][a-z0-9-]{0,62}$/.test(module) || steps.some((step, index) => step.version !== index + 1))
+    return err(HaiCommonError.VALIDATION_ERROR, core.i18n.coreM("core_errorValidation"));
+  const table = "hai_schema_migrations";
+  const targetVersion = steps.length;
+  const failed = (cause) => err({ ...HaiCommonError.INIT_FAILED, message: core.i18n.coreM("core_runtimeStartFailed", { params: { module } }), ext: { module, phase: "migration" }, cause });
+  async function inspect(sql) {
+    const columns = await schemaColumns(db, table, sql);
+    if (!columns.success)
+      return failed(columns.error);
+    const row = columns.data.length ? await sql.get(`SELECT version FROM ${table} WHERE module=?`, [module]) : ok(null);
+    if (!row.success)
+      return failed(row.error);
+    const currentVersion = Number(row.data?.version ?? 0);
+    if (currentVersion > targetVersion)
+      return failed();
+    const changes = [];
+    for (const step of steps) {
+      const needed = await step.needed(sql);
+      if (!needed.success)
+        return failed(needed.error);
+      if (needed.data)
+        changes.push(step.name);
+    }
+    return ok({ module, currentVersion, targetVersion, changes, requiresExclusiveAccess: changes.length > 0 });
+  }
+  if (options.dryRun)
+    return inspect(db.sql);
+  const created = await db.sql.execute(`CREATE TABLE IF NOT EXISTS ${table} (module VARCHAR(64) PRIMARY KEY, version INTEGER NOT NULL)`);
+  if (!created.success)
+    return failed(created.error);
+  const seeded = await db.sql.execute(db.config?.type === "mysql" ? `INSERT IGNORE INTO ${table}(module,version) VALUES (?,0)` : `INSERT INTO ${table}(module,version) VALUES (?,0) ON CONFLICT(module) DO NOTHING`, [module]);
+  if (!seeded.success)
+    return failed(seeded.error);
+  const started = await db.tx.begin();
+  if (!started.success)
+    return failed(started.error);
+  const tx = started.data;
+  let mysqlLock = false;
+  let committed = false;
+  try {
+    if (db.config?.type === "mysql") {
+      const lock = await tx.get("SELECT GET_LOCK(?,30) AS acquired", [`hai-schema:${module}`]);
+      if (!lock.success || Number(lock.data?.acquired) !== 1)
+        return failed(lock.success ? new Error("Migration lock unavailable") : lock.error);
+      mysqlLock = true;
+    }
+    const locked = await tx.execute(`UPDATE ${table} SET version=version WHERE module=?`, [module]);
+    if (!locked.success)
+      return failed(locked.error);
+    const plan = await inspect(tx);
+    if (!plan.success)
+      return plan;
+    for (const step of steps) {
+      const needed = await step.needed(tx);
+      if (!needed.success)
+        return failed(needed.error);
+      if (needed.data) {
+        const applied = await step.apply(tx);
+        if (!applied.success)
+          return failed(applied.error);
+        const remaining = await step.needed(tx);
+        if (!remaining.success || remaining.data)
+          return failed(remaining.success ? new Error("Migration step did not converge") : remaining.error);
+      }
+    }
+    const recorded = await tx.execute(`UPDATE ${table} SET version=? WHERE module=?`, [targetVersion, module]);
+    if (!recorded.success)
+      return failed(recorded.error);
+    if (mysqlLock) {
+      await tx.get("SELECT RELEASE_LOCK(?)", [`hai-schema:${module}`]);
+      mysqlLock = false;
+    }
+    const result = await tx.commit();
+    committed = result.success;
+    return result.success ? plan : failed(result.error);
+  } catch (error) {
+    return failed(error);
+  } finally {
+    if (mysqlLock)
+      await tx.get("SELECT RELEASE_LOCK(?)", [`hai-schema:${module}`]);
+    if (!committed)
+      await tx.rollback();
+  }
+}
 
-export { BaseReldbCrudRepository, HaiReldbError, MysqlConfigSchema, MysqlOptionsSchema, PoolConfigSchema, PostgresqlConfigSchema, ReldbConfigSchema, ReldbTypeSchema, SqliteConfigSchema, SqliteOptionsSchema, SslConfigSchema, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };
+export { BaseReldbCrudRepository, HaiReldbError, createJsonOps, escapeSqlString, migrateSchema, parseJsonPath, quoteIdentifier, reldb, schemaColumns, validateIdentifier, validateIdentifiers };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map