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

package/README.md

@@ -1,20 +1,44 @@
 # @h-ai/reldb
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
+## 简介
+
 关系型数据库访问模块，通过统一的 `reldb` 对象访问 SQLite、PostgreSQL、MySQL。
 
-## 支持的数据库
+初始化只在健康检查成功后发布连接；失败时释放候选资源。若清理仍失败，初始化错误的 `error.ext.cleanupPending` 为 `true`。`reldb.close()` 返回 `Promise<HaiResult<void>>`，等待正在进行的初始化，并合并并发关闭。开始清理后 `isInitialized` 为 `false`，配置与业务操作不再可用；清理失败仍保留资源，后续 `close()` 或 `init()` 先重试释放，成功前不会创建替代连接。调用方必须检查关闭结果。
+
+```ts
+const closed = await reldb.close()
+if (!closed.success) {
+  // 处理清理故障后有限重试；再次失败应向应用报告。
+  const retried = await reldb.close()
+  if (!retried.success)
+    throw new Error(retried.error.message)
+}
+```
+
+关闭会等待已借出的事务提交/回滚并释放句柄；应用必须结束事务才能完成关闭。SQLite 的 WAL 配置与 worker 握手也属于初始化资源链。PostgreSQL 空闲连接断开由连接池移除并在后续查询时替换，不使进程退出；日志仅记录安全错误标识，不输出驱动错误原文。
+
+## 核心功能清单
 
-- SQLite
-- PostgreSQL
-- MySQL
+- 用同一套 API 连接 SQLite、PostgreSQL 和 MySQL。
+- 执行参数化 SQL，创建表和索引，读取分页结果。
+- 使用事务、CRUD 与 Repository 组织业务读写。
 
-## 快速开始
+## 使用入门
+
+### 快速开始
 
 ```ts
 import { HaiReldbError, reldb } from '@h-ai/reldb'
 
 // 初始化
-await reldb.init({ type: 'sqlite', database: ':memory:' })
+const initialized = await reldb.init({ type: 'sqlite', database: ':memory:' })
+if (!initialized.success)
+  throw new Error(initialized.error.message)
 
 // DDL
 await reldb.ddl.createTable('users', {
@@ -49,7 +73,20 @@ const user = await userCrud.findById(1)
 await reldb.close()
 ```
 
-## 配置
+`reldb.config` 返回的是**脱敏后的配置快照**：数据库 `password`、URL 内嵌凭证和 TLS 客户端私钥 `ssl.key` 会自动隐藏，便于排查状态但不应用于回放原始连接信息。
+
+### 配置
+
+`@h-ai/reldb/schemas` 直接导出同一组配置 Schema 和类型，只依赖 Zod，不加载数据库实例或驱动，可用于 CLI 或浏览器的配置校验。MySQL TLS 仅接受 `false` 或严格对象，`{}` 默认校验证书链和 DNS 身份；PostgreSQL 保留其布尔值、字符串模式及对象契约。
+
+```ts
+import { ReldbConfigSchema } from '@h-ai/reldb/schemas'
+
+const checked = ReldbConfigSchema.safeParse({ type: 'mysql', database: 'shop', ssl: {} })
+if (!checked.success)
+  throw new Error('Invalid database configuration')
+// checked.data.ssl: { rejectUnauthorized: true, verifyIdentity: true }
+```
 
 支持连接字符串（`url`）或分字段（`host/port/database/user/password`）。
 
@@ -58,7 +95,7 @@ await reldb.close()
 await reldb.init({ type: 'sqlite', database: './data.db' })
 
 // PostgreSQL
