@h-ai/reldb 0.1.0-alpha.70 → 0.1.0-alpha.72

package/README.en.md

@@ -594,6 +594,18 @@ Custom SQL methods in `BaseReldbCrudRepository` subclasses must check `await thi
 
 Production requires PostgreSQL/MySQL. SQLite, including disk files, is for development/explicit tests and does not provide cross-host shared state. Initialization checks apply when NODE_ENV or HAI_CORE_ENV is production; only explicit HAI_E2E=1/HAI_E2E_MOCK=1 tests are exempt. [State, concurrency and recovery (Chinese)](../../.agents/instructions/distributed-state.md)。
 
+## Module schema migrations
+
+`schemaColumns(reldb, table, sql?)` inspects real columns. `migrateSchema(reldb, module, steps, { dryRun: true })` creates no ledger. Modules own their steps. Execution journals versions in `hai_schema_migrations`; SQLite/PostgreSQL are transactional, while MySQL implicit DDL commits require reentrant steps. Failures do not advance versions; retries inspect real state. Older code rejects newer ledgers. Stop old writers and back up DB/session cache first. Rollback restores compatible database and binaries together. See the [upgrade guide](../../docs/usage/README.en.md).
+
+## Error messages and correlated logs
+
+Unique constraint violations return `HaiReldbError.DUPLICATE_ENTRY` (409); timeout, pool exhaustion and other existing error codes remain intact. Branch on error codes rather than localized messages or driver text. Logs preserve driver code/schema/routine/constraint and stack line numbers; numeric bound values do not obscure these diagnostic identifiers.
+
+HTTP errors expose localized safe messages followed by `(traceId: …)`, with the same ID in `error.traceId` and `X-Trace-Id`. The framework reuses the request ID to correlate browser and server logs. Sanitized exceptions, stacks and operation context remain in logs; internal cause/ext are not exposed. Field validation returns localized field names and messages only.
+
+Use `core.error.toPublic(error, traceId?)` at HTTP/UI boundaries and `core.error.formatMessage(error)` after translating messages; formatting is idempotent. Pass complete Error objects to logs instead of discarding their context. Database failures log driver codes, sanitized messages/stacks and table/column context; SQL text, bound values and connection credentials are excluded.
+
 ## Development and testing
 
 ```bash

package/README.ja.md

