@southwind-ai/database 0.1.0

package/index.ts

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

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@southwind-ai/database",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@southwind-ai/shared": "workspace:*",
+    "drizzle-orm": "^0.45.2"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bundle-validation.ts

@@ -0,0 +1,218 @@
+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;
+}

package/src/dialects.ts

@@ -0,0 +1,139 @@
+import type {
+  ColumnTypeMapping,
+  DatabaseCompatibilityAdapter,
+  DatabaseDialect,
+  DialectCapabilities,
+  PageRequest,
+  PaginationSqlParts,
+} from "@southwind-ai/shared";
+
+const reservedWords: Record<DatabaseDialect, string[]> = {
+  postgresql: ["user", "role", "order"],
+  mysql: ["user", "role", "order"],
+  dm: ["user", "role", "order", "limit"],
+  kingbase: ["user", "role", "order", "limit"],
+};
+
+const capabilities: Record<DatabaseDialect, DialectCapabilities> = {
+  postgresql: {
+    dialect: "postgresql",
+    identifierStrategy: "identity",
+    jsonColumnStrategy: "jsonb",
+    supportsReturning: true,
+    supportsRecursiveCte: true,
+    supportsFullTextSearch: true,
+    reservedWords: reservedWords.postgresql,
+  },
+  mysql: {
+    dialect: "mysql",
+    identifierStrategy: "auto-increment",
+    jsonColumnStrategy: "json",
+    supportsReturning: false,
+    supportsRecursiveCte: true,
+    supportsFullTextSearch: true,
+    reservedWords: reservedWords.mysql,
+  },
+  dm: {
+    dialect: "dm",
+    identifierStrategy: "sequence",
+    jsonColumnStrategy: "text",
+    supportsReturning: false,
+    supportsRecursiveCte: true,
+    supportsFullTextSearch: false,
+    reservedWords: reservedWords.dm,
+  },
+  kingbase: {
+    dialect: "kingbase",
+    identifierStrategy: "identity",
+    jsonColumnStrategy: "json",
+    supportsReturning: true,
+    supportsRecursiveCte: true,
+    supportsFullTextSearch: false,
+    reservedWords: reservedWords.kingbase,
+  },
+};
+
+const typeMappings: Record<
+  DatabaseDialect,
+  Record<ColumnTypeMapping["logicalType"], string>
+> = {
+  postgresql: {
+    id: "uuid",
+    string: "varchar(255)",
+    text: "text",
+    integer: "integer",
+    boolean: "boolean",
+    datetime: "timestamptz",
+    json: "jsonb",
+  },
+  mysql: {
+    id: "varchar(36)",
+    string: "varchar(255)",
+    text: "text",
+    integer: "int",
+    boolean: "tinyint(1)",
+    datetime: "datetime",
+    json: "json",
+  },
+  dm: {
+    id: "varchar(36)",
+    string: "varchar(255)",
+    text: "clob",
+    integer: "int",
+    boolean: "tinyint",
+    datetime: "timestamp",
+    json: "clob",
+  },
+  kingbase: {
+    id: "varchar(36)",
+    string: "varchar(255)",
+    text: "text",
+    integer: "integer",
+    boolean: "boolean",
+    datetime: "timestamp",
+    json: "json",
+  },
+};
+
+export function createDialectAdapter(
+  dialect: DatabaseDialect,
+): DatabaseCompatibilityAdapter {
+  return {
+    dialect,
+    capabilities: capabilities[dialect],
+    mapColumnType(logicalType) {
+      return {
+        logicalType,
+        physicalType: typeMappings[dialect][logicalType],
+      };
+    },
+    mapIdentifier(name) {
+      const needsQuote = capabilities[dialect].reservedWords.includes(
+        name.toLowerCase(),
+      );
+      if (!needsQuote) {
+        return name;
+      }
+
+      return dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
+    },
+    mapJsonPath(column, path) {
+      const jsonPath = path.join(".");
+      if (dialect === "postgresql") {
+        return `${column} #>> '{${path.join(",")}}'`;
+      }
+
+      if (dialect === "mysql" || dialect === "kingbase") {
+        return `json_extract(${column}, '$.${jsonPath}')`;
+      }
+
+      return `${column}`;
+    },
+    mapPagination(request: PageRequest): PaginationSqlParts {
+      return {
+        limit: request.pageSize,
+        offset: (request.page - 1) * request.pageSize,
+      };
+    },
+  };
+}

package/src/runner.ts

