create-windy 0.2.26 → 0.2.28

package/template/packages/database/drizzle/meta/_journal.json

@@ -225,6 +225,13 @@
       "when": 1784837513572,
       "tag": "0031_panoramic_typhoid_mary",
       "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "7",
+      "when": 1784922914250,
+      "tag": "0032_marvelous_pepper_potts",
+      "breakpoints": true
     }
   ]
 }

package/template/packages/database/index.ts

@@ -1,4 +1,5 @@
 export * from "./src/dialects.js";
+export * from "./src/postgres-module-migrations.js";
 export * from "./src/runner.js";
 export * from "./src/schema/index.js";
 export * from "./src/sql-store.js";

package/template/packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/database",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -23,5 +23,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "pg": "^8.22.0"
   }
 }

package/template/packages/database/src/postgres-module-migrations.integration.test.ts

@@ -0,0 +1,170 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  MIGRATION_BUNDLE_FORMAT_VERSION,
+  type MigrationBundle,
+} from "@southwind-ai/shared";
+import { Pool } from "pg";
+import { runPostgresMigrationBundles } from "./postgres-module-migrations.js";
+
+const databaseUrl = process.env.MODULE_MIGRATION_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+
+describePostgres("PostgreSQL Module Migration 启动执行", () => {
+  let pool: Pool;
+
+  beforeAll(() => {
+    pool = new Pool({ connectionString: databaseUrl });
+  });
+
+  afterAll(async () => {
+    await pool?.end();
+  });
+
+  test("并发启动按拓扑串行、记录完整历史、重复幂等并拒绝 checksum 漂移", async () => {
+    const base = bundle("customer-domain", "1.2.0", [
+      migration(
+        "customer-domain",
+        "customer-domain.0040",
+        "create table module_migration_base (id integer primary key)",
+      ),
+    ]);
+    const feature = bundle(
+      "case-domain",
+      "2.0.0",
+      [
+        migration(
+          "case-domain",
+          "case-domain.0041",
+          "create table module_migration_feature (id integer primary key)",
+          ["customer-domain.0040"],
+        ),
+      ],
+      ["customer-domain"],
+    );
+
+    const concurrent = await Promise.all([
+      runPostgresMigrationBundles({ pool, bundles: [feature, base] }),
+      runPostgresMigrationBundles({ pool, bundles: [feature, base] }),
+    ]);
+    expect(concurrent.flatMap(({ applied }) => applied).sort()).toEqual([
+      "case-domain.0041",
+      "customer-domain.0040",
+    ]);
+
+    const history = await pool.query<{
+      id: string;
+      module: string;
+      module_version: string;
+      migration_order: number;
+      checksum: string;
+    }>(
+      `select id, module, module_version, migration_order, checksum
+       from windy_migration_history
+       where id = any($1::text[])
+       order by migration_order`,
+      [["customer-domain.0040", "case-domain.0041"]],
+    );
+    expect(history.rows).toEqual([
+      {
+        id: "customer-domain.0040",
+        module: "customer-domain",
+        module_version: "1.2.0",
+        migration_order: 0,
+        checksum: "sha256:customer-domain.0040",
+      },
+      {
+        id: "case-domain.0041",
+        module: "case-domain",
+        module_version: "2.0.0",
+        migration_order: 1,
+        checksum: "sha256:case-domain.0041",
+      },
+    ]);
+
+    const repeated = await runPostgresMigrationBundles({
+      pool,
+      bundles: [feature, base],
+    });
+    expect(repeated.applied).toEqual([]);
+
+    const driftedBase = bundle("customer-domain", "1.2.0", [
+      {
+        ...base.migrations[0]!,
+        checksum: "sha256:changed",
+      },
+    ]);
+    await expect(
+      runPostgresMigrationBundles({
+        pool,
+        bundles: [driftedBase, feature],
+      }),
+    ).rejects.toThrow("checksum 与当前 Bundle 不一致");
+  });
+
+  test("任一 statement 失败会回滚本次全部 schema 与 history", async () => {
+    const broken = bundle("broken-domain", "1.0.0", [
+      migration(
+        "broken-domain",
+        "broken-domain.0001",
+        "create table module_migration_rollback (id integer primary key)",
+      ),
+      migration(
+        "broken-domain",
+        "broken-domain.0002",
+        "select * from module_migration_missing_relation",
+        ["broken-domain.0001"],
+      ),
+    ]);
+
+    await expect(
+      runPostgresMigrationBundles({ pool, bundles: [broken] }),
+    ).rejects.toThrow("broken-domain.0002");
+    const state = await pool.query<{
+      relation: string | null;
+      history_count: string;
+    }>(
+      `select
+         to_regclass('public.module_migration_rollback')::text as relation,
+         (select count(*)::text from windy_migration_history
+          where module = 'broken-domain') as history_count`,
+    );
+    expect(state.rows[0]).toEqual({
+      relation: null,
+      history_count: "0",
+    });
+  });
+});
+
+function bundle(
+  module: string,
+  version: string,
+  migrations: MigrationBundle["migrations"],
+  dependencies: readonly string[] = [],
+): MigrationBundle {
+  return {
+    formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
+    module,
+    version,
+    dependencies,
+    migrations,
+  };
+}
+
+function migration(
+  module: string,
+  id: string,
+  sql: string,
+  dependsOn: readonly string[] = [],
+): MigrationBundle["migrations"][number] {
+  return {
+    id,
+    module,
+    description: id,
+    direction: "up",
+    checksum: `sha256:${id}`,
+    dependsOn,
+    async run(context) {
+      await context.execute({ sql });
+    },
+  };
+}

