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

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

@@ -0,0 +1,322 @@
+/**
+ * Declarative export command - export a declarative SQL schema from a database diff.
+ */
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildCommand, type CommandContext } from "@stricli/core";
+import chalk from "chalk";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
+import { exportDeclarativeSchema } from "../../core/export/index.ts";
+import type { Grouping, GroupingPattern } from "../../core/export/types.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import {
+  compileSerializeDSL,
+  type SerializeDSL,
+} from "../../core/integrations/serialize/dsl.ts";
+import { createPlan } from "../../core/plan/index.ts";
+import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
+import {
+  assertSafePath,
+  buildFileTree,
+  computeFileDiff,
+  formatExportSummary,
+} from "../utils/export-display.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
+import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
+
+function parseJsonFlag<T>(label: string, value: string): T {
+  try {
+    return JSON.parse(value) as T;
+  } catch (error) {
+    throw new Error(
+      `Invalid ${label} JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+export const declarativeExportCommand = buildCommand({
+  parameters: {
+    flags: {
+      source: {
+        kind: "parsed",
+        brief:
+          "Source (current state): postgres URL or catalog snapshot file path. Omit to export all objects from target.",
+        parse: String,
+        optional: true,
+      },
+      target: {
+        kind: "parsed",
+        brief:
+          "Target (desired state): postgres URL or catalog snapshot file path",
+        parse: String,
+      },
+      output: {
+        kind: "parsed",
+        brief: "Output directory path for declarative schema files",
+        parse: String,
+      },
+      integration: {
+        kind: "parsed",
+        brief:
+          "Integration name (e.g., 'supabase') or path to integration JSON file",
+        parse: String,
+        optional: true,
+      },
+      filter: {
+        kind: "parsed",
+        brief: 'Filter DSL as inline JSON (e.g., \'{"schema":"public"}\')',
+        parse: (v: string) => parseJsonFlag<FilterDSL>("filter", v),
+        optional: true,
+      },
+      serialize: {
+        kind: "parsed",
+        brief:
+          'Serialize DSL as inline JSON array (e.g., \'[{"when":{"type":"schema"},"options":{"skipAuthorization":true}}]\')',
+        parse: (v: string) => parseJsonFlag<SerializeDSL>("serialize", v),
+        optional: true,
+      },
+      "grouping-mode": {
+        kind: "enum",
+        brief: "How grouped entities are organized on disk",
+        values: ["single-file", "subdirectory"] as const,
+        optional: true,
+      },
+      "group-patterns": {
+        kind: "parsed",
+        brief:
+          'JSON array of {pattern, name} objects (e.g., \'[{"pattern":"^auth","name":"auth"}]\')',
+        parse: (v: string) => {
+          const parsed = parseJsonFlag<GroupingPattern[]>("group-patterns", v);
+          if (!Array.isArray(parsed)) {
+            throw new Error("group-patterns must be a JSON array");
+          }
+          return parsed;
+        },
+        optional: true,
+      },
+      "flat-schemas": {
+        kind: "parsed",
+        brief:
+          "Comma-separated list of schemas to flatten (e.g., partman,pgboss,audit)",
+        parse: String,
+        optional: true,
+      },
+      "format-options": {
+        kind: "parsed",
+        brief:
+          'SQL format options as inline JSON (e.g., \'{"keywordCase":"lower","maxWidth":180}\')',
+        parse: (v: string) =>
+          parseJsonFlag<SqlFormatOptions>("format-options", v),
+        optional: true,
+      },
+      force: {
+        kind: "boolean",
+        brief: "Remove entire output directory before writing",
+        optional: true,
+      },
+      "dry-run": {
+        kind: "boolean",
+        brief: "Show tree and summary without writing files",
+        optional: true,
+      },
+      "diff-focus": {
+        kind: "boolean",
+        brief:
+          "Show only files that changed (created/updated/deleted) in the tree",
+        optional: true,
+      },
+      verbose: {
+        kind: "boolean",
+        brief: "Show detailed output",
+        optional: true,
+      },
+    },
+    aliases: {
+      s: "source",
+      t: "target",
+      o: "output",
+    },
+  },
+  docs: {
+    brief: "Export a declarative schema from a database diff",
+    fullDescription: `
+Export a declarative SQL schema by comparing two databases (source → target).
+Writes .sql files to the output directory, grouped by object type and optional
+grouping rules.
+
+When --source is omitted, all objects from the target database are exported
+(equivalent to diffing from an empty database).
+
+Flags:
+  source         - Source database connection URL (optional; omit for full export)
+  target         - Target database connection URL (desired state)
+  output         - Directory path for generated .sql files
+  integration    - Integration name or path (e.g., supabase) for filter/serialize
+  filter         - Filter DSL as JSON to include/exclude changes
+  serialize      - Serialize DSL as JSON array for custom SQL generation
+  grouping-mode  - single-file or subdirectory for grouped entities
+  group-patterns - JSON array of {pattern, name} for name-based grouping
+  flat-schemas   - Comma-separated schemas to merge into one file per category
+  format-options - SQL format options as JSON
+  force          - Remove output directory before writing (full replace)
+  dry-run        - Show tree and summary only, do not write files
+  diff-focus     - Show only changed files (created/updated/deleted) in the tree
+  verbose        - Show detailed output
+
+After export, a tip is printed with the command to apply the schema to an empty database.
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      source?: string;
+      target: string;
+      output: string;
+      integration?: string;
+      filter?: FilterDSL;
+      serialize?: SerializeDSL;
+      "grouping-mode"?: "single-file" | "subdirectory";
+      "group-patterns"?: GroupingPattern[];
+      "flat-schemas"?: string;
+      "format-options"?: SqlFormatOptions;
+      force?: boolean;
+      "dry-run"?: boolean;
+      "diff-focus"?: boolean;
+      verbose?: boolean;
+    },
+  ) {
+    const {
+      filter,
+      serialize,
+      emptyCatalog: integrationEmptyCatalog,
+    } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
+
+    const resolvedSource = flags.source
+      ? isPostgresUrl(flags.source)
+        ? flags.source
+        : await loadCatalogFromFile(flags.source)
+      : integrationEmptyCatalog
+        ? deserializeCatalog(integrationEmptyCatalog)
+        : null;
+
+    const resolvedTarget = isPostgresUrl(flags.target)
+      ? flags.target
+      : await loadCatalogFromFile(flags.target);
+
+    // Pass raw DSL to createPlan (not pre-compiled functions).
+    // createPlan compiles them internally and uses the DSL type to correctly
+    // determine cascade behavior: DSL filters disable cascading by default
+    // (unless cascade:true is set), preventing unintended exclusion of
+    // changes that depend on filtered objects (e.g. RLS policies that
+    // reference auth.uid() when the auth schema is filtered out).
+    const planResult = await createPlan(resolvedSource, resolvedTarget, {
+      filter,
+      serialize,
+      skipDefaultPrivilegeSubtraction: true,
+    });
+
+    if (!planResult) {
+      this.process.stdout.write("No changes detected.\n");
+      return;
+    }
+
+    const hasGrouping =
+      flags["grouping-mode"] !== undefined ||
+      (flags["group-patterns"] !== undefined &&
+        flags["group-patterns"].length > 0) ||
+      (flags["flat-schemas"] !== undefined && flags["flat-schemas"].length > 0);
+
+    let grouping: Grouping | undefined;
+    if (hasGrouping) {
+      grouping = {
+        mode: flags["grouping-mode"] ?? "single-file",
+        groupPatterns: flags["group-patterns"],
+        autoGroupPartitions: true,
+        flatSchemas:
+          flags["flat-schemas"] !== undefined
+            ? flags["flat-schemas"]
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : undefined,
+      };
+    }
+
+    const serializeFn =
+      serialize !== undefined ? compileSerializeDSL(serialize) : undefined;
+
+    const output = exportDeclarativeSchema(planResult, {
+      integration:
+        serializeFn !== undefined ? { serialize: serializeFn } : undefined,
+      formatOptions: flags["format-options"] ?? undefined,
+      grouping,
+      onWarning: (msg) => {
+        this.process.stderr.write(chalk.yellow(`Warning: ${msg}\n`));
+      },
+    });
+
+    const outputDir = path.resolve(flags.output);
+    const applyTip = (dir: string) =>
+      `\nTip: To apply this schema to an empty database, run:\n  pgdelta declarative apply --path ${dir} --target <database_url>\n`;
+    const diff = await computeFileDiff(outputDir, output.files);
+
+    this.process.stdout.write("\n");
+    this.process.stdout.write(
+      `${buildFileTree(
+        output.files.map((f) => f.path),
+        path.basename(outputDir) || outputDir,
+        { diff, diffFocus: !!flags["diff-focus"] },
+      )}\n`,
+    );
+    this.process.stdout.write("\n");
+    this.process.stdout.write(
+      `${chalk.green("+")} created   ${chalk.yellow("~")} updated   ${chalk.red("-")} deleted\n`,
+    );
+    this.process.stdout.write("\n");
+
+    const summary = formatExportSummary(diff, !!flags["dry-run"]);
+    if (summary) {
+      this.process.stdout.write(`${summary}\n`);
+    }
+
+    const totalChanges = planResult.sortedChanges.length;
+    const totalStatements = output.files.reduce((s, f) => s + f.statements, 0);
+    this.process.stdout.write(
+      `Changes: ${totalChanges} | Files: ${output.files.length} | Statements: ${totalStatements}\n`,
+    );
+
+    if (flags["dry-run"]) {
+      this.process.stdout.write(chalk.dim("\n(dry-run: no files written)\n"));
+      this.process.stdout.write(chalk.cyan(applyTip(outputDir)));
+      return;
+    }
+
+    if (flags.force) {
+      await rm(outputDir, { recursive: true, force: true });
+      await mkdir(outputDir, { recursive: true });
+    } else if (diff.deleted.length > 0) {
+      this.process.stderr.write(
+        chalk.yellow(
+          `Warning: ${diff.deleted.length} existing file(s) will no longer be present. Use --force to replace the output directory.\n`,
+        ),
+      );
+    }
+
+    for (const file of output.files) {
+      assertSafePath(file.path, outputDir);
+      const filePath = path.join(outputDir, file.path);
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await writeFile(filePath, file.sql);
+    }
+
+    this.process.stdout.write(
+      chalk.green(`Wrote ${output.files.length} file(s) to ${outputDir}\n`),
+    );
+    this.process.stdout.write(chalk.cyan(applyTip(outputDir)));
+  },
+});

