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

package/src/cli/utils/resolve-input.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { isPostgresUrl, loadCatalogFromFile } from "./resolve-input.ts";
+
+describe("isPostgresUrl", () => {
+  test("returns true for postgres:// URL", () => {
+    expect(isPostgresUrl("postgres://user:pass@localhost:5432/db")).toBe(true);
+  });
+
+  test("returns true for postgresql:// URL", () => {
+    expect(isPostgresUrl("postgresql://localhost/db")).toBe(true);
+  });
+
+  test("returns false for file path", () => {
+    expect(isPostgresUrl("/path/to/catalog.json")).toBe(false);
+    expect(isPostgresUrl("catalog.json")).toBe(false);
+  });
+
+  test("returns false for other strings", () => {
+    expect(isPostgresUrl("")).toBe(false);
+    expect(isPostgresUrl("postgres")).toBe(false);
+  });
+});
+
+describe("loadCatalogFromFile", () => {
+  test("loads and deserializes catalog from JSON file", async () => {
+    const fixturePath = path.join(
+      import.meta.dir,
+      "../../core/fixtures/empty-catalogs/postgres-15-16-baseline.json",
+    );
+    const catalog = await loadCatalogFromFile(fixturePath);
+    expect(catalog).toBeDefined();
+    expect(catalog.version).toBeGreaterThan(0);
+    expect(typeof catalog.currentUser).toBe("string");
+    expect(catalog.schemas).toBeDefined();
+    expect(catalog.depends).toEqual(expect.any(Array));
+  });
+});

package/src/cli/utils/resolve-input.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared utilities for resolving CLI --source/--target inputs that
+ * can be either a PostgreSQL connection URL or a catalog snapshot file path.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { Catalog } from "../../core/catalog.model.ts";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
+
+export function isPostgresUrl(input: string): boolean {
+  return input.startsWith("postgres://") || input.startsWith("postgresql://");
+}
+
+export async function loadCatalogFromFile(path: string): Promise<Catalog> {
+  const json = await readFile(path, "utf-8");
+  return deserializeCatalog(JSON.parse(json));
+}

package/src/cli/utils.ts

