@h-ai/reldb 1.0.0-beta.22 → 1.0.0-beta.24

package/README.en.md

@@ -113,10 +113,9 @@ Pagination: normalize accepts page options and limits and returns normalized opt
 
 Prepare module persistence: table name returns columns; module name, steps and dryRun return a migration plan. Back up and stop conflicting writers before applying.
 
-| Entry                 | Input parameters       | Successful result     | Call example                                                            |
-| --------------------- | ---------------------- | --------------------- | ----------------------------------------------------------------------- |
-| `reldb.schemaColumns` | table, sql             | `string[]`            | `await reldb.schemaColumns('orders')`                                   |
-| `reldb.migrateSchema` | module, steps, options | `SchemaMigrationPlan` | `await reldb.migrateSchema('orders', migrationSteps, { dryRun: true })` |
+| Entry                 | Input parameters | Successful result | Call example                          |
+| --------------------- | ---------------- | ----------------- | ------------------------------------- |
+| `reldb.schemaColumns` | table, sql       | `string[]`        | `await reldb.schemaColumns('orders')` |
 
 #### reldb.tx
 
@@ -603,9 +602,9 @@ await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...
 
 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
+### Inspect table structure
 
-`reldb.schemaColumns(table, sql?)` inspects real columns. `reldb.migrateSchema(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).
+`reldb.schemaColumns(table, sql?)` reads the actual column names. Pass the transaction SQL handle to inspect the structure within the current transaction. Framework modules validate their own schemas during initialization. Applications manage their business tables.
 
 ## Configuration
 

package/README.ja.md

@@ -113,10 +113,9 @@ params で値を束縛して業務データを操作。順に行配列、先頭
 
 永続化の準備。テーブル名から列名、モジュール名・手順・dryRun から移行計画を取得。適用前にバックアップし競合書込を停止。
 
-| 入口                  | 入力引数               | 成功結果              | 呼出し例                                                                |
-| --------------------- | ---------------------- | --------------------- | ----------------------------------------------------------------------- |
-| `reldb.schemaColumns` | table, sql             | `string[]`            | `await reldb.schemaColumns('orders')`                                   |
-| `reldb.migrateSchema` | module, steps, options | `SchemaMigrationPlan` | `await reldb.migrateSchema('orders', migrationSteps, { dryRun: true })` |
+| 入口                  | 入力引数   | 成功結果   | 呼出し例                              |
+| --------------------- | ---------- | ---------- | ------------------------------------- |
+| `reldb.schemaColumns` | table, sql | `string[]` | `await reldb.schemaColumns('orders')` |
 
 #### reldb.tx
 
@@ -603,9 +602,9 @@ await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...
 
 本番は PostgreSQL/MySQL が必須です。ファイルを含む SQLite は開発・明示的テスト用であり、ホスト間の共有状態を保証しません。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲（中国語）](../../.agents/instructions/distributed-state.md).
 
-### モジュールのスキーマ移行
+### テーブル構造の確認
 
-`reldb.schemaColumns(table, sql?)` は実際の列を読み取ります。`reldb.migrateSchema(module, steps, { dryRun: true })` は台帳を作成しません。各モジュールが手順を所有し、`hai_schema_migrations` に版を記録します。SQLite/PostgreSQL はトランザクション、MySQL の暗黙 DDL コミットには再入可能な手順が必要です。失敗時は版を進めず、実構造を再確認して再試行します。新しい台帳へのダウングレードは拒否します。旧書込を停止し DB/セッションキャッシュをバックアップしてください。復旧は互換 DB とバイナリを一緒に戻します。[更新ガイド](../../docs/usage/README.ja.md)を参照。
+`reldb.schemaColumns(table, sql?)` で実際の列名を読み取れます。トランザクションの SQL ハンドルを渡すと、同じトランザクション内で構造を確認できます。各フレームワークモジュールは初期化時に自身のテーブル構造を検証し、業務テーブルはアプリが管理します。
 
 ## 設定
 

package/README.md

@@ -113,10 +113,9 @@ table/column/index 名必须来自可信代码；sql 是可信语句，params
 
 模块持久化准备。输入表名得到列名数组；输入模块名、迁移步骤和 dryRun 得到迁移计划。执行前备份并停止冲突写入。
 
-| 入口                  | 输入参数               | 成功结果              | 调用示例                                                                |
-| --------------------- | ---------------------- | --------------------- | ----------------------------------------------------------------------- |
-| `reldb.schemaColumns` | table, sql             | `string[]`            | `await reldb.schemaColumns('orders')`                                   |
-| `reldb.migrateSchema` | module, steps, options | `SchemaMigrationPlan` | `await reldb.migrateSchema('orders', migrationSteps, { dryRun: true })` |
+| 入口                  | 输入参数   | 成功结果   | 调用示例                              |
+| --------------------- | ---------- | ---------- | ------------------------------------- |
+| `reldb.schemaColumns` | table, sql | `string[]` | `await reldb.schemaColumns('orders')` |
 
 #### reldb.tx
 
@@ -603,9 +602,9 @@ await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...
 
 生产仅使用 PostgreSQL/MySQL；SQLite（含磁盘文件）只用于开发/明确测试，不能作为跨主机共享状态。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验；仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md).
 
-### 模块架构迁移
+### 检查数据表结构
 
-`reldb.schemaColumns(table, sql?)` 只读检查真实结构；`reldb.migrateSchema(module, steps, { dryRun: true })` 不创建账本。版本步骤由所属模块维护，业务不修改框架内部表。执行使用 `hai_schema_migrations`，SQLite/PostgreSQL 整体事务，MySQL DDL 隐式提交因此步骤必须可重入；失败不推进版本，重新检查真实结构后续做，拒绝向低版本降级。升级前停止所有旧写入并备份 DB/会话缓存；回退需恢复兼容数据库与旧代码，不能只换二进制。详见 [升级指南](../../docs/usage/README.md).
+`reldb.schemaColumns(table, sql?)` 只读查询实际列名。传入当前事务的 SQL 操作句柄，可在同一事务中检查表结构。框架模块初始化时校验各自的表结构，业务表由应用管理。
 
 ## 配置
 

package/dist/index.d.ts

@@ -192,38 +192,6 @@ declare function parseJsonPath(path: string): string[];
  */
 declare function createJsonOps(dbType: 'sqlite' | 'postgresql' | 'mysql'): ReldbJsonOps;
 
-/** 模块维护自己的迁移；这里只提供跨数据库列检查、版本账本和执行边界。 */
-
-/**
- * 一个可重入的模块升级步骤；只接收代码中固定的 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;
-}
-
 /**
  * HaiReldbError 的数据约束与操作契约。
  * @example
@@ -240,7 +208,6 @@ declare const HaiReldbError: {
     QUERY_FAILED: _h_ai_core.HaiErrorDef;
     CONSTRAINT_VIOLATION: _h_ai_core.HaiErrorDef;
     TRANSACTION_FAILED: _h_ai_core.HaiErrorDef;
-    MIGRATION_FAILED: _h_ai_core.HaiErrorDef;
     RECORD_NOT_FOUND: _h_ai_core.HaiErrorDef;
     DUPLICATE_ENTRY: _h_ai_core.HaiErrorDef;
     DEADLOCK: _h_ai_core.HaiErrorDef;
@@ -989,18 +956,6 @@ interface ReldbFunctions {
     readonly crud: CrudManager;
     /** 事务管理器 */
     readonly tx: TxManager;
-    /**
-     * 预检或执行模块维护的版本迁移；绑定当前数据库，不接受其它模块实例。
-     * @example
-     * ```ts
-     * import { reldb } from '@h-ai/reldb'
-     * const plan = await reldb.migrateSchema('example', [], { dryRun: true })
-     * if (!plan.success) throw new Error(plan.error.message)
-     * ```
-     */
-    migrateSchema: (module: string, steps: readonly SchemaMigration[], options?: {
-        dryRun?: boolean;
-    }) => Promise<HaiResult<SchemaMigrationPlan>>;
     /**
      * 只读查询当前数据库真实列名；sql 可指定当前事务，不创建表。
      * @example
@@ -1216,6 +1171,8 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
      * @returns 初始化结果
      */
     protected ensureReady(): Promise<HaiResult<void>>;
+    /** 验证框架仓库使用当前字段定义，结构不符时停止发布仓库。 */
+    protected ensureSchema(): Promise<HaiResult<void>>;
     /**
      * 创建单条记录
      *
@@ -1590,4 +1547,4 @@ declare function quoteIdentifier(name: string): string;
 declare function escapeSqlString(value: string): string;
 
 export { BaseReldbCrudRepository, DbType, HaiReldbError, ReldbConfig, ReldbConfigInput, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };
-export type { BaseReldbCrudRepositoryConfig, ColumnType, CrudConfig, CrudManager, CrudPageOptions, CrudQueryOptions, DdlOperations, DmlOperations, DmlWithTxOperations, ExecuteResult, JsonSqlExpr, NormalizedPagination, PaginationOverrides, PaginationQueryOptions, QueryRow, ReldbColumnDef, ReldbCrudCountOptions, ReldbCrudFieldDefinition, ReldbCrudRepository, ReldbFunctions, ReldbIndexDef, ReldbJsonOps, ReldbTableDef, SchemaMigration, SchemaMigrationPlan, TxManager, TxWrapCallback };
+export type { BaseReldbCrudRepositoryConfig, ColumnType, CrudConfig, CrudManager, CrudPageOptions, CrudQueryOptions, DdlOperations, DmlOperations, DmlWithTxOperations, ExecuteResult, JsonSqlExpr, NormalizedPagination, PaginationOverrides, PaginationQueryOptions, QueryRow, ReldbColumnDef, ReldbCrudCountOptions, ReldbCrudFieldDefinition, ReldbCrudRepository, ReldbFunctions, ReldbIndexDef, ReldbJsonOps, ReldbTableDef, TxManager, TxWrapCallback };

package/dist/index.js

@@ -16,6 +16,7 @@ var en_US_default = {
   reldb_initFailed: "Failed to initialize database",
   reldb_closeFailed: "Failed to close database",
   reldb_ddlFailed: "DDL operation failed",
+  reldb_schemaMismatch: "Table {table} does not match its current schema",
   reldb_queryFailed: "Query failed",
   reldb_duplicateEntry: "Record already exists",
   reldb_batchFailed: "Batch execute failed",
@@ -51,6 +52,7 @@ var ja_JP_default = {
   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_schemaMismatch: "\u30C6\u30FC\u30D6\u30EB {table} \u304C\u73FE\u5728\u306E\u30B9\u30AD\u30FC\u30DE\u5B9A\u7FA9\u3068\u4E00\u81F4\u3057\u307E\u305B\u3093",
   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",
@@ -86,6 +88,7 @@ var zh_CN_default = {
   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_schemaMismatch: "\u6570\u636E\u8868 {table} \u4E0E\u5F53\u524D\u7ED3\u6784\u5B9A\u4E49\u4E0D\u7B26",
   reldb_queryFailed: "\u67E5\u8BE2\u5931\u8D25",
   reldb_duplicateEntry: "\u8BB0\u5F55\u5DF2\u5B58\u5728",
   reldb_batchFailed: "\u6279\u91CF\u6267\u884C\u5931\u8D25",
@@ -126,7 +129,6 @@ var ReldbErrorInfo = {
   QUERY_FAILED: "002:500",
   CONSTRAINT_VIOLATION: "003:409",
   TRANSACTION_FAILED: "004:500",
-  MIGRATION_FAILED: "005:500",
   RECORD_NOT_FOUND: "006:404",
   DUPLICATE_ENTRY: "007:409",
   DEADLOCK: "008:500",
@@ -473,6 +475,22 @@ var BaseReldbCrudRepository = class {
     }
     return ok(void 0);
   }
+  /** 验证框架仓库使用当前字段定义，结构不符时停止发布仓库。 */
+  async ensureSchema() {
+    const ready = await this.ensureReady();
+    if (!ready.success)
+      return ready;
+    const columns = await this.db.schemaColumns(this.table);
+    if (!columns.success)
+      return columns;
+    const names = new Set(columns.data);
+    if (names.size !== this.fields.length || this.fields.some((field) => !names.has(field.columnName))) {
+      return err(HaiReldbError.DDL_FAILED, reldbM("reldb_schemaMismatch", {
+        params: { table: this.table }
+      }));
+    }
+    return ok(void 0);
+  }
   /**
    * 创建单条记录
    *
@@ -3363,106 +3381,6 @@ async function schemaColumns(db, table, sql = db.sql) {
   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();
-  }
-}
 
 // src/reldb-main.ts
 var logger5 = core.logger.child({ module: "reldb", scope: "main" });
@@ -3648,12 +3566,6 @@ var reldb = {
   get tx() {
     return currentProvider?.tx ?? notInitializedTx;
   },
-  /** 迁移操作绑定当前实例，调用方只提供模块自己的步骤。 */
-  migrateSchema(module, steps, options) {
-    if (!currentProvider)
-      return Promise.resolve(notInitialized.result());
-    return migrateSchema(reldb, module, steps, options);
-  },
   /** 列检查复用当前连接或显式传入的事务。 */
   schemaColumns(table, sql) {
     if (!currentProvider)