-await reldb.init({ type: 'postgresql', url: 'postgres://user:pass@localhost:5432/mydb' })
+await reldb.init({ type: 'postgresql', url: 'postgres://user:pass@localhost:5432/mydb', database: 'mydb' })
 
 // MySQL
 await reldb.init({
@@ -69,65 +106,189 @@ await reldb.init({
   user: 'admin',
   password: 'secret',
   mysql: { charset: 'utf8mb4' },
+  pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 },
 })
 ```
 
-## 事务
+#### 连接池与 MySQL URL
+
+MySQL 的 `pool` 只接受 `max`、`acquireTimeout`、`queueLimit`，省略时默认分别为 10、10000 毫秒、1000。其他池字段（包括 `min`、`idleTimeout`）以及未实现的 `mysql.timezone` 会在配置校验时失败。空闲连接由 mysql2/服务端断开或 `close()` 释放，本模块不承诺 MySQL 的最小保留数或可配置的空闲回收期限；[mysql2 3.24.5 的真实选项](https://github.com/sidorares/node-mysql2/blob/v3.24.5/typings/mysql/lib/Pool.d.ts)与 PostgreSQL 不同。
+
+| 字段             | PostgreSQL（显式提供 `pool` 时的默认值） | MySQL                                  |
+| ---------------- | ---------------------------------------- | -------------------------------------- |
+| `max`            | 10                                       | 10，借用和正在建连合计不超过此值       |
+| `min`            | 1，已建立连接的保留下限，不主动预建      | 不支持，明确拒绝                       |
+| `idleTimeout`    | 30000 毫秒，0 禁用                       | 不支持，明确拒绝                       |
+| `acquireTimeout` | 10000 毫秒，0 禁用                       | 10000 毫秒，必须为 1–2147483647 的整数 |
+| `queueLimit`     | 不支持                                   | 1000，等待请求上限，必须为正整数       |
+
+PostgreSQL 未提供 `pool` 时沿用 pg 驱动默认值；保留与空闲回收语义见 [pg.Pool](https://node-postgres.com/apis/pool)。MySQL 所有 SQL、DDL、CRUD、批量和事务入口共用有界 FIFO 借用队列：排队与建立连接共用一个 `acquireTimeout` 截止期限，超时返回 `TIMEOUT`，队列满返回 `POOL_EXHAUSTED`。超时排队请求会移除；已开始但迟到的建连只释放连接，不启动 SQL，结算前仍占容量槽位。取得连接及业务执行前再次校验期限；它不限制已启动 SQL 或事务的执行时长。
+
+MySQL `close()` 立即拒绝新请求并结束排队等待，随后等待已借出连接、事务及在途建连结算再关闭池。驱动 `connectTimeout` 使用相同超时值；关闭可能等到该建连时限或现有 SQL/事务结束，应用仍须主动结束事务。环境变量使用 `HAI_DB_POOL_*`，`HAI_DB_POOL_MIN` / `HAI_DB_POOL_IDLETIMEOUT` 仅用于 PostgreSQL，MySQL 的 `HAI_DB_POOL_QUEUELIMIT` 控制等待总量。
+
+MySQL 支持仅传 `url`（`mysql://`），未给 URL 时 `database` 必填。URL 中的 host/port/database/user/password 优先，冲突的分字段不参与连接；`pool`、`mysql.charset`、`ssl` 和 `operationLog` 独立适用。URL 仅接受连接地址，query/fragment 会被拒绝，不能用隐藏 URL 参数改变 TLS 或池策略。URL 模式的连接日志会脱敏。以下示例假定已设置 `HAI_DB_URL`：
+
+```ts
+const initialized = await reldb.init({ type: 'mysql', url: process.env.HAI_DB_URL, pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 } })
+if (!initialized.success)
+  throw new Error(initialized.error.message)
+```
+
+MySQL 的空 `url`（例如空环境变量占位）表示使用 host/port/database/user/password；非空 URL 仍严格校验。
+
+#### MySQL TLS
+
+`ssl` 省略或为 `false` 时不启用 TLS；启用时只能传严格对象，空对象默认 `{ rejectUnauthorized: true, verifyIdentity: true }`。`ca` 是受信 CA 的 PEM 内容，省略时使用 Node 信任库；可选客户端 `cert` / `key` 也必须是 PEM 内容且成对提供。未知 TLS 字段、`true` 和 PostgreSQL 字符串模式明确拒绝，不提供任意参数/回调透传。
+
+当前 [mysql2 3.24.5 的主机身份校验](https://github.com/sidorares/node-mysql2/blob/v3.24.5/lib/base/connection.js)依赖 DNS servername。因此在证书链及身份校验均开启时，IP 目标返回 `CONFIG_ERROR`，须使用与证书 DNS SAN 匹配的主机名。显式 `verifyIdentity: false` 只保留证书链校验；`rejectUnauthorized: false` 放弃服务端认证，即使存在加密也不能确认服务端身份。关闭任一验证会输出固定风险日志，不会称为安全连接。
+
+```ts
+// trustedCaPem 由部署时的受信 CA 提供，不是任意远端返回的证书。
+const initialized = await reldb.init({ type: 'mysql', host: 'db.example.com', database: 'app', ssl: { ca: trustedCaPem } })
+if (!initialized.success)
+  throw new Error(initialized.error.message)
+```
+
+TLS 定向测试需要 OpenSSL（Windows 可使用 Git 附带版本）及本机容器端口转发；每轮生成并销毁 CA/私钥，通过真实 MySQL 验证受信 DNS、错误 CA/主机名拒绝、`REQUIRE X509` 客户端认证和会话 `Ssl_cipher`，不使用关闭验证替代认证成功证据。
+
+#### SQLite 执行方式（worker 异步）
+
+better-sqlite3 是同步驱动，查询会阻塞 Node 主线程事件循环。WAL 只能改善数据库锁并发，无法避免同步调用占用主线程。需要卸载这一阻塞时，可把 SQLite 切到专用 worker 线程执行（单连接，opt-in，默认 `sync`）：
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  sqlite: {
+    executor: 'worker', // 'sync'（默认）| 'worker'
+    walMode: true, // 默认 true
+    workerConnectTimeoutMs: 10000, // worker 打开连接超时，默认 10000
+  },
+})
+```
+
+worker 模式下查询、写入与事务均在 worker 线程串行执行；公共 API 与返回值与同步模式完全一致。
+
+#### 操作日志
+
+可在数据库配置中通过 `operationLog` 开启 SQL 操作日志。日志在 reldb provider-base 的 DML 操作层统一输出，不在 `reldb-main.ts` 或各 raw provider 中重复包装。
+
+```yaml
+# config/_db.yml
+type: sqlite
+database: ./data/app.db
+operationLog:
+  read: false # query / get / queryPage
+  write: false # DDL, execute / batch, tx.begin / tx.commit / tx.rollback
+  maxLength: 1000 # 安全数量摘要的最大字符数，0省略摘要；不记录SQL原文/参数值
+  level: debug # info | debug | trace，默认 debug
+```
+
+通过 `core.config.load('db', ...)` 加载时，`HAI_DB_TYPE`、
+`HAI_DB_DATABASE`、`HAI_DB_OPERATIONLOG_LEVEL` 等约定变量优先于 YAML。
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+操作日志记录固定操作名、SQL 长度、参数数量和批量数量等摘要。失败日志额外保留错误码、traceId 以及白名单内的脱敏驱动消息和堆栈，便于定位；不会直接记录整份 SQL、绑定参数或连接配置。
+
+### 事务
 
 三种使用方式：
 
-### wrap（自动提交/回滚）
+#### wrap（自动提交/回滚）
+
+事务回调正常返回就会提交，返回失败 HaiResult 也不例外。必须检查每一步结果，并在失败时抛出异常触发回滚；wrap 会把异常转为 TRANSACTION_FAILED。需要保留原领域错误时，使用下方手动事务。各片段假定数据库已成功初始化且 users 表已经创建。
 
 ```ts
 const result = await reldb.tx.wrap(async (tx) => {
-  await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
-  await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
+  for (const name of ['Alice', 'Bob']) {
+    const inserted = await tx.execute('INSERT INTO users (name) VALUES (?)', [name])
+    if (!inserted.success)
+      throw new Error(inserted.error.message, { cause: inserted.error })
+  }
   return 'ok'
 })
 // 回调正常返回 → 自动提交；抛异常 → 自动回滚
 ```
 
-### begin + commit（分步提交）
+#### begin + commit（分步提交）
 
 ```ts