@@ -0,0 +1,247 @@
+/**
+ * Shared utility functions for CLI commands.
+ */
+
+import { createInterface } from "node:readline";
+import type { CommandContext } from "@stricli/core";
+import chalk from "chalk";
+import type { Change } from "../core/change.types.ts";
+import type { DiffContext } from "../core/context.ts";
+import { groupChangesHierarchically } from "../core/plan/hierarchy.ts";
+import { type Plan, serializePlan } from "../core/plan/index.ts";
+import { renderPlanSql } from "../core/plan/render.ts";
+import { classifyChangesRisk } from "../core/plan/risk.ts";
+import type { SqlFormatOptions } from "../core/plan/sql-format.ts";
+import { formatTree } from "./formatters/index.ts";
+
+// Re-export ApplyPlanResult type for convenience
+type ApplyPlanResult =
+  | { status: "invalid_plan"; message: string }
+  | { status: "fingerprint_mismatch"; current: string; expected: string }
+  | { status: "already_applied" }
+  | {
+      status: "applied";
+      statements: number;
+      units: number;
+      warnings?: string[];
+    }
+  | {
+      status: "failed";
+      error: unknown;
+      script: string;
+      failedUnitIndex?: number;
+      completedUnits: number;
+    };
+
+type PlanResult = {
+  plan: Plan;
+  sortedChanges: Change[];
+  ctx: DiffContext;
+};
+
+interface FormatPlanOptions {
+  disableColors?: boolean;
+  showUnsafeFlagSuggestion?: boolean;
+  sqlFormatOptions?: SqlFormatOptions;
+}
+
+/**
+ * Formats a plan result for display in various formats.
+ */
+export function formatPlanForDisplay(
+  planResult: PlanResult,
+  format: "tree" | "json" | "sql",
+  options: FormatPlanOptions = {},
+): { content: string; label: string } {
+  const { plan, sortedChanges, ctx } = planResult;
+  const risk = plan.risk ?? classifyChangesRisk(sortedChanges);
+  const planWithRisk = plan.risk ? plan : { ...plan, risk };
+
+  switch (format) {
+    case "sql": {
+      const content = [
+        `-- Risk: ${risk.level === "data_loss" ? `data-loss (${risk.statements.length})` : "safe"}`,
+        renderPlanSql(plan, { sqlFormatOptions: options.sqlFormatOptions }),
+      ].join("\n");
+      return { content, label: "Migration script" };
+    }
+    case "json": {
+      const content = serializePlan(planWithRisk);
+      return { content, label: "Plan" };
+    }
+    default: {
+      const hierarchy = groupChangesHierarchically(ctx, sortedChanges);
+      const previousLevel = chalk.level;
+      if (options.disableColors) {
+        chalk.level = 0;
+      }
+      try {
+        let treeContent = formatTree(hierarchy);
+        if (risk.level === "data_loss") {
+          const warningLines = [
+            "",
+            chalk.yellow("⚠ Data-loss operations detected:"),
+            ...risk.statements.map((statement: string) =>
+              chalk.yellow(`- ${statement}`),
+            ),
+          ];
+          if (options.showUnsafeFlagSuggestion !== false) {
+            warningLines.push(
+              chalk.yellow(
+                "Use `--unsafe` to allow applying these operations.",
+              ),
+            );
+          }
+          const treeLines = treeContent.split("\n");
+          // Insert warning after the legend (at the end of the output)
+          // Find the legend line which contains "create", "alter", and "drop"
+          let insertIndex = treeLines.length;
+          const ansiPattern = new RegExp(
+            `${String.fromCharCode(27)}\\[[0-9;]*m`,
+            "g",
+          );
+          // Search from the end backwards for the legend
+          for (let i = treeLines.length - 1; i >= 0; i--) {
+            const line = treeLines[i];
+            const stripped = line.replace(ansiPattern, "").trim();
+            // Legend format: "+ create   ~ alter   - drop" (or variations)
+            if (
+              stripped.includes("create") &&
+              stripped.includes("alter") &&
+              stripped.includes("drop")
+            ) {
+              insertIndex = i + 1;
+              break;
+            }
+          }
+          // Fallback: if legend not found, append at the end
+          if (insertIndex === treeLines.length) {
+            insertIndex = treeLines.length;
+          }
+          treeLines.splice(insertIndex, 0, ...warningLines);
+          treeContent = treeLines.join("\n");
+        }
+        // add newline for nicer stdout when in tree mode
+        if (!treeContent.endsWith("\n")) {
+          treeContent = `${treeContent}\n`;
+        }
+        return { content: treeContent, label: "Human-readable plan" };
+      } finally {
+        if (options.disableColors) {
+          chalk.level = previousLevel;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Validates plan risk and handles unsafe operations.
+ * Returns validation result with optional exit code.
+ */
+export function validatePlanRisk(
+  plan: Plan,
+  unsafe: boolean,
+  context: CommandContext,
+  options?: { suppressWarning?: boolean },
+): { valid: boolean; exitCode?: number } {
+  if (!unsafe) {
+    if (!plan.risk) {
+      context.process.stderr.write(
+        "Plan is missing risk metadata. Regenerate the plan with the current pgdelta or re-run with --unsafe to apply anyway.\n",
+      );
+      return { valid: false, exitCode: 1 };
+    }
+    if (plan.risk.level === "data_loss") {
+      if (!options?.suppressWarning) {
+        const warningLines = [
+          chalk.yellow("⚠ Data-loss operations detected:"),
+          ...plan.risk.statements.map((statement: string) =>
+            chalk.yellow(`- ${statement}`),
+          ),
+          chalk.yellow("Use `--unsafe` to allow applying these operations."),
+        ];
+        context.process.stderr.write(`${warningLines.join("\n")}\n`);
+      }
+      return { valid: false, exitCode: 1 };
+    }
+  }
+  return { valid: true };
+}
+
+/**
+ * Handles applyPlan results and writes appropriate output.
+ * Returns the exit code that should be set.
+ */
+export function handleApplyResult(
+  result: ApplyPlanResult,
+  context: CommandContext,
+): { exitCode: number } {
+  switch (result.status) {
+    case "invalid_plan":
+      context.process.stderr.write(`${result.message}\n`);
+      return { exitCode: 1 };
+    case "fingerprint_mismatch":
+      context.process.stderr.write(
+        "Target database does not match plan source fingerprint. Aborting.\n",
+      );
+      return { exitCode: 1 };
+    case "already_applied":
+      context.process.stdout.write(
+        "Plan already applied (target fingerprint matches desired state).\n",
+      );
+      return { exitCode: 0 };
+    case "failed": {
+      context.process.stderr.write(
+        `Failed to apply changes: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`,
+      );
+      if (result.failedUnitIndex !== undefined) {
+        context.process.stderr.write(
+          `Failed in migration unit ${result.failedUnitIndex + 1} (${result.completedUnits} unit${result.completedUnits === 1 ? "" : "s"} already committed).\n`,
+        );
+      }
+      context.process.stderr.write(`Migration script:\n${result.script}\n`);
+      return { exitCode: 1 };
+    }
+    case "applied": {
+      context.process.stdout.write(
+        `Applied ${result.statements} change${result.statements === 1 ? "" : "s"} across ${result.units} migration unit${result.units === 1 ? "" : "s"}.\n`,
+      );
+      context.process.stdout.write("Successfully applied all changes.\n");
+      if (result.warnings?.length) {
+        for (const warning of result.warnings) {
+          context.process.stderr.write(`Warning: ${warning}\n`);
+        }
+      }
+      return { exitCode: 0 };
+    }
+  }
+}
+
+/**
+ * Prompts user for confirmation using readline.
+ * Returns true for 'y'/'yes', false otherwise.
+ */
+export function promptConfirmation(
+  question: string,
+  context: CommandContext,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    // Access stdin/stdout from the process object
+    // Type assertion needed because CommandContext.process may not expose stdin in its type
+    const process = context.process as unknown as {
+      stdin: NodeJS.ReadableStream;
+      stdout: NodeJS.WritableStream;
+    };
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(question, (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolve(normalized === "y" || normalized === "yes");
+    });
+  });
+}

package/src/core/catalog-export/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Catalog export – programmatic API for extracting a database catalog
+ * and serializing it to a JSON snapshot.
+ *
+ * Use this subpath when you only need catalog export (e.g. Supabase CLI
+ * edge-runtime templates) without pulling in the full pg-delta API.
+ */
+
+export {
+  Catalog,
+  createEmptyCatalog,
+  extractCatalog,
+} from "../catalog.model.ts";
+export type { CatalogSnapshot } from "../catalog.snapshot.ts";
+export {
+  deserializeCatalog,
+  serializeCatalog,
+  stringifyCatalogSnapshot,
+} from "../catalog.snapshot.ts";
+export { createManagedPool } from "../postgres-config.ts";

package/src/core/catalog.diff.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { diffCatalogs } from "./catalog.diff.ts";
+import { Catalog, createEmptyCatalog } from "./catalog.model.ts";
+import { Role, type RoleProps } from "./objects/role/role.model.ts";
+import {
+  GrantViewPrivileges,
+  RevokeViewPrivileges,
+} from "./objects/view/changes/view.privilege.ts";
+import { View, type ViewProps } from "./objects/view/view.model.ts";
+
+const idColumn: ViewProps["columns"][number] = {
+  name: "id",
+  position: 1,
+  data_type: "integer",
+  data_type_str: "integer",
+  is_custom_type: false,
+  custom_type_type: null,
+  custom_type_category: null,
+  custom_type_schema: null,
+  custom_type_name: null,
+  not_null: false,
+  is_identity: false,
+  is_identity_always: false,
+  is_generated: false,
+  collation: null,
+  default: null,
+  comment: null,
+};
+
+const nameColumn: ViewProps["columns"][number] = {
+  name: "name",
+  position: 2,
+  data_type: "text",
+  data_type_str: "text",
+  is_custom_type: false,
+  custom_type_type: null,
+  custom_type_category: null,
+  custom_type_schema: null,
+  custom_type_name: null,
+  not_null: false,
+  is_identity: false,
+  is_identity_always: false,
+  is_generated: false,
+  collation: null,
+  default: null,
+  comment: null,
+};
+
+const baseView: ViewProps = {
+  schema: "public",
+  name: "replaced_view",
+  definition: "SELECT id FROM source_table",
+  row_security: false,
+  force_row_security: false,
+  has_indexes: false,
+  has_rules: false,
+  has_triggers: false,
+  has_subclasses: false,
+  is_populated: true,
+  replica_identity: "d",
+  is_partition: false,
+  options: null,
+  partition_bound: null,
+  owner: "postgres",
+  comment: null,
+  columns: [idColumn],
+  privileges: [],
+};
+
+const makeView = (override: Partial<ViewProps> = {}) =>
+  new View({
+    ...baseView,
+    ...override,
+    columns: override.columns ?? [...baseView.columns],
+    privileges: override.privileges ?? [...baseView.privileges],
+  });
+
+const makeRole = (name: string, override: Partial<RoleProps> = {}) =>
+  new Role({
+    name,
+    is_superuser: false,
+    can_inherit: true,
+    can_create_roles: false,
+    can_create_databases: false,
+    can_login: true,
+    can_replicate: false,
+    connection_limit: null,
+    can_bypass_rls: false,
+    config: null,
+    comment: null,
+    members: [],
+    default_privileges: [],
+    security_labels: [],
+    ...override,
+  });
+
+describe("catalog.diff", () => {
+  test("keeps replacement-created view grants through dropped-target privilege filtering", async () => {
+    const baseline = await createEmptyCatalog(170000, "postgres");
+    const mainView = makeView();
+    const branchView = makeView({
+      definition: "SELECT id, name FROM source_table",
+      columns: [...mainView.columns, nameColumn],
+      privileges: [
+        { grantee: "view_reader", privilege: "SELECT", grantable: false },
+      ],
+    });
+
+    const main = new Catalog({
+      // oxlint-disable-next-line typescript/no-misused-spread
+      ...baseline,
+      views: { [mainView.stableId]: mainView },
+    });
+    const branch = new Catalog({
+      // oxlint-disable-next-line typescript/no-misused-spread
+      ...baseline,
+      views: { [branchView.stableId]: branchView },
+    });
+
+    const changes = diffCatalogs(main, branch);
+
+    expect(
+      changes.some((change) => change instanceof GrantViewPrivileges),
+    ).toBe(true);
+  });
+
+  test("keeps replacement-created view revokes through dropped-target privilege filtering", async () => {
+    const baseline = await createEmptyCatalog(170000, "postgres");
+    const mainView = makeView();
+    const branchView = makeView({
+      definition: "SELECT id, name FROM source_table",
+      columns: [...mainView.columns, nameColumn],
+    });
+    const postgres = makeRole("postgres", {
+      default_privileges: [
+        {
+          in_schema: "public",
+          objtype: "r",
+          grantee: "view_reader",
+          privileges: [{ privilege: "SELECT", grantable: false }],
+          is_implicit: false,
+        },
+      ],
+    });
+    const viewReader = makeRole("view_reader");
+
+    const roles = {
+      [postgres.stableId]: postgres,
+      [viewReader.stableId]: viewReader,
+    };
+    const main = new Catalog({
+      // oxlint-disable-next-line typescript/no-misused-spread
+      ...baseline,
+      roles,
+      views: { [mainView.stableId]: mainView },
+    });
+    const branch = new Catalog({
+      // oxlint-disable-next-line typescript/no-misused-spread
+      ...baseline,
+      roles,
+      views: { [branchView.stableId]: branchView },
+    });
+
+    // The recreated view inherits SELECT from default privileges, but the
+    // branch model wants no explicit reader ACL. The replacement filter must
+    // keep the generated REVOKE even though the old view stable id is dropped.
+    const changes = diffCatalogs(main, branch);
+
+    expect(
+      changes.some((change) => change instanceof RevokeViewPrivileges),
+    ).toBe(true);
+  });
+});