@@ -594,6 +594,18 @@ if (!result.success) {
 
 本番は 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/セッションキャッシュをバックアップしてください。復旧は互換 DB とバイナリを一緒に戻します。[更新ガイド](../../docs/usage/README.ja.md)を参照。
+
+## エラー表示とログの関連付け
+
+一意制約違反は `HaiReldbError.DUPLICATE_ENTRY`（409）に統一し、タイムアウトや待機列満杯など既存のコードは保持します。翻訳済みメッセージやドライバー文字列ではなくコードで分岐してください。ログには code/schema/routine/constraint とスタック行番号を残し、数値のバインド値でこれらの診断識別子を隠しません。
+
+HTTP エラーはローカライズ済みの安全な表示に `(traceId: …)` を付け、同じ ID を error.traceId と X-Trace-Id に返します。requestId を traceId として共有し、ブラウザーとサーバーのログを関連付けます。脱機密化した例外・スタック・操作情報はログに残し、内部 cause/ext は公開しません。項目検証は翻訳済みの項目名とメッセージだけを返します。
+
+HTTP/UI 境界には core.error.toPublic(error, traceId?)、再翻訳後の表示には core.error.formatMessage(error) を使い、ID を重複追加しません。ログには完全な Error を渡してください。DB ログにはドライバーコード、脱機密化したメッセージ・スタック、表・列を残し、SQL 本文、バインド値と接続認証情報を記録しません。
+
 ## 開発とテスト
 
 ```bash

package/README.md

@@ -594,6 +594,18 @@ if (!result.success) {
 
 生产仅使用 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 错误只向用户返回本地化的安全提示，末尾显示 `(traceId: …)`；响应同时包含 `error.traceId` 和 `X-Trace-Id`。框架复用本次 requestId 作为 traceId，前后端日志自动关联。底层异常、堆栈和操作上下文经凭据脱敏后写入日志，不通过 cause/ext 向用户公开。字段校验只返回本地化的字段名和错误。
+
+`core.error.toPublic(error, traceId?)` 用于接口/UI 边界；`core.error.formatMessage(error)` 用于重新翻译后的提示，重复调用不会重复追加标识。日志传入完整 Error 对象，不能只记录通用标题或提前 String(error) 丢失上下文。数据库失败记录驱动错误码、消息、堆栈及表/列；SQL 原文、绑定值和连接凭据不进入日志。
+
 ## 开发测试
 
 ```bash

package/dist/index.d.ts

@@ -1458,6 +1458,59 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
  */
 declare const reldb: ReldbFunctions;
 
+/** 模块维护自己的迁移；这里只提供跨数据库列检查、版本账本和执行边界。 */
+
+/**
+ * 一个可重入的模块升级步骤；只接收代码中固定的 SQL 与表名。
+ * @example
+ * ```ts
+ * import type { SchemaMigration } from '@h-ai/reldb'
+ * const steps: SchemaMigration[] = []
+ * ```
+ */
+interface SchemaMigration {
+    version: number;
+    name: string;
+    needed: (sql: DmlOperations) => Promise<HaiResult<boolean>>;
+    apply: (sql: DmlOperations) => Promise<HaiResult<unknown>>;
+}
+/**
+ * 只读预检结果；生产升级需先停旧写入并备份数据库与共享缓存。
+ * @example
+ * ```ts
+ * import type { SchemaMigrationPlan } from '@h-ai/reldb'
+ * function changes(plan: SchemaMigrationPlan) { return plan.changes }
+ * ```
+ */
+interface SchemaMigrationPlan {
+    module: string;
+    currentVersion: number;
+    targetVersion: number;
+    changes: string[];
+    requiresExclusiveAccess: boolean;
+}
+/**
+ * 查询真实列名；不创建表，不把查询错误当成新安装。
+ * @example
+ * ```ts
+ * import { reldb, schemaColumns } from '@h-ai/reldb'
+ * const columns = await schemaColumns(reldb, 'hai_iam_users')
+ * ```
+ */
+declare function schemaColumns(db: ReldbFunctions, table: string, sql?: DmlOperations): Promise<HaiResult<string[]>>;
+/**
+ * 预检或执行模块维护的版本迁移。SQLite/PostgreSQL 原子提交；MySQL DDL 隐式提交，步骤须可重入。
+ * 失败不记录目标版本；重启重新检查真实结构。新版本账本拒绝旧代码向下迁移。
+ * @example
+ * ```ts
+ * import { reldb, migrateSchema } from '@h-ai/reldb'
+ * const plan = await migrateSchema(reldb, 'example', [], { dryRun: true })
+ * ```
+ */
+declare function migrateSchema(db: ReldbFunctions, module: string, steps: readonly SchemaMigration[], options?: {
+    dryRun?: boolean;
+}): Promise<HaiResult<SchemaMigrationPlan>>;
+
 /**
  * @h-ai/reldb — 安全工具
  *
@@ -1535,4 +1588,4 @@ declare function quoteIdentifier(name: string): string;
  */
 declare function escapeSqlString(value: string): string;
 
-export { BaseReldbCrudRepository, type BaseReldbCrudRepositoryConfig, type ColumnType, type CrudConfig, type CrudManager, type CrudPageOptions, type CrudQueryOptions, DbType, type DdlOperations, type DmlOperations, type DmlWithTxOperations, type ExecuteResult, HaiReldbError, type JsonSqlExpr, type NormalizedPagination, type PaginationOverrides, type PaginationQueryOptions, type QueryRow, type ReldbColumnDef, ReldbConfig, ReldbConfigInput, type ReldbCrudCountOptions, type ReldbCrudFieldDefinition, type ReldbCrudRepository, type ReldbFunctions, type ReldbIndexDef, type ReldbJsonOps, type ReldbTableDef, type TxManager, type TxWrapCallback, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };
+export { BaseReldbCrudRepository, type BaseReldbCrudRepositoryConfig, type ColumnType, type CrudConfig, type CrudManager, type CrudPageOptions, type CrudQueryOptions, DbType, type DdlOperations, type DmlOperations, type DmlWithTxOperations, type ExecuteResult, HaiReldbError, type JsonSqlExpr, type NormalizedPagination, type PaginationOverrides, type PaginationQueryOptions, type QueryRow, type ReldbColumnDef, ReldbConfig, ReldbConfigInput, type ReldbCrudCountOptions, type ReldbCrudFieldDefinition, type ReldbCrudRepository, type ReldbFunctions, type ReldbIndexDef, type ReldbJsonOps, type ReldbTableDef, type SchemaMigration, type SchemaMigrationPlan, type TxManager, type TxWrapCallback, createJsonOps, escapeSqlString, migrateSchema, parseJsonPath, quoteIdentifier, reldb, schemaColumns, validateIdentifier, validateIdentifiers };

package/dist/index.js

@@ -1,6 +1,6 @@
 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 } from '@h-ai/core';