+// 放在 async 业务函数内，失败时向调用方返回 HaiResult。
 const txResult = await reldb.tx.begin()
-if (!txResult.success) { /* 处理错误 */ }
+if (!txResult.success)
+  return txResult
 const tx = txResult.data
-
-await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
-await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
-await tx.commit()
+try {
+  for (const name of ['Alice', 'Bob']) {
+    const inserted = await tx.execute('INSERT INTO users (name) VALUES (?)', [name])
+    if (!inserted.success) {
+      const rolledBack = await tx.rollback()
+      return rolledBack.success ? inserted : rolledBack
+    }
+  }
+  return await tx.commit()
+}
+catch (error) {
+  const rolledBack = await tx.rollback()
+  if (!rolledBack.success)
+    return rolledBack
+  throw error // 只传播非业务异常，由宿主边界处理。
+}
 ```
 
-### begin + rollback（分步回滚）
+#### begin + rollback（分步回滚）
 
 ```ts
+// 独立脚本：试写后回滚，不保留用户数据。
 const txResult = await reldb.tx.begin()
-if (!txResult.success) { /* 处理错误 */ }
+if (!txResult.success)
+  throw new Error(txResult.error.message, { cause: txResult.error })
 const tx = txResult.data
-
-await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
-// 业务检查失败，手动回滚
-await tx.rollback()
+// 两个 API 均返回 HaiResult；同时失败时保留执行和回滚两份原因。
+const inserted = await tx.execute('INSERT INTO users (name) VALUES (?)', ['Alice'])
+const rolledBack = await tx.rollback()
+if (!inserted.success && !rolledBack.success)
+  throw new AggregateError([inserted.error, rolledBack.error], rolledBack.error.message)
+if (!inserted.success)
+  throw new Error(inserted.error.message, { cause: inserted.error })
+if (!rolledBack.success)
+  throw new Error(rolledBack.error.message, { cause: rolledBack.error })
 ```
 
-### 事务内使用 batch / queryPage
+#### 事务内使用 batch / queryPage
 
 ```ts
 await reldb.tx.wrap(async (tx) => {
-  await tx.batch([
-    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['用户1'] },
-    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['用户2'] },
+  const inserted = await tx.batch([
+    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['Alice'] },
+    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['Bob'] },
   ])