package/template/packages/database/src/postgres-module-migrations.ts

@@ -0,0 +1,69 @@
+import type { MigrationBundle } from "@southwind-ai/shared";
+import { PlatformMigrationRunner, type MigrationRunReport } from "./runner.js";
+import {
+  createPostgresStatementExecutor,
+  PostgresMigrationHistoryStore,
+  type QueryableClient,
+} from "./sql-store.js";
+
+const MODULE_MIGRATION_LOCK = "windy.module-migrations.v1";
+
+export interface PostgresTransactionClient extends QueryableClient {
+  release(): void;
+}
+
+export interface PostgresTransactionPool {
+  connect(): Promise<PostgresTransactionClient>;
+}
+
+export interface PostgresMigrationBundleOptions {
+  pool: PostgresTransactionPool;
+  bundles: readonly MigrationBundle[];
+  now?: () => Date;
+}
+
+export async function runPostgresMigrationBundles(
+  options: PostgresMigrationBundleOptions,
+): Promise<MigrationRunReport> {
+  const client = await options.pool.connect();
+  let transactionOpen = false;
+  try {
+    await client.query("begin");
+    transactionOpen = true;
+    await client.query("select pg_advisory_xact_lock(hashtext($1))", [
+      MODULE_MIGRATION_LOCK,
+    ]);
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store: new PostgresMigrationHistoryStore(client),
+      execute: createPostgresStatementExecutor(client),
+      now: options.now,
+      recordFailures: false,
+    });
+    const report = await runner.runBundles(options.bundles);
+    const failure = report.failed[0];
+    if (failure) {
+      throw new Error(
+        `Module Migration ${failure.id} 执行失败：${failure.error}`,
+      );
+    }
+    await client.query("commit");
+    transactionOpen = false;
+    return report;
+  } catch (error) {
+    if (transactionOpen) await rollbackWithoutMasking(client);
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+async function rollbackWithoutMasking(
+  client: PostgresTransactionClient,
+): Promise<void> {
+  try {
+    await client.query("rollback");
+  } catch {
+    // 原始 migration 错误决定启动失败原因，连接释放后由 Pool 负责处置。
+  }
+}

package/template/packages/database/src/runner.test.ts

@@ -141,7 +141,11 @@ describe("PlatformMigrationRunner", () => {
       "select 'feature.001'",
       "select 'feature.002'",
     ]);
-    expect((await store.listApplied())[0]?.checksum).toBe("sha256:system-1");
+    expect((await store.listApplied())[0]).toMatchObject({
+      checksum: "sha256:system-1",
+      moduleVersion: "1.0.0",
+      migrationOrder: 0,
+    });
   });
 
   test("repeat bundle 跳过 checksum 相同的已应用迁移", async () => {

package/template/packages/database/src/runner.ts

@@ -17,11 +17,14 @@ export interface MigrationRunnerOptions {
   store: MigrationHistoryStore;
   execute?: (statement: MigrationStatement) => Promise<void>;
   now?: () => Date;
+  recordFailures?: boolean;
 }
 
 export interface MigrationPlanItem {
   id: string;
   module: string;
+  moduleVersion: string;
+  migrationOrder: number;
   description: string;
   direction: "up" | "down";
   checksum: string;
@@ -62,9 +65,15 @@ export class PlatformMigrationRunner {
   ): Promise<MigrationPlanItem[]> {
     const ordered = validateAndOrderBundles(bundles);
     const applied = appliedById(await this.options.store.listApplied());
+    let migrationOrder = 0;
     return ordered.flatMap((bundle) =>
       orderBundleMigrations(bundle).map((migration) =>
-        planItem(migration, applied.get(migration.id)),
+        planItem(
+          migration,
+          bundle.version,
+          migrationOrder++,
+          applied.get(migration.id),
+        ),
       ),
     );
   }
@@ -119,7 +128,7 @@ export class PlatformMigrationRunner {
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         failed.push({ id: item.id, error: message });
-        if (!dryRun) {
+        if (!dryRun && this.options.recordFailures !== false) {
           await this.recordResult(item, stepStartedAt, stepStatements, message);
         }
         break;
@@ -147,6 +156,8 @@ export class PlatformMigrationRunner {
     await this.options.store.record({
       id: item.id,
       module: item.module,
+      moduleVersion: item.moduleVersion,
+      migrationOrder: item.migrationOrder,
       direction: item.direction,
       status: error ? "failed" : "applied",
       checksum: item.checksum,
@@ -164,6 +175,8 @@ function appliedById(entries: readonly MigrationHistoryEntry[]) {
 
 function planItem(
   migration: BundleMigrationDefinition,
+  moduleVersion: string,
+  migrationOrder: number,
   applied: MigrationHistoryEntry | undefined,
 ): MigrationPlanItem {
   if (applied?.module !== undefined && applied.module !== migration.module) {
@@ -182,6 +195,8 @@ function planItem(
   return {
     id: migration.id,
     module: migration.module,
+    moduleVersion,
+    migrationOrder,
     description: migration.description,
     direction: migration.direction,
     checksum: migration.checksum,

package/template/packages/database/src/schema/migration-history.ts

@@ -1,5 +1,6 @@
 import {
   index,
+  integer,
   jsonb,
   pgTable,
   text,
@@ -12,6 +13,8 @@ export const windyMigrationHistory = pgTable(
   {
     id: varchar("id", { length: 160 }).primaryKey(),
     module: varchar("module", { length: 96 }).notNull(),
+    moduleVersion: varchar("module_version", { length: 64 }),
+    migrationOrder: integer("migration_order"),
     direction: varchar("direction", { length: 16 }).notNull(),
     status: varchar("status", { length: 16 }).notNull(),
     checksum: varchar("checksum", { length: 128 }),

package/template/packages/database/src/sql-store.test.ts

@@ -24,6 +24,8 @@ describe("PostgresMigrationHistoryStore", () => {
         {
           id: "system.001",
           module: "system",
+          module_version: "1.0.0",
+          migration_order: 0,
           direction: "up",
           status: "applied",
           checksum: null,
@@ -39,6 +41,8 @@ describe("PostgresMigrationHistoryStore", () => {
       {
         id: "system.001",
         module: "system",
+        moduleVersion: "1.0.0",
+        migrationOrder: 0,
         direction: "up",
         status: "applied",
         startedAt: "2026-07-09T00:00:00.000Z",
@@ -55,6 +59,8 @@ describe("PostgresMigrationHistoryStore", () => {
     await store.record({
       id: "system.001",
       module: "system",
+      moduleVersion: "1.0.0",
+      migrationOrder: 0,
       direction: "up",
       status: "applied",
       startedAt: "2026-07-09T00:00:00.000Z",
@@ -63,7 +69,7 @@ describe("PostgresMigrationHistoryStore", () => {
     });
 
     expect(client.calls[0]?.sql).toContain("on conflict (id) do update");
-    expect(client.calls[0]?.params?.[5]).toBe(
+    expect(client.calls[0]?.params?.[7]).toBe(
       JSON.stringify(["create table users (id varchar(64))"]),
     );
   });

package/template/packages/database/src/sql-store.ts

@@ -15,6 +15,8 @@ export interface QueryableClient {
 interface MigrationHistoryRow {
   id: string;
   module: string;
+  module_version: string | null;
+  migration_order: number | null;
   direction: "up" | "down";
   status: "applied" | "failed";
   checksum: string | null;
@@ -29,7 +31,8 @@ export class PostgresMigrationHistoryStore implements MigrationHistoryStore {
 
   async listApplied(): Promise<MigrationHistoryEntry[]> {
     const result = await this.client.query<MigrationHistoryRow>(
-      `select id, module, direction, status, checksum, statements, error, started_at, finished_at
+      `select id, module, module_version, migration_order, direction, status,
+              checksum, statements, error, started_at, finished_at
        from windy_migration_history
        where status = $1
        order by finished_at asc`,
@@ -42,10 +45,13 @@ export class PostgresMigrationHistoryStore implements MigrationHistoryStore {
   async record(entry: MigrationHistoryEntry): Promise<void> {
     await this.client.query(
       `insert into windy_migration_history
-         (id, module, direction, status, checksum, statements, error, started_at, finished_at)
-       values ($1, $2, $3, $4, $5, $6::jsonb, $7, $8, $9)
+         (id, module, module_version, migration_order, direction, status,
+          checksum, statements, error, started_at, finished_at)
+       values ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10, $11)
        on conflict (id) do update set
          module = excluded.module,
+         module_version = excluded.module_version,
+         migration_order = excluded.migration_order,
          direction = excluded.direction,
          status = excluded.status,
          checksum = excluded.checksum,
@@ -56,6 +62,8 @@ export class PostgresMigrationHistoryStore implements MigrationHistoryStore {
       [
         entry.id,
         entry.module,
+        entry.moduleVersion || null,
+        entry.migrationOrder ?? null,
         entry.direction,
         entry.status,
         entry.checksum || null,
@@ -86,6 +94,8 @@ function mapHistoryRow(row: MigrationHistoryRow): MigrationHistoryEntry {
   return {
     id: row.id,
     module: row.module,
+    moduleVersion: row.module_version || undefined,
+    migrationOrder: row.migration_order ?? undefined,
     direction: row.direction,
     status: row.status,
     startedAt: toIsoString(row.started_at),

package/template/packages/database/src/store.ts

@@ -5,6 +5,8 @@ export type MigrationStatus = "applied" | "failed";
 export interface MigrationHistoryEntry {
   id: string;
   module: string;
+  moduleVersion?: string;
+  migrationOrder?: number;
   direction: "up" | "down";
   status: MigrationStatus;
   startedAt: ISODateTime;