@@ -0,0 +1,193 @@
+import type {
+  BundleMigrationDefinition,
+  DatabaseCompatibilityAdapter,
+  DatabaseDialect,
+  MigrationBundle,
+  MigrationManifestSource,
+  MigrationStatement,
+} from "@southwind-ai/shared";
+import {
+  normalizeManifestBundles,
+  orderBundleMigrations,
+  validateAndOrderBundles,
+} from "./bundle-validation.js";
+import { createDialectAdapter } from "./dialects.js";
+import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
+
+export interface MigrationRunnerOptions {
+  dialect: DatabaseDialect;
+  store: MigrationHistoryStore;
+  execute?: (statement: MigrationStatement) => Promise<void>;
+  now?: () => Date;
+}
+
+export interface MigrationPlanItem {
+  id: string;
+  module: string;
+  description: string;
+  direction: "up" | "down";
+  checksum: string;
+  skipped: boolean;
+  skipReason?: "already-applied";
+}
+
+export interface MigrationRunReport {
+  dialect: DatabaseDialect;
+  dryRun: boolean;
+  startedAt: string;
+  finishedAt: string;
+  planned: MigrationPlanItem[];
+  applied: string[];
+  failed: Array<{ id: string; error: string }>;
+  statements: MigrationStatement[];
+}
+
+export class PlatformMigrationRunner {
+  private readonly adapter: DatabaseCompatibilityAdapter;
+  private readonly executeStatement: (
+    statement: MigrationStatement,
+  ) => Promise<void>;
+  private readonly now: () => Date;
+
+  constructor(private readonly options: MigrationRunnerOptions) {
+    this.adapter = createDialectAdapter(options.dialect);
+    this.executeStatement = options.execute || (async () => undefined);
+    this.now = options.now || (() => new Date());
+  }
+
+  async plan(modules: readonly MigrationManifestSource[]) {
+    return this.planBundles(normalizeManifestBundles(modules));
+  }
+
+  async planBundles(
+    bundles: readonly MigrationBundle[],
+  ): Promise<MigrationPlanItem[]> {
+    const ordered = validateAndOrderBundles(bundles);
+    const applied = appliedById(await this.options.store.listApplied());
+    return ordered.flatMap((bundle) =>
+      orderBundleMigrations(bundle).map((migration) =>
+        planItem(migration, applied.get(migration.id)),
+      ),
+    );
+  }
+
+  async run(
+    modules: readonly MigrationManifestSource[],
+    dryRun = false,
+  ): Promise<MigrationRunReport> {
+    return this.runBundles(normalizeManifestBundles(modules), dryRun);
+  }
+
+  async runBundles(
+    bundles: readonly MigrationBundle[],
+    dryRun = false,
+  ): Promise<MigrationRunReport> {
+    const startedAt = this.now().toISOString();
+    const ordered = validateAndOrderBundles(bundles);
+    const planned = await this.planBundles(ordered);
+    const migrations = new Map(
+      ordered.flatMap((bundle) =>
+        bundle.migrations.map(
+          (migration) => [migration.id, migration] as const,
+        ),
+      ),
+    );
+    const applied: string[] = [];
+    const failed: Array<{ id: string; error: string }> = [];
+    const statements: MigrationStatement[] = [];
+
+    for (const item of planned) {
+      if (item.skipped) continue;
+      const migration = migrations.get(item.id);
+      if (!migration) throw new Error(`Migration ${item.id} 不存在`);
+
+      const stepStartedAt = this.now().toISOString();
+      const stepStatements: MigrationStatement[] = [];
+      try {
+        await migration.run({
+          dialect: this.options.dialect,
+          dryRun,
+          adapter: this.adapter,
+          execute: async (statement) => {
+            statements.push(statement);
+            stepStatements.push(statement);
+            if (!dryRun) await this.executeStatement(statement);
+          },
+        });
+        applied.push(item.id);
+        if (!dryRun) {
+          await this.recordResult(item, stepStartedAt, stepStatements);
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        failed.push({ id: item.id, error: message });
+        if (!dryRun) {
+          await this.recordResult(item, stepStartedAt, stepStatements, message);
+        }
+        break;
+      }
+    }
+
+    return {
+      dialect: this.options.dialect,
+      dryRun,
+      startedAt,
+      finishedAt: this.now().toISOString(),
+      planned,
+      applied,
+      failed,
+      statements,
+    };
+  }
+
+  private async recordResult(
+    item: MigrationPlanItem,
+    startedAt: string,
+    statements: readonly MigrationStatement[],
+    error?: string,
+  ): Promise<void> {
+    await this.options.store.record({
+      id: item.id,
+      module: item.module,
+      direction: item.direction,
+      status: error ? "failed" : "applied",
+      checksum: item.checksum,
+      startedAt,
+      finishedAt: this.now().toISOString(),
+      statements: statements.map(({ sql }) => sql),
+      error,
+    });
+  }
+}
+
+function appliedById(entries: readonly MigrationHistoryEntry[]) {
+  return new Map(entries.map((entry) => [entry.id, entry]));
+}
+
+function planItem(
+  migration: BundleMigrationDefinition,
+  applied: MigrationHistoryEntry | undefined,
+): MigrationPlanItem {
+  if (applied?.module !== undefined && applied.module !== migration.module) {
+    throw new Error(
+      `已应用 Migration ${migration.id} 归属 ${applied.module}，当前归属 ${migration.module}`,
+    );
+  }
+  if (
+    applied?.checksum !== undefined &&
+    applied.checksum !== migration.checksum
+  ) {
+    throw new Error(
+      `已应用 Migration ${migration.id} checksum 与当前 Bundle 不一致`,
+    );
+  }
+  return {
+    id: migration.id,
+    module: migration.module,
+    description: migration.description,
+    direction: migration.direction,
+    checksum: migration.checksum,
+    skipped: Boolean(applied),
+    skipReason: applied ? "already-applied" : undefined,
+  };
+}

package/src/schema/bulk-data.ts

@@ -0,0 +1,87 @@
+import {
+  index,
+  integer,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  varchar,
+} from "drizzle-orm/pg-core";
+import { durableJobs } from "./durable-jobs.js";
+
+export const bulkDataJobs = pgTable(
+  "bulk_data_jobs",
+  {
+    id: varchar("id", { length: 64 }).primaryKey(),
+    kind: varchar("kind", { length: 24 }).notNull(),
+    resource: varchar("resource", { length: 80 }).notNull(),
+    mode: varchar("mode", { length: 24 }),
+    status: varchar("status", { length: 32 }).notNull(),
+    idempotencyKey: varchar("idempotency_key", { length: 160 }).notNull(),
+    requestDigest: varchar("request_digest", { length: 64 }).notNull(),
+    requestedBy: varchar("requested_by", { length: 64 }).notNull(),
+    totalRows: integer("total_rows").notNull().default(0),
+    processedRows: integer("processed_rows").notNull().default(0),
+    succeededRows: integer("succeeded_rows").notNull().default(0),
+    failedRows: integer("failed_rows").notNull().default(0),
+    attempt: integer("attempt").notNull().default(0),
+    maxAttempts: integer("max_attempts").notNull().default(3),
+    nextAttemptAt: timestamp("next_attempt_at", { withTimezone: true }),
+    error: text("error"),
+    durableJobId: varchar("durable_job_id", { length: 64 }).references(
+      () => durableJobs.id,
+      { onDelete: "restrict" },
+    ),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    startedAt: timestamp("started_at", { withTimezone: true }),
+    finishedAt: timestamp("finished_at", { withTimezone: true }),
+    updatedAt: timestamp("updated_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("uk_bulk_data_jobs_idempotency").on(
+      table.requestedBy,
+      table.kind,
+      table.resource,
+      table.idempotencyKey,
+    ),
+    index("idx_bulk_data_jobs_claim").on(
+      table.status,
+      table.nextAttemptAt,
+      table.createdAt,
+    ),
+    index("idx_bulk_data_jobs_actor_created").on(
+      table.requestedBy,
+      table.createdAt,
+    ),
+    index("idx_bulk_data_jobs_durable_job").on(table.durableJobId),
+  ],
+);
+
+export const bulkDataArtifacts = pgTable(
+  "bulk_data_artifacts",
+  {
+    id: varchar("id", { length: 64 }).primaryKey(),
+    jobId: varchar("job_id", { length: 64 })
+      .notNull()
+      .references(() => bulkDataJobs.id, { onDelete: "restrict" }),
+    kind: varchar("kind", { length: 24 }).notNull(),
+    filename: varchar("filename", { length: 240 }).notNull(),
+    contentType: varchar("content_type", { length: 120 }).notNull(),
+    content: text("content"),
+    artifactRef: varchar("artifact_ref", { length: 37 }),
+    sha256: varchar("sha256", { length: 64 }).notNull(),
+    byteSize: integer("byte_size").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("uk_bulk_data_artifacts_job_kind").on(table.jobId, table.kind),
+    index("idx_bulk_data_artifacts_expiry").on(table.expiresAt),
+  ],
+);

package/src/schema/common.ts

@@ -0,0 +1,33 @@
+import { timestamp, varchar } from "drizzle-orm/pg-core";
+
+export const idColumn = (name = "id") => varchar(name, { length: 64 });
+
+export const statusColumn = (name = "status") => varchar(name, { length: 32 });
+
+export const auditColumns = {
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  createdBy: varchar("created_by", { length: 64 }).notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  updatedBy: varchar("updated_by", { length: 64 }).notNull(),
+  deletedAt: timestamp("deleted_at", { withTimezone: true }),
+  deletedBy: varchar("deleted_by", { length: 64 }),
+};
+
+export interface GovernedExportScopeSnapshot {
+  tenantId: "single-tenant";
+  actorId: string;
+  departmentId?: string;
+  grants: Array<
+    | { scope: "all" | "tenant" | "self" }
+    | {
+        scope: "department" | "department-and-children";
+        departmentId?: string;
+      }
+    | { scope: "custom"; dimension: string; values: string[] }
+  >;
+  roleIds: string[];
+}