@southwind-ai/database 0.1.1 → 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.1",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@southwind-ai/shared": "0.1.1",
+    "@southwind-ai/shared": "0.1.2",
     "drizzle-orm": "^0.45.2"
   },
   "exports": {
@@ -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

@@ -1,16 +1,14 @@
-import type {
-  BundleMigrationDefinition,
-  DatabaseCompatibilityAdapter,
-  DatabaseDialect,
-  MigrationBundle,
-  MigrationManifestSource,
-  MigrationStatement,
-} from "@southwind-ai/shared";
 import {
   normalizeManifestBundles,
   orderBundleMigrations,
   validateAndOrderBundles,
-} from "./bundle-validation.js";
+  type BundleMigrationDefinition,
+  type DatabaseCompatibilityAdapter,
+  type DatabaseDialect,
+  type MigrationBundle,
+  type MigrationManifestSource,
+  type MigrationStatement,
+} from "@southwind-ai/shared";
 import { createDialectAdapter } from "./dialects.js";
 import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
 
@@ -19,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;
@@ -64,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),
+        ),
       ),
     );
   }
@@ -121,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;
@@ -149,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,
@@ -166,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) {
@@ -184,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/schema/platform-settings.ts

@@ -2,7 +2,10 @@
 export {};
 
 // @windy-module system.configuration begin
-import type { ModuleConfigDiffEntry, ModuleConfigValues } from "@southwind-ai/shared";
+import type {
+  ModuleConfigDiffEntry,
+  ModuleConfigValues,
+} from "@southwind-ai/shared";
 import {
   index,
   integer,
@@ -15,6 +18,7 @@ import {
 // @windy-module system.configuration end
 // @windy-module system.settings begin
 import {
+  boolean,
   pgTable as settingsTable,
   text,
   varchar as settingsVarchar,
@@ -33,6 +37,17 @@ export const platformBrandingSettings = settingsTable(
     ...auditColumns,
   },
 );
+
+export const platformWatermarkPolicies = settingsTable(
+  "platform_watermark_policies",
+  {
+    id: settingsVarchar("id", { length: 64 }).primaryKey(),
+    enabled: boolean("enabled").notNull(),
+    businessPagesEnabled: boolean("business_pages_enabled").notNull(),
+    customContent: settingsVarchar("custom_content", { length: 80 }).notNull(),
+    ...auditColumns,
+  },
+);
 // @windy-module system.settings end
 
 // @windy-module system.configuration begin

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;

package/src/bundle-validation.ts

@@ -1,218 +0,0 @@
-import {
-  MIGRATION_BUNDLE_FORMAT_VERSION,
-  type BundleMigrationDefinition,
-  type MigrationBundle,
-  type MigrationDefinition,
-  type MigrationManifestSource,
-} from "@southwind-ai/shared";
-
-export function normalizeManifestBundles(
-  modules: readonly MigrationManifestSource[],
-): MigrationBundle[] {
-  return modules.map((manifest) => {
-    const bundle =
-      manifest.migrationBundle ||
-      legacyManifestBundle(manifest, manifest.migrations);
-    if (bundle.module !== manifest.name) {
-      throw new Error(
-        `Migration Bundle ${bundle.module} 与 Manifest ${manifest.name} 不一致`,
-      );
-    }
-    if (bundle.version !== manifest.version) {
-      throw new Error(
-        `Migration Bundle ${bundle.module} 版本 ${bundle.version} 与 Manifest ${manifest.version} 不一致`,
-      );
-    }
-    assertSameDependencies(manifest, bundle);
-    assertSameMigrations(manifest, bundle);
-    assertSchemaMigrationReferences(manifest, bundle);
-    return bundle;
-  });
-}
-
-function assertSameDependencies(
-  manifest: MigrationManifestSource,
-  bundle: MigrationBundle,
-): void {
-  const declared = manifest.dependencies || [];
-  const bundled = bundle.dependencies || [];
-  if (
-    declared.length !== bundled.length ||
-    declared.some((dependency) => !bundled.includes(dependency))
-  ) {
-    throw new Error(
-      `Manifest ${manifest.name} 的 dependencies 必须与 Migration Bundle 一致`,
-    );
-  }
-}
-
-function legacyManifestBundle(
-  manifest: MigrationManifestSource,
-  migrations: readonly MigrationDefinition[],
-): MigrationBundle {
-  return {
-    formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
-    module: manifest.name,
-    version: manifest.version,
-    dependencies: manifest.dependencies,
-    migrations: migrations.map((migration) => ({
-      ...migration,
-      checksum:
-        migration.checksum ||
-        `legacy:${manifest.name}:${manifest.version}:${migration.id}`,
-    })),
-  };
-}
-
-function assertSameMigrations(
-  manifest: MigrationManifestSource,
-  bundle: MigrationBundle,
-): void {
-  const declared = manifest.migrations.map(({ id }) => id);
-  const bundled = bundle.migrations.map(({ id }) => id);
-  if (
-    declared.length !== bundled.length ||
-    declared.some((id, index) => id !== bundled[index])
-  ) {
-    throw new Error(
-      `Manifest ${manifest.name} 的 migrations 必须与 Migration Bundle 完全一致`,
-    );
-  }
-}
-
-function assertSchemaMigrationReferences(
-  manifest: MigrationManifestSource,
-  bundle: MigrationBundle,
-): void {
-  const ids = new Set(bundle.migrations.map(({ id }) => id));
-  for (const schema of manifest.schemaExports || []) {
-    for (const migrationId of schema.migrationIds) {
-      if (!ids.has(migrationId)) {
-        throw new Error(
-          `Schema Export ${schema.key} 引用了 Bundle 中不存在的 Migration：${migrationId}`,
-        );
-      }
-    }
-  }
-}
-
-export function validateAndOrderBundles(
-  bundles: readonly MigrationBundle[],
-): MigrationBundle[] {
-  const byModule = new Map<string, MigrationBundle>();
-  const migrationOwner = new Map<string, string>();
-  for (const bundle of bundles) {
-    validateBundle(bundle);
-    if (byModule.has(bundle.module)) {
-      throw new Error(`Migration Bundle 模块重复：${bundle.module}`);
-    }
-    byModule.set(bundle.module, bundle);
-    for (const migration of bundle.migrations) {
-      const owner = migrationOwner.get(migration.id);
-      if (owner) {
-        throw new Error(
-          `Migration ID 重复：${migration.id}（${owner} / ${bundle.module}）`,
-        );
-      }
-      migrationOwner.set(migration.id, bundle.module);
-    }
-  }
-  for (const bundle of bundles) {
-    for (const dependency of bundle.dependencies || []) {
-      if (!byModule.has(dependency)) {
-        throw new Error(
-          `Migration Bundle ${bundle.module} 依赖未安装模块：${dependency}`,
-        );
-      }
-    }
-    validateMigrationDependencies(bundle, migrationOwner);
-  }
-  return topologicalBundles(byModule);
-}
-
-function validateBundle(bundle: MigrationBundle): void {
-  if (bundle.formatVersion !== MIGRATION_BUNDLE_FORMAT_VERSION) {
-    throw new Error(
-      `Migration Bundle ${bundle.module} 格式版本不受支持：${bundle.formatVersion}`,
-    );
-  }
-  if (!bundle.module.trim()) throw new Error("Migration Bundle 缺少 module");
-  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(bundle.version)) {
-    throw new Error(
-      `Migration Bundle ${bundle.module} 版本无效：${bundle.version}`,
-    );
-  }
-  for (const migration of bundle.migrations) {
-    if (migration.module !== bundle.module) {
-      throw new Error(
-        `Migration ${migration.id} 的模块归属应为 ${bundle.module}`,
-      );
-    }
-    if (!migration.id.trim()) throw new Error("Migration ID 不能为空");
-    if (!migration.checksum.trim()) {
-      throw new Error(`Migration ${migration.id} 缺少 checksum`);
-    }
-  }
-}
-
-function validateMigrationDependencies(
-  bundle: MigrationBundle,
-  owners: ReadonlyMap<string, string>,
-): void {
-  for (const migration of bundle.migrations) {
-    for (const dependency of migration.dependsOn || []) {
-      const owner = owners.get(dependency);
-      if (!owner) {
-        throw new Error(`Migration ${migration.id} 依赖不存在：${dependency}`);
-      }
-      if (
-        owner !== bundle.module &&
-        !(bundle.dependencies || []).includes(owner)
-      ) {
-        throw new Error(
-          `Migration ${migration.id} 跨模块依赖 ${owner}，但 Bundle 未声明该模块依赖`,
-        );
-      }
-    }
-  }
-}
-
-function topologicalBundles(
-  pendingSource: ReadonlyMap<string, MigrationBundle>,
-): MigrationBundle[] {
-  const pending = new Map(pendingSource);
-  const sorted: MigrationBundle[] = [];
-  while (pending.size > 0) {
-    const ready = Array.from(pending.values()).find((bundle) =>
-      (bundle.dependencies || []).every(
-        (dependency) => !pending.has(dependency),
-      ),
-    );
-    if (!ready) throw new Error("Migration Bundle 模块依赖存在循环");
-    sorted.push(ready);
-    pending.delete(ready.module);
-  }
-  return sorted;
-}
-
-export function orderBundleMigrations(
-  bundle: MigrationBundle,
-): BundleMigrationDefinition[] {
-  const pending = new Map(
-    bundle.migrations.map((migration) => [migration.id, migration]),
-  );
-  const sorted: BundleMigrationDefinition[] = [];
-  while (pending.size > 0) {
-    const ready = Array.from(pending.values()).find((migration) =>
-      (migration.dependsOn || []).every(
-        (dependency) => !pending.has(dependency),
-      ),
-    );
-    if (!ready) {
-      throw new Error(`Migration Bundle ${bundle.module} 的迁移依赖存在循环`);
-    }
-    sorted.push(ready);
-    pending.delete(ready.id);
-  }
-  return sorted;
-}