@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.30

package/src/cli/commands/apply.ts

@@ -0,0 +1,101 @@
+/**
+ * Apply command - apply a plan's migration script to a target database.
+ */
+
+import { readFile } from "node:fs/promises";
+import { buildCommand, type CommandContext } from "@stricli/core";
+import { applyPlan } from "../../core/plan/apply.ts";
+import { deserializePlan, type Plan } from "../../core/plan/index.ts";
+import { handleApplyResult, validatePlanRisk } from "../utils.ts";
+
+export const applyCommand = buildCommand({
+  parameters: {
+    flags: {
+      plan: {
+        kind: "parsed",
+        brief: "Path to plan file (JSON format)",
+        parse: String,
+      },
+      source: {
+        kind: "parsed",
+        brief: "Source database connection URL (current state)",
+        parse: String,
+      },
+      target: {
+        kind: "parsed",
+        brief: "Target database connection URL (desired state)",
+        parse: String,
+      },
+      unsafe: {
+        kind: "boolean",
+        brief: "Allow data-loss operations (unsafe mode)",
+        optional: true,
+      },
+    },
+    aliases: {
+      p: "plan",
+      s: "source",
+      t: "target",
+      u: "unsafe",
+    },
+  },
+  docs: {
+    brief: "Apply a plan's migration script to a database",
+    fullDescription: `
+Apply changes from a plan file to a target database.
+
+The plan file should be a JSON file created with "pgdelta plan --output <file>.plan.json" (or any .plan/.json path).
+
+Safe by default: will refuse plans containing data-loss unless --unsafe is set.
+
+Exit codes:
+  0 - Success (changes applied)
+  1 - Error occurred
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      plan: string;
+      source: string;
+      target: string;
+      unsafe?: boolean;
+    },
+  ) {
+    // Read and parse plan file
+    let planJson: string;
+    try {
+      planJson = await readFile(flags.plan, "utf-8");
+    } catch (error) {
+      this.process.stderr.write(
+        `Error reading plan file: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    let plan: Plan;
+    try {
+      plan = deserializePlan(planJson);
+    } catch (error) {
+      this.process.stderr.write(
+        `Error parsing plan file: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    const validation = validatePlanRisk(plan, !!flags.unsafe, this);
+    if (!validation.valid) {
+      process.exitCode = validation.exitCode ?? 1;
+      return;
+    }
+
+    const result = await applyPlan(plan, flags.source, flags.target, {
+      verifyPostApply: true,
+    });
+
+    const { exitCode } = handleApplyResult(result, this);
+    process.exitCode = exitCode;
+  },
+});

package/src/cli/commands/catalog-export.ts

@@ -0,0 +1,103 @@
+/**
+ * Catalog export command - extract a database catalog and save as a snapshot JSON file.
+ */
+
+import { writeFile } from "node:fs/promises";
+import { buildCommand, type CommandContext } from "@stricli/core";
+import { filterCatalog } from "../../core/catalog.filter.ts";
+import { extractCatalog } from "../../core/catalog.model.ts";
+import {
+  serializeCatalog,
+  stringifyCatalogSnapshot,
+} from "../../core/catalog.snapshot.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import { createManagedPool } from "../../core/postgres-config.ts";
+
+export const catalogExportCommand = buildCommand({
+  parameters: {
+    flags: {
+      target: {
+        kind: "parsed",
+        brief: "Target database connection URL to extract the catalog from",
+        parse: String,
+      },
+      output: {
+        kind: "parsed",
+        brief: "Output file path for the catalog snapshot JSON",
+        parse: String,
+      },
+      role: {
+        kind: "parsed",
+        brief: "Role to use when extracting the catalog (SET ROLE)",
+        parse: String,
+        optional: true,
+      },
+      filter: {
+        kind: "parsed",
+        brief:
+          'Filter DSL as inline JSON to filter changes (e.g., \'{"*/schema": "app"}\').',
+        parse: (value: string): FilterDSL => {
+          try {
+            return JSON.parse(value) as FilterDSL;
+          } catch (error) {
+            throw new Error(
+              `Invalid filter JSON: ${error instanceof Error ? error.message : String(error)}`,
+            );
+          }
+        },
+        optional: true,
+      },
+    },
+    aliases: {
+      t: "target",
+      o: "output",
+    },
+  },
+  docs: {
+    brief: "Export a database catalog as a snapshot JSON file",
+    fullDescription: `
+Extract the full catalog from a live PostgreSQL database and save it
+as a JSON snapshot file. The snapshot can later be used as --source or
+--target for the plan and declarative export commands, enabling
+offline diffing without a live database connection.
+
+Use cases:
+  - Snapshot template1 for use as an empty-database baseline
+  - Snapshot a production database to generate revert migrations
+  - Snapshot any state for reproducible offline diffs
+
+Pass --filter to scope the snapshot to a subset of the catalog (same
+Filter DSL accepted by plan/sync). Useful when committing a baseline
+snapshot to a repo and only one schema's drift is interesting.
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      target: string;
+      output: string;
+      role?: string;
+      filter?: FilterDSL;
+    },
+  ) {
+    const { pool, close } = await createManagedPool(flags.target, {
+      role: flags.role,
+      label: "target",
+    });
+
+    try {
+      const catalog = await extractCatalog(pool);
+      const scoped = flags.filter
+        ? await filterCatalog(catalog, flags.filter)
+        : catalog;
+      const snapshot = serializeCatalog(scoped);
+      const json = stringifyCatalogSnapshot(snapshot);
+      await writeFile(flags.output, json, "utf-8");
+      this.process.stdout.write(
+        `Catalog snapshot written to ${flags.output}\n`,
+      );
+    } finally {
+      await close();
+    }
+  },
+});

package/src/cli/commands/declarative-apply.diagnostics.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import type { Diagnostic } from "@supabase/pg-topo";
+import {
+  buildDiagnosticDisplayItems,
+  type DiagnosticDisplayEntry,
+} from "../utils/apply-display.ts";
+
+const unresolvedDiagnostic = (message: string): Diagnostic => ({
+  code: "UNRESOLVED_DEPENDENCY",
+  message,
+  details: {
+    requiredObjectKey: "function:public:json_build_object:(unknown,unknown)",
+  },
+  suggestedFix: "Add the missing statement.",
+});
+
+describe("declarative apply diagnostic display grouping", () => {
+  test("grouped mode collapses repeated unresolved diagnostics", () => {
+    const entries: DiagnosticDisplayEntry[] = [
+      {
+        diagnostic: unresolvedDiagnostic(
+          "No producer found for 'function:public:json_build_object:(unknown,unknown)'.",
+        ),
+        location: "schemas/public/tables/user.sql:38:1",
+        requiredObjectKey:
+          "function:public:json_build_object:(unknown,unknown)",
+      },
+      {
+        diagnostic: unresolvedDiagnostic(
+          "No producer found for 'function:public:json_build_object:(unknown,unknown)'.",
+        ),
+        location: "schemas/public/tables/user.sql:45:1",
+        requiredObjectKey:
+          "function:public:json_build_object:(unknown,unknown)",
+      },
+    ];
+
+    const displayItems = buildDiagnosticDisplayItems(entries, true);
+
+    expect(displayItems).toHaveLength(1);
+    expect(displayItems[0]?.locations).toEqual([
+      "schemas/public/tables/user.sql:38:1",
+      "schemas/public/tables/user.sql:45:1",
+    ]);
+  });
+
+  test("ungrouped mode keeps full per-diagnostic detail", () => {
+    const entries: DiagnosticDisplayEntry[] = [
+      {
+        diagnostic: unresolvedDiagnostic(
+          "No producer found for 'function:public:json_build_object:(unknown,unknown)'.",
+        ),
+        location: "schemas/public/tables/user.sql:38:1",
+        requiredObjectKey:
+          "function:public:json_build_object:(unknown,unknown)",
+      },
+      {
+        diagnostic: unresolvedDiagnostic(
+          "No producer found for 'function:public:json_build_object:(unknown,unknown)'.",
+        ),
+        location: "schemas/public/tables/user.sql:45:1",
+        requiredObjectKey:
+          "function:public:json_build_object:(unknown,unknown)",
+      },
+    ];
+
+    const displayItems = buildDiagnosticDisplayItems(entries, false);
+
+    expect(displayItems).toHaveLength(2);
+    expect(displayItems[0]?.locations).toEqual([
+      "schemas/public/tables/user.sql:38:1",
+    ]);
+    expect(displayItems[1]?.locations).toEqual([
+      "schemas/public/tables/user.sql:45:1",
+    ]);
+  });
+});

package/src/cli/commands/declarative-apply.ts

@@ -0,0 +1,380 @@
+/**
+ * Declarative-apply command - apply a declarative SQL schema to a database
+ * using pg-topo static analysis + round-based execution.
+ */
+
+import { readFile } from "node:fs/promises";
+import { buildCommand, type CommandContext } from "@stricli/core";
+import chalk from "chalk";
+import { loadDeclarativeSchema } from "../../core/declarative-apply/discover-sql.ts";
+import {
+  applyDeclarativeSchema,
+  type DeclarativeApplyResult,
+  type RoundResult,
+} from "../../core/declarative-apply/index.ts";
+import {
+  buildDiagnosticDisplayItems,
+  type DiagnosticDisplayEntry,
+  formatStatementError,
+  positionToLineColumn,
+  requiredObjectKeyFromDiagnostic,
+  resolveSqlFilePath,
+} from "../utils/apply-display.ts";
+
+export const declarativeApplyCommand = buildCommand({
+  parameters: {
+    flags: {
+      path: {
+        kind: "parsed",
+        brief:
+          "Path to the declarative schema directory (containing .sql files) or a single .sql file",
+        parse: String,
+      },
+      target: {
+        kind: "parsed",
+        brief: "Target database connection URL to apply the schema to",
+        parse: String,
+      },
+      "max-rounds": {
+        kind: "parsed",
+        brief:
+          "Maximum number of application rounds before giving up (default: 100)",
+        parse: Number,
+        optional: true,
+      },
+      "skip-function-validation": {
+        kind: "boolean",
+        brief: "Skip final function body validation pass",
+        optional: true,
+      },
+      verbose: {
+        kind: "boolean",
+        brief: "Show detailed per-round progress",
+        optional: true,
+      },
+      "ungroup-diagnostics": {
+        kind: "boolean",
+        brief:
+          "Show full per-diagnostic detail instead of grouped summary output",
+        optional: true,
+      },
+    },
+    aliases: {
+      p: "path",
+      t: "target",
+      v: "verbose",
+    },
+  },
+  docs: {
+    brief: "Apply a declarative SQL schema to a database",
+    fullDescription: `
+Apply SQL files from a declarative schema directory to a target database.
+
+Uses pg-topo for static dependency analysis and topological ordering,
+then applies statements round-by-round to handle any remaining
+dependency gaps. Statements that fail with dependency errors are
+deferred to subsequent rounds until all succeed or no progress is made.
+
+Function body checks are disabled during rounds to avoid false failures
+from functions referencing not-yet-created objects. A final validation
+pass re-runs all function/procedure definitions with body checks enabled.
+
+Exit codes:
+  0 - Success (all statements applied)
+  1 - Error (hard failures or validation errors)
+  2 - Stuck (dependency cycle or unresolvable ordering)
+
+Tip: Use DEBUG=pg-delta:declarative-apply for detailed defer/skip/fail logs (which statements are deferred and why).
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      path: string;
+      target: string;
+      "max-rounds"?: number;
+      "skip-function-validation"?: boolean;
+      verbose?: boolean;
+      "ungroup-diagnostics"?: boolean;
+    },
+  ) {
+    const verbose = !!flags.verbose;
+    const ungroupDiagnostics = !!flags["ungroup-diagnostics"];
+
+    const onRoundComplete = verbose
+      ? (round: RoundResult) => {
+          const parts = [
+            `Round ${round.round}:`,
+            chalk.green(`${round.applied} applied`),
+          ];
+          if (round.deferred > 0) {
+            parts.push(chalk.yellow(`${round.deferred} deferred`));
+          }
+          if (round.failed > 0) {
+            parts.push(chalk.red(`${round.failed} failed`));
+          }
+          this.process.stdout.write(`${parts.join("  ")}\n`);
+        }
+      : undefined;
+
+    this.process.stdout.write(`Analyzing SQL files in ${flags.path}...\n`);
+
+    let content: Array<{ filePath: string; sql: string }>;
+    try {
+      content = await loadDeclarativeSchema(flags.path);
+    } catch (error) {
+      this.process.stderr.write(
+        `Error: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    if (content.length === 0) {
+      this.process.stderr.write(
+        `No .sql files found in '${flags.path}'. Pass a directory containing .sql files or a single .sql file.\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    let result: DeclarativeApplyResult;
+    try {
+      result = await applyDeclarativeSchema({
+        content,
+        targetUrl: flags.target,
+        maxRounds: flags["max-rounds"],
+        validateFunctionBodies: !flags["skip-function-validation"],
+        onRoundComplete,
+      });
+    } catch (error) {
+      this.process.stderr.write(
+        `Error: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    // Report pg-topo diagnostics grouped by severity (least noisy first).
+    // UNKNOWN_STATEMENT_CLASS is always hidden; DUPLICATE_PRODUCER,
+    // CYCLE_EDGE_SKIPPED, and UNRESOLVED_DEPENDENCY are verbose-only.
+    const diagnosticDisplayOrder: Record<string, number> = {
+      UNKNOWN_STATEMENT_CLASS: 0,
+      DUPLICATE_PRODUCER: 1,
+      CYCLE_EDGE_SKIPPED: 2,
+      UNRESOLVED_DEPENDENCY: 3,
+    };
+    const diagnosticColor: Record<string, (s: string) => string> = {
+      DUPLICATE_PRODUCER: chalk.yellow,
+      CYCLE_EDGE_SKIPPED: chalk.red,
+      UNRESOLVED_DEPENDENCY: chalk.dim,
+    };
+    const verboseOnlyCodes = new Set([
+      "UNRESOLVED_DEPENDENCY",
+      "DUPLICATE_PRODUCER",
+      "CYCLE_EDGE_SKIPPED",
+    ]);
+    const warnings = result.diagnostics
+      .filter(
+        (d) =>
+          d.code !== "UNKNOWN_STATEMENT_CLASS" &&
+          (verbose || !verboseOnlyCodes.has(d.code)),
+      )
+      .sort(
+        (a, b) =>
+          (diagnosticDisplayOrder[a.code] ?? 99) -
+          (diagnosticDisplayOrder[b.code] ?? 99),
+      );
+    if (warnings.length > 0 && verbose) {
+      const fileContentCache = new Map<string, string>();
+      for (const diag of warnings) {
+        const id = diag.statementId;
+        if (
+          id &&
+          id.sourceOffset != null &&
+          id.filePath &&
+          !fileContentCache.has(id.filePath)
+        ) {
+          // Try to resolve the exact file path of the statement to get the exact location of the error
+          try {
+            const fullPath = await resolveSqlFilePath(flags.path, id.filePath);
+            const content = await readFile(fullPath, "utf-8");
+            fileContentCache.set(id.filePath, content);
+          } catch {
+            // Fall back to statementIndex display
+          }
+        }
+      }
+
+      this.process.stderr.write(
+        chalk.yellow(
+          `\n${warnings.length} diagnostic(s) from static analysis:\n`,
+        ),
+      );
+      const entries: DiagnosticDisplayEntry[] = warnings.map((diag) => {
+        let location: string | undefined;
+        if (diag.statementId) {
+          const id = diag.statementId;
+          const offset = id.sourceOffset;
+          const content =
+            offset != null ? fileContentCache.get(id.filePath) : undefined;
+          if (content != null && offset != null) {
+            const { line, column } = positionToLineColumn(content, offset + 1);
+            location = `${id.filePath}:${line}:${column}`;
+          } else {
+            location = `${id.filePath}:${id.statementIndex}`;
+          }
+        }
+        return {
+          diagnostic: diag,
+          location,
+          requiredObjectKey: requiredObjectKeyFromDiagnostic(diag),
+        };
+      });
+      const displayItems = buildDiagnosticDisplayItems(
+        entries,
+        !ungroupDiagnostics,
+      );
+
+      let lastCode = "";
+      const previewLimit = 5;
+      for (const item of displayItems) {
+        if (item.code !== lastCode) {
+          if (lastCode !== "") {
+            this.process.stderr.write("\n");
+          }
+          lastCode = item.code;
+        }
+        const colorFn = diagnosticColor[item.code] ?? chalk.yellow;
+        const location =
+          item.locations.length > 0 ? ` (${item.locations[0]})` : "";
+        const occurrences =
+          !ungroupDiagnostics && item.locations.length > 1
+            ? ` x${item.locations.length}`
+            : "";
+        this.process.stderr.write(
+          colorFn(
+            `  [${item.code}]${location}${occurrences} ${item.message}\n`,
+          ),
+        );
+        if (!ungroupDiagnostics && item.requiredObjectKey) {
+          this.process.stderr.write(
+            colorFn(`    -> Object: ${item.requiredObjectKey}\n`),
+          );
+        }
+        if (!ungroupDiagnostics && item.locations.length > 1) {
+          for (const locationEntry of item.locations.slice(0, previewLimit)) {
+            this.process.stderr.write(colorFn(`    at ${locationEntry}\n`));
+          }
+          const remaining = item.locations.length - previewLimit;
+          if (remaining > 0) {
+            this.process.stderr.write(
+              colorFn(`    ... and ${remaining} more location(s)\n`),
+            );
+          }
+        }
+        if (item.suggestedFix) {
+          this.process.stderr.write(
+            colorFn(`    -> Fix: ${item.suggestedFix}\n`),
+          );
+        }
+      }
+      this.process.stderr.write("\n");
+    }
+
+    const { apply } = result;
+
+    // Summary
+    this.process.stdout.write("\n");
+    this.process.stdout.write(
+      `Statements: ${result.totalStatements} total, ${apply.totalApplied} applied`,
+    );
+    if (apply.totalSkipped > 0) {
+      this.process.stdout.write(`, ${apply.totalSkipped} skipped`);
+    }
+    this.process.stdout.write("\n");
+    this.process.stdout.write(`Rounds: ${apply.totalRounds}\n`);
+
+    switch (apply.status) {
+      case "success": {
+        this.process.stdout.write(
+          chalk.green("All statements applied successfully.\n"),
+        );
+        if (apply.validationErrors && apply.validationErrors.length > 0) {
+          this.process.stderr.write(
+            chalk.yellow(
+              `\n${apply.validationErrors.length} function body validation error(s):\n`,
+            ),
+          );
+          for (const err of apply.validationErrors) {
+            const formatted = await formatStatementError(err, flags.path);
+            this.process.stderr.write(chalk.yellow(formatted));
+            this.process.stderr.write("\n\n");
+          }
+          process.exitCode = 1;
+        } else {
+          process.exitCode = 0;
+        }
+        break;
+      }
+
+      case "stuck": {
+        this.process.stderr.write(
+          chalk.red(
+            `\nStuck after ${apply.totalRounds} round(s). ${apply.stuckStatements?.length ?? 0} statement(s) could not be applied:\n`,
+          ),
+        );
+        if (apply.stuckStatements) {
+          for (const stuck of apply.stuckStatements) {
+            const formatted = await formatStatementError(stuck, flags.path);
+            this.process.stderr.write(chalk.red(formatted));
+            this.process.stderr.write("\n\n");
+          }
+        }
+        if (apply.errors && apply.errors.length > 0) {
+          this.process.stderr.write(
+            chalk.red(
+              `\nAdditionally, ${apply.errors.length} statement(s) had non-dependency errors:\n`,
+            ),
+          );
+          for (const err of apply.errors) {
+            const formatted = await formatStatementError(err, flags.path);
+            this.process.stderr.write(chalk.red(formatted));
+            this.process.stderr.write("\n\n");
+          }
+        }
+        process.exitCode = 2;
+        break;
+      }
+
+      case "error": {
+        this.process.stderr.write(
+          chalk.red(
+            `\nCompleted with errors. ${apply.errors?.length ?? 0} statement(s) failed:\n`,
+          ),
+        );
+        if (apply.errors) {
+          for (const err of apply.errors) {
+            const formatted = await formatStatementError(err, flags.path);
+            this.process.stderr.write(chalk.red(formatted));
+            this.process.stderr.write("\n\n");
+          }
+        }
+        if (apply.validationErrors && apply.validationErrors.length > 0) {
+          this.process.stderr.write(
+            chalk.yellow(
+              `\n${apply.validationErrors.length} function body validation error(s):\n`,
+            ),
+          );
+          for (const err of apply.validationErrors) {
+            const formatted = await formatStatementError(err, flags.path);
+            this.process.stderr.write(chalk.yellow(formatted));
+            this.process.stderr.write("\n\n");
+          }
+        }
+        process.exitCode = 1;
+        break;
+      }
+    }
+  },
+});