@southwind-ai/database 0.1.2 → 0.1.3

package/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/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/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/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/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/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/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;