+import { core, ok, err, HaiCommonError } from '@h-ai/core';
 import process from 'process';
 import { createRequire } from 'module';
 import { isIP } from 'net';
@@ -13,22 +13,23 @@ import { Worker } from 'worker_threads';
 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",
@@ -37,8 +38,8 @@ var en_US_default = {
   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"
 };
@@ -47,22 +48,23 @@ var en_US_default = {
 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: {error}",
-  reldb_closeFailed: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u7D42\u4E86\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
-  reldb_ddlFailed: "DDL\u64CD\u4F5C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
-  reldb_queryFailed: "\u30AF\u30A8\u30EA\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
-  reldb_batchFailed: "\u30D0\u30C3\u30C1\u5B9F\u884C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
-  reldb_postgresTxFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  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: {error}",
+  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: {error}",
-  reldb_sqliteTxFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
-  reldb_sqliteBatchFailed: "\u30D0\u30C3\u30C1\u5B9F\u884C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  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: {error}",
-  reldb_mysqlTxFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  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",
@@ -71,8 +73,8 @@ var ja_JP_default = {
   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: {error}",
-  reldb_txFailed: "\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  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"
 };
@@ -81,22 +83,23 @@ var ja_JP_default = {
 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",
@@ -105,8 +108,8 @@ var zh_CN_default = {
   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"
 };
@@ -1592,11 +1595,57 @@ 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, { ...summarizeOperationPayload(errorMeta), errorCode: errorDef.code });
-    return err(errorDef, reldbM("reldb_queryFailed", { params: { error: String(error) } }), error);
+    return failed(error);
   }
 }
 function createBaseDdlOps(ctx, raw) {
@@ -1670,7 +1719,7 @@ function createBaseDdlOps(ctx, raw) {
     },
     raw(sql) {
       logReldbOperation(ctx, "write", "ddl.raw", { sql });
-      return wrapOp(ctx, () => raw.raw(sql), HaiReldbError.DDL_FAILED, "DDL: raw failed");
+      return wrapOp(ctx, () => raw.raw(sql), HaiReldbError.DDL_FAILED, "DDL: raw failed", { sql });
     }
   };
 }
@@ -1678,23 +1727,23 @@ function createBaseDmlOps(ctx, raw) {
   return {
     query: (sql, params) => {
       logReldbOperation(ctx, "read", "query", { sql, params });
-      return wrapOp(ctx, () => raw.query(sql, params), HaiReldbError.QUERY_FAILED, "DML: query failed");
+      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");
+      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");
+      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");
+      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");
+      return wrapOp(ctx, () => raw.queryPage(options), HaiReldbError.QUERY_FAILED, "DML: queryPage failed", { ...options });
     }
   };
 }
@@ -3363,7 +3412,99 @@ var reldb = {
     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 = () => err({ ...HaiCommonError.INIT_FAILED, message: core.i18n.coreM("core_runtimeStartFailed", { params: { module } }), ext: { module, phase: "migration" } });
+  async function inspect(sql) {
+    const columns = await schemaColumns(db, table, sql);
+    if (!columns.success)
+      return failed();
+    const row = columns.data.length ? await sql.get(`SELECT version FROM ${table} WHERE module=?`, [module]) : ok(null);
+    if (!row.success)
+      return failed();
+    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();
+      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();
+  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();
+  const started = await db.tx.begin();
+  if (!started.success)
+    return failed();
+  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();
+      mysqlLock = true;
+    }
+    const locked = await tx.execute(`UPDATE ${table} SET version=version WHERE module=?`, [module]);
+    if (!locked.success)
+      return failed();
+    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();
+      if (needed.data) {
+        const applied = await step.apply(tx);
+        if (!applied.success)
+          return failed();
+        const remaining = await step.needed(tx);
+        if (!remaining.success || remaining.data)
+          return failed();
+      }
+    }
+    const recorded = await tx.execute(`UPDATE ${table} SET version=? WHERE module=?`, [targetVersion, module]);
+    if (!recorded.success)
+      return failed();
+    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();
+  } catch {
+    return failed();
+  } finally {
+    if (mysqlLock)
+      await tx.get("SELECT RELEASE_LOCK(?)", [`hai-schema:${module}`]);
+    if (!committed)
+      await tx.rollback();
+  }
+}
 
-export { BaseReldbCrudRepository, HaiReldbError, 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