package/src/cli/commands/plan.ts

@@ -0,0 +1,256 @@
+/**
+ * Plan command - compute schema diff and preview changes.
+ */
+
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildCommand, type CommandContext } from "@stricli/core";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
+import { createPlan } from "../../core/plan/index.ts";
+import { renderPlanFiles } from "../../core/plan/render.ts";
+import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
+import { setCommandExitCode } from "../exit-code.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
+import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
+import { formatPlanForDisplay } from "../utils.ts";
+
+export const planCommand = buildCommand({
+  parameters: {
+    flags: {
+      source: {
+        kind: "parsed",
+        brief:
+          "Source (current state): postgres URL or catalog snapshot file path. Omit for empty baseline.",
+        parse: String,
+        optional: true,
+      },
+      target: {
+        kind: "parsed",
+        brief:
+          "Target (desired state): postgres URL or catalog snapshot file path",
+        parse: String,
+      },
+      format: {
+        kind: "enum",
+        brief: "Output format override: json (plan) or sql (script).",
+        values: ["json", "sql"] as const,
+        optional: true,
+      },
+      output: {
+        kind: "parsed",
+        brief:
+          "Write output to file (stdout by default). If format is not set: .sql infers sql, .json infers json, otherwise uses human output.",
+        parse: String,
+        optional: true,
+      },
+      "output-dir": {
+        kind: "parsed",
+        brief:
+          "Write numbered SQL migration files to a directory using transaction-aware plan units.",
+        parse: String,
+        optional: true,
+      },
+      role: {
+        kind: "parsed",
+        brief:
+          "Role to use when executing the migration (SET ROLE will be added to statements).",
+        parse: String,
+        optional: true,
+      },
+      filter: {
+        kind: "parsed",
+        brief:
+          'Filter DSL as inline JSON to filter changes (e.g., \'{"schema":"public"}\').',
+        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,
+      },
+      serialize: {
+        kind: "parsed",
+        brief:
+          'Serialize DSL as inline JSON array (e.g., \'[{"when":{"type":"schema"},"options":{"skipAuthorization":true}}]\').',
+        parse: (value: string): SerializeDSL => {
+          try {
+            return JSON.parse(value) as SerializeDSL;
+          } catch (error) {
+            throw new Error(
+              `Invalid serialize JSON: ${error instanceof Error ? error.message : String(error)}`,
+            );
+          }
+        },
+        optional: true,
+      },
+      integration: {
+        kind: "parsed",
+        brief:
+          "Integration name (e.g., 'supabase') or path to integration JSON file (must end with .json). Loads from core/integrations/ or file path.",
+        parse: String,
+        optional: true,
+      },
+      "sql-format": {
+        kind: "boolean",
+        brief: "Format SQL output (opt-in for --format sql or .sql output).",
+        optional: true,
+      },
+      "sql-format-options": {
+        kind: "parsed",
+        brief:
+          'SQL format options as inline JSON (e.g., \'{"keywordCase":"upper","maxWidth":100}\').',
+        parse: (value: string): SqlFormatOptions => {
+          try {
+            return JSON.parse(value) as SqlFormatOptions;
+          } catch (error) {
+            throw new Error(
+              `Invalid SQL format JSON: ${error instanceof Error ? error.message : String(error)}`,
+            );
+          }
+        },
+        optional: true,
+      },
+    },
+    aliases: {
+      s: "source",
+      t: "target",
+      o: "output",
+    },
+  },
+  docs: {
+    brief: "Compute schema diff and preview changes",
+    fullDescription: `
+Compute the schema diff between two PostgreSQL databases (source → target),
+and preview it for review or scripting. Defaults to tree display;
+json/sql outputs are available for artifacts or piping.
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      source?: string;
+      target: string;
+      format?: "json" | "sql";
+      output?: string;
+      "output-dir"?: string;
+      role?: string;
+      filter?: FilterDSL;
+      serialize?: SerializeDSL;
+      integration?: string;
+      "sql-format"?: boolean;
+      "sql-format-options"?: SqlFormatOptions;
+    },
+  ) {
+    const {
+      filter,
+      serialize,
+      emptyCatalog: integrationEmptyCatalog,
+    } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
+
+    const resolvedSource = flags.source
+      ? isPostgresUrl(flags.source)
+        ? flags.source
+        : await loadCatalogFromFile(flags.source)
+      : integrationEmptyCatalog
+        ? deserializeCatalog(integrationEmptyCatalog)
+        : null;
+
+    const resolvedTarget = isPostgresUrl(flags.target)
+      ? flags.target
+      : await loadCatalogFromFile(flags.target);
+
+    const planResult = await createPlan(resolvedSource, resolvedTarget, {
+      role: flags.role,
+      filter,
+      serialize,
+    });
+    if (!planResult) {
+      this.process.stdout.write("No changes detected.\n");
+      return;
+    }
+
+    if (flags.output && flags["output-dir"]) {
+      throw new Error("Use either --output or --output-dir, not both.");
+    }
+
+    if (flags["output-dir"]) {
+      await prepareOutputDirectory(flags["output-dir"]);
+      const files = renderPlanFiles(planResult.plan, {
+        sqlFormatOptions:
+          flags["sql-format"] || flags["sql-format-options"]
+            ? (flags["sql-format-options"] ?? {})
+            : undefined,
+      });
+      for (const file of files) {
+        await writeFile(
+          path.join(flags["output-dir"], file.path),
+          file.sql,
+          "utf-8",
+        );
+      }
+      this.process.stdout.write(
+        `${files.length} migration file${files.length === 1 ? "" : "s"} written to ${flags["output-dir"]}\n`,
+      );
+      setCommandExitCode(2);
+      return;
+    }
+
+    const outputPath = flags.output;
+    let effectiveFormat: "tree" | "json" | "sql";
+    if (flags.format) {
+      effectiveFormat = flags.format;
+    } else if (outputPath?.endsWith(".sql")) {
+      effectiveFormat = "sql";
+    } else if (outputPath?.endsWith(".json")) {
+      effectiveFormat = "json";
+    } else {
+      effectiveFormat = "tree";
+    }
+
+    const { content, label } = formatPlanForDisplay(
+      planResult,
+      effectiveFormat,
+      {
+        disableColors: !!outputPath,
+        showUnsafeFlagSuggestion: false,
+        sqlFormatOptions:
+          flags["sql-format"] || flags["sql-format-options"]
+            ? (flags["sql-format-options"] ?? {})
+            : undefined,
+      },
+    );
+
+    if (outputPath) {
+      await writeFile(outputPath, content, "utf-8");
+      this.process.stdout.write(`${label} written to ${outputPath}\n`);
+    } else {
+      this.process.stdout.write(content);
+      if (!content.endsWith("\n")) {
+        this.process.stdout.write("\n");
+      }
+    }
+
+    // Exit code 2 indicates changes were detected
+    setCommandExitCode(2);
+  },
+});
+
+async function prepareOutputDirectory(outputDir: string): Promise<void> {
+  await mkdir(outputDir, { recursive: true });
+  const entries = await readdir(outputDir);
+  if (entries.length > 0) {
+    throw new Error(
+      `Output directory is not empty: ${outputDir}. Choose an empty directory to avoid stale migration files.`,
+    );
+  }
+}