+  if (!inserted.success)
+    throw new Error(inserted.error.message, { cause: inserted.error })
 
   const page = await tx.queryPage<{ id: number, name: string }>({
     sql: 'SELECT id, name FROM users ORDER BY id',
     pagination: { page: 1, pageSize: 10 },
   })
+  if (!page.success)
+    throw new Error(page.error.message, { cause: page.error })
+  return page.data
 })
 ```
 
-## Crud
+### Crud
 
 通过 `reldb.crud.table()` 创建单表 CRUD 仓库，免写 SQL：
 
@@ -142,7 +303,7 @@ const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
 })
 ```
 
-### create / createMany
+#### create / createMany
 
 ```ts
 // 单条插入
@@ -156,7 +317,7 @@ await userCrud.createMany([
 ])
 ```
 
-### createOrUpdate
+#### createOrUpdate
 
 主键存在时更新，否则创建（upsert）：
 
@@ -175,7 +336,7 @@ await userCrud.createOrUpdate({ id: 1, name: '张三', email: 'test@example.com'
 
 `BaseReldbCrudRepository` 自动获取 `dbType`，无需手动传入。
 
-### findById / getById / findAll / findPage
+#### findById / getById / findAll / findPage
 
 ```ts
 // 主键查找（不存在时返回 null）
@@ -205,14 +366,14 @@ const page = await userCrud.findPage({
 // page.data → { items: [...], total: 100, page: 1, pageSize: 20 }
 ```
 
-### updateById / deleteById
+#### updateById / deleteById
 
 ```ts
 await userCrud.updateById(1, { name: '李四' })
 await userCrud.deleteById(1)
 ```
 
-### count / exists / existsById
+#### count / exists / existsById
 
 ```ts
 const total = await userCrud.count({ where: 'name LIKE ?', params: ['%张%'] })
@@ -225,22 +386,33 @@ const found = await userCrud.existsById(1)
 // found.data → true
 ```
 
-### 事务中使用 Crud
+#### 事务中使用 Crud
 
 所有方法均支持传入 `tx` 参数，自动路由到事务上下文：
 
 ```ts
 await reldb.tx.wrap(async (tx) => {
-  await userCrud.create({ name: '用户A', email: 'a@test.com' }, tx)
-  await userCrud.updateById(1, { name: '新名字' }, tx)
-  const user = await userCrud.findById(1, tx)
+  const created = await userCrud.create({ name: 'Alice', email: 'alice@example.com' }, tx)
+  if (!created.success)
+    throw new Error(created.error.message, { cause: created.error })
+  if (created.data.lastInsertRowid === undefined)
+    throw new Error('Insert did not return an ID')
+  const updated = await userCrud.updateById(created.data.lastInsertRowid, { name: 'Alice Smith' }, tx)
+  if (!updated.success)
+    throw new Error(updated.error.message, { cause: updated.error })
+  const user = await userCrud.findById(created.data.lastInsertRowid, tx)
+  if (!user.success)
+    throw new Error(user.error.message, { cause: user.error })
+  return user.data
 })
 ```
 
-## BaseReldbCrudRepository
+### BaseReldbCrudRepository
 
 业务仓库继承 `BaseReldbCrudRepository`，通过 `fields` 定义字段映射，自动建表、类型转换：
 
+Unix 毫秒字段使用 `BIGINT`（SQLite 为 64 位 INTEGER，PostgreSQL/MySQL 为 BIGINT），普通 INTEGER 在 PostgreSQL/MySQL 中无法容纳当前毫秒时间。BIGINT 的原始 SQL/CRUD 和基类读取值保留驱动的 number/string/bigint 类型；需要 number 的业务仓库须校验安全整数后转换，避免静默精度丢失。TIMESTAMP 字段由基类读取为 Date。
+
 ```ts
 import type { DmlWithTxOperations, ReldbCrudFieldDefinition } from '@h-ai/reldb'
 import { BaseReldbCrudRepository, reldb } from '@h-ai/reldb'
@@ -273,6 +445,10 @@ class UserRepository extends BaseReldbCrudRepository<UserRow> {
 
   /** 自定义方法中使用 this.sql(tx) 自动路由到事务 */
   async insertRaw(data: { name: string, email: string }, tx?: DmlWithTxOperations) {
+    // 自定义原始写操作应先确保表已就绪（避免刚建库/建表较慢时的竞态）
+    const ready = await this.ensureReady()
+    if (!ready.success)
+      return ready
     const now = Date.now()
     return this.sql(tx).execute(
       'INSERT INTO users (name, email, created_at, updated_at) VALUES (?, ?, ?, ?)',
@@ -300,7 +476,7 @@ if (txResult.success) {
 }
 ```
 
-## JSON 路径操作
+### JSON 路径操作
 
 通过 `reldb.json` 构建跨数据库统一的 JSON 路径操作 SQL 表达式。
 
@@ -316,7 +492,7 @@ if (txResult.success) {
 
 所有方法返回 `{ sql, params }` 片段，可直接嵌入 `reldb.sql.query` / `reldb.sql.execute`。
 
-### extract — 提取 JSON 字段值
+#### extract — 提取 JSON 字段值
 
 ```ts
 // 用于 WHERE 条件
@@ -334,7 +510,7 @@ const result = await reldb.sql.query(
 )
 ```
 
-### set — 设置 JSON 字段路径（创建或替换）
+#### set — 设置 JSON 字段路径（创建或替换）
 
 ```ts
 const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
@@ -344,7 +520,7 @@ await reldb.sql.execute(
 )
 ```
 
-### insert — 插入 JSON 字段路径（仅当路径不存在时）
+#### insert — 插入 JSON 字段路径（仅当路径不存在时）
 
 ```ts
 const { sql, params } = reldb.json.insert('data', '$.firstSeen', new Date().toISOString())
@@ -354,7 +530,7 @@ await reldb.sql.execute(
 )
 ```
 
-### remove — 删除 JSON 字段路径
+#### remove — 删除 JSON 字段路径
 
 ```ts
 const { sql, params } = reldb.json.remove('settings', '$.deprecated')
@@ -364,7 +540,7 @@ await reldb.sql.execute(
 )
 ```
 
-### merge — 合并 JSON 对象（RFC 7396 Merge Patch）
+#### merge — 合并 JSON 对象（RFC 7396 Merge Patch）
 
 ```ts
 // 覆盖已有键、保留未提及键、将 null 键删除
@@ -378,7 +554,9 @@ await reldb.sql.execute(
 )
 ```
 
-### 完整示例
+`json.merge(column, patch)` 在三种后端均实现 RFC 7396 的对象补丁：递归保留未改键，补丁 null 删除指定键，数组整体替换。PostgreSQL 用参数化递归 CTE 在单次 SQL 中修改当前行，不要求预装函数，也不先在应用读取再写回。补丁根必须是可 JSON 序列化的对象；此契约不扩展为任意 JSON 根补丁。列表达式由开发者静态提供，动态路径和值全部作为参数。参见 [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396) 和 [PostgreSQL JSON 运算](https://www.postgresql.org/docs/16/functions-json.html)。
+
+#### 完整示例
 
 ```ts
 // 建表（含 JSON 列）
@@ -413,7 +591,7 @@ const { sql: rmSql, params: rmParams } = reldb.json.remove('meta', '$.reviewer')
 await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...rmParams, 1])
 ```
 
-## 错误处理
+### 错误处理
 
 所有操作返回 `HaiResult<T>`，通过 `result.success` 判断成功或失败。
 
@@ -438,17 +616,37 @@ if (!result.success) {
 
 常用错误码：
 
-| 错误码                               | code            | 说明         |
-| ------------------------------------ | --------------- | ------------ |
-| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:010` | 未初始化     |
-| `HaiReldbError.CONNECTION_FAILED`    | `hai:reldb:001` | 连接失败     |
-| `HaiReldbError.QUERY_FAILED`         | `hai:reldb:002` | 查询失败     |
-| `HaiReldbError.CONSTRAINT_VIOLATION` | `hai:reldb:003` | 约束违反     |
-| `HaiReldbError.TRANSACTION_FAILED`   | `hai:reldb:004` | 事务失败     |
-| `HaiReldbError.DDL_FAILED`           | `hai:reldb:020` | DDL 操作失败 |
-| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:013` | 配置错误     |
+| 错误码                               | code            | 说明                       |
+| ------------------------------------ | --------------- | -------------------------- |
+| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:010` | 未初始化                   |
+| `HaiReldbError.CONNECTION_FAILED`    | `hai:reldb:001` | 连接失败                   |
+| `HaiReldbError.QUERY_FAILED`         | `hai:reldb:002` | 查询失败                   |
+| `HaiReldbError.CONSTRAINT_VIOLATION` | `hai:reldb:003` | 约束违反                   |
+| `HaiReldbError.TRANSACTION_FAILED`   | `hai:reldb:004` | 事务失败                   |
+| `HaiReldbError.DDL_FAILED`           | `hai:reldb:020` | DDL 操作失败               |
+| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:013` | 配置错误                   |
+| `HaiReldbError.TIMEOUT`              | `hai:reldb:009` | MySQL 连接获取超过截止期限 |
+| `HaiReldbError.POOL_EXHAUSTED`       | `hai:reldb:011` | MySQL 连接等待队列已满     |
+
+派生 `BaseReldbCrudRepository` 的自定义 SQL 方法先检查 `await this.ensureReady()`；构造函数启动自动建表不等于仓库就绪，服务 init 必须等待候选仓库的就绪入口再发布。PostgreSQL 自动提交的单条 `CREATE TABLE/INDEX IF NOT EXISTS` 仅对 `23505/pg_class_relname_nsp_index`（建表还包括 `pg_type_typname_nsp_index`）目录竞争，或建表时 `42710` 且服务端 routine 为 `heap_create_with_catalog` / `TypeCreate` 的行类型竞争重执行一次；重试仍失败则保留错误，DDL 与 SQL 入口一致；事务、业务唯一约束及其他错误不自动重试。初始化连接探测仅对临时 DNS 错误 `EAI_AGAIN` 最多尝试三次，间隔 250/500 ms；不重放业务 SQL。
+
+## 生产共享状态
 
-## 测试
+生产仅使用 PostgreSQL/MySQL；SQLite（含磁盘文件）只用于开发/明确测试，不能作为跨主机共享状态。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验；仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md)。
+
+## 模块架构迁移
+
+`schemaColumns(reldb, table, sql?)` 只读检查真实结构；`migrateSchema(reldb, module, steps, { dryRun: true })` 不创建账本。版本步骤由所属模块维护，业务不修改框架内部表。执行使用 `hai_schema_migrations`，SQLite/PostgreSQL 整体事务，MySQL DDL 隐式提交因此步骤必须可重入；失败不推进版本，重新检查真实结构后续做，拒绝向低版本降级。升级前停止所有旧写入并备份 DB/会话缓存；回退需恢复兼容数据库与旧代码，不能只换二进制。详见 [升级指南](../../docs/usage/README.md)。
+
+## 错误提示与关联日志
+
+唯一约束冲突统一返回 `HaiReldbError.DUPLICATE_ENTRY`（409）；超时、队列已满等已有错误码保持不变。业务按错误码分支，不解析本地化消息或驱动错误文本。日志保留驱动 code/schema/routine/constraint 和堆栈行号；数字绑定值不会误遮蔽这些诊断标识。
+
+HTTP 错误返回本地化安全文案及追踪编号；ToastContainer 默认隐藏编号，由排查信息图标展开和复制。响应同时包含 `error.traceId` 和 `X-Trace-Id`。框架复用本次 requestId 作为 traceId，前后端日志自动关联。底层异常、堆栈和操作上下文经凭据脱敏后写入日志，不通过 cause/ext 向用户公开。字段校验只返回本地化的字段名和错误。
+
+`core.error.toPublic(error, traceId?)` 用于接口/UI 边界；`core.error.formatMessage(error)` 用于重新翻译后的提示，重复调用不会重复追加标识。日志传入完整 Error 对象，不能只记录通用标题或提前 String(error) 丢失上下文。数据库失败记录驱动错误码、消息、堆栈及表/列；SQL 原文、绑定值和连接凭据不进入日志。
+
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/reldb test
@@ -456,6 +654,8 @@ pnpm --filter @h-ai/reldb test
 
 > MySQL/PostgreSQL 测试需要 Docker。
 
-## License
+源码 JSDoc 遵循[统一规范](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)：公开示例使用实际发布入口，内部示例在原模块作用域检查。构建后执行 `pnpm check:jsdoc --package reldb`；示例编译不代替真实后端行为验证。
+
+## 许可证
 
 Apache-2.0

package/dist/chunk-SDS2ZT3V.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+
+// src/reldb-config.ts
+var ReldbTypeSchema = z.enum(["sqlite", "postgresql", "mysql"]);
+var ReldbOperationLogConfigSchema = z.object({
+  read: z.boolean().default(false),
+  write: z.boolean().default(false),
+  /** 安全数量摘要的最大字符数；0 表示省略摘要，永不记录 SQL 原文或参数值。 */
+  maxLength: z.number().int().min(0).default(1e3),
+  level: z.enum(["info", "debug", "trace"]).default("debug")
+});
+var OperationLogConfigFieldSchema = {
+  operationLog: ReldbOperationLogConfigSchema.optional()
+};
+var PoolConfigSchema = z.object({
+  /** PostgreSQL 已建立连接的最小保留数（默认 1，不主动预建） */
+  min: z.number().int().min(0).default(1),
+  /** 最大连接数（默认 10） */
+  max: z.number().int().min(1).default(10),
+  /** PostgreSQL 空闲连接超时，毫秒（默认 30000；0 禁用） */
+  idleTimeout: z.number().int().min(0).default(3e4),
+  /** 获取连接超时，毫秒（默认10000）；PostgreSQL >=0，0禁用；MySQL排队+建连总期限为1–2147483647 */
+  acquireTimeout: z.number().int().min(0).default(1e4)
+});
+var MysqlPoolConfigSchema = z.object({
+  /** 最大连接数（默认 10） */
+  max: z.number().int().min(1).default(10),
+  /** 获取连接超时，毫秒（默认10000）；PostgreSQL >=0，0禁用；MySQL排队+建连总期限为1–2147483647 */
+  acquireTimeout: z.number().int().min(1).max(2147483647).default(1e4),
+  /** MySQL 等待队列最大请求数（默认 1000；正整数，不支持无限队列） */
+  queueLimit: z.number().int().min(1).default(1e3)
+}).strict();
+var SslConfigSchema = z.union([
+  z.boolean(),
+  z.enum(["require", "prefer", "allow", "disable"]),
+  z.record(z.string(), z.unknown())
+]);
+var MysqlSslConfigSchema = z.union([
+  z.literal(false),
+  z.object({
+    /** MySQL 是否校验证书链（默认 true）；false 明确放弃服务端认证 */
+    rejectUnauthorized: z.boolean().default(true),
+    /** MySQL 是否验证 DNS 主机身份（默认 true）；仅证书链验证开启时有效 */
+    verifyIdentity: z.boolean().default(true),
+    /** MySQL 信任的 CA，PEM 内容；省略时使用 Node 信任库 */
+    ca: z.string().min(1).optional(),
+    /** MySQL 客户端证书，PEM 内容；必须同时提供 key */
+    cert: z.string().min(1).optional(),
+    /** MySQL 客户端私钥，PEM 内容；必须同时提供 cert */
+    key: z.string().min(1).optional()
+  }).strict().refine((ssl) => Boolean(ssl.cert) === Boolean(ssl.key), { path: ["key"] })
+]);
+var SqliteOptionsSchema = z.object({
+  /** 是否启用 WAL 模式（默认 true），可提高并发读写性能 */
+  walMode: z.boolean().default(true),
+  /** 是否只读模式（默认 false） */
+  readonly: z.boolean().default(false),
+  /**
+   * 执行方式（默认 sync）。
+   *
+   * - `sync`：主线程直接执行 better-sqlite3（同步阻塞主线程事件循环）。
+   * - `worker`：在专用 worker 线程持有唯一连接执行，把阻塞移出主线程。
+   *   注意 WAL 只改善数据库锁并发，无法避免 better-sqlite3 同步调用占用调用线程。
+   */
+  executor: z.enum(["sync", "worker"]).default("sync"),
+  /** worker 执行方式下等待连接打开的超时（毫秒，默认 10000） */
+  workerConnectTimeoutMs: z.number().int().positive().default(1e4)
+});
+var MysqlOptionsSchema = z.object({
+  /** 字符集（默认 utf8mb4），推荐使用 utf8mb4 支持完整 Unicode */
+  charset: z.string().default("utf8mb4")
+}).strict();
+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(),
+  ...OperationLogConfigFieldSchema
+});
+var PostgresqlConfigSchema = NetworkConfigSchema.extend({
+  type: z.literal("postgresql"),
+  ...OperationLogConfigFieldSchema
+});
+var MysqlConfigSchema = NetworkConfigSchema.extend({
+  type: z.literal("mysql"),
+  /** 网络数据库URL；MySQL空串表示使用分字段，非空仅mysql://且拒绝query/fragment，优先于host/port/database/user/password */
+  url: z.union([z.literal("").transform(() => void 0), z.url({ protocol: /^mysql$/ }).refine((value) => !value.includes("?") && !value.includes("#"))]).optional(),
+  /** 数据库：SQLite文件路径或:memory:；PostgreSQL必填名称；MySQL无URL时必填，URL模式从URL读取 */
+  database: z.string().min(1).optional(),
+  /** TLS：PostgreSQL使用其模式；MySQL仅false或严格对象，空对象默认校验证书链和DNS身份 */
+  ssl: MysqlSslConfigSchema.optional(),
+  /** 连接池配置：PostgreSQL支持min/idleTimeout；MySQL仅max/acquireTimeout/queueLimit，拒绝其他字段 */
+  pool: MysqlPoolConfigSchema.optional(),
+  /** MySQL 特定选项 */
+  mysql: MysqlOptionsSchema.optional(),
+  ...OperationLogConfigFieldSchema
+}).refine((config) => Boolean(config.url) || Boolean(config.database), { path: ["database"] });
+var ReldbConfigSchema = z.discriminatedUnion("type", [
+  SqliteConfigSchema,
+  PostgresqlConfigSchema,
+  MysqlConfigSchema
+]);
+
+export { MysqlConfigSchema, MysqlOptionsSchema, MysqlPoolConfigSchema, MysqlSslConfigSchema, PoolConfigSchema, PostgresqlConfigSchema, ReldbConfigSchema, ReldbOperationLogConfigSchema, ReldbTypeSchema, SqliteConfigSchema, SqliteOptionsSchema, SslConfigSchema };
+//# sourceMappingURL=chunk-SDS2ZT3V.js.map
+//# sourceMappingURL=chunk-SDS2ZT3V.js.map