@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/index.d.ts

@@ -3,7 +3,16 @@
  *
  * This module exports the public API for the pg-delta library.
  */
+export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.model.ts";
+export type { CatalogSnapshot } from "./core/catalog.snapshot.ts";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.ts";
+export { exportDeclarativeSchema } from "./core/export/index.ts";
+export type { DeclarativeSchemaOutput, FileCategory, FileEntry, FileMetadata, } from "./core/export/types.ts";
 export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
 export { applyPlan } from "./core/plan/apply.ts";
+export type { CatalogInput } from "./core/plan/create.ts";
 export { createPlan } from "./core/plan/create.ts";
+export type { SqlFormatOptions } from "./core/plan/sql-format.ts";
+export { formatSqlStatements } from "./core/plan/sql-format.ts";
 export type { CreatePlanOptions, Plan } from "./core/plan/types.ts";
+export { createManagedPool } from "./core/postgres-config.ts";

package/dist/index.js

@@ -3,6 +3,14 @@
  *
  * This module exports the public API for the pg-delta library.
  */
+// Catalog model and extraction
+export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.model.js";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.js";
+// Declarative schema export
+export { exportDeclarativeSchema } from "./core/export/index.js";
+// Plan operations
 export { applyPlan } from "./core/plan/apply.js";
-// Core operations
 export { createPlan } from "./core/plan/create.js";
+export { formatSqlStatements } from "./core/plan/sql-format.js";
+// Postgres config
+export { createManagedPool } from "./core/postgres-config.js";

package/package.json

@@ -1,18 +1,47 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.20",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./integrations/supabase": "./dist/core/integrations/supabase.js"
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./integrations/supabase": {
+      "bun": "./src/core/integrations/supabase.ts",
+      "import": "./dist/core/integrations/supabase.js",
+      "require": "./dist/core/integrations/supabase.js",
+      "types": "./dist/core/integrations/supabase.d.ts",
+      "default": "./dist/core/integrations/supabase.js"
+    },
+    "./declarative": {
+      "bun": "./src/core/declarative-apply/index.ts",
+      "import": "./dist/core/declarative-apply/index.js",
+      "require": "./dist/core/declarative-apply/index.js",
+      "types": "./dist/core/declarative-apply/index.d.ts",
+      "default": "./dist/core/declarative-apply/index.js"
+    },
+    "./catalog-export": {
+      "bun": "./src/core/catalog-export/index.ts",
+      "import": "./dist/core/catalog-export/index.js",
+      "require": "./dist/core/catalog-export/index.js",
+      "types": "./dist/core/catalog-export/index.d.ts",
+      "default": "./dist/core/catalog-export/index.js"
+    }
   },
   "bin": {
     "pgdelta": "./dist/cli/bin/cli.js"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -26,45 +55,53 @@
   ],
   "author": "Supabase",
   "license": "MIT",
-  "homepage": "https://github.com/supabase/pg-delta",
+  "homepage": "https://github.com/supabase/pg-toolbelt",
   "repository": {
     "type": "git",
-    "url": "https://github.com/supabase/pg-delta.git"
+    "url": "https://github.com/supabase/pg-toolbelt.git",
+    "directory": "packages/pg-delta"
   },
-  "bugs": "https://github.com/supabase/pg-delta/issues",
+  "bugs": "https://github.com/supabase/pg-toolbelt/issues",
   "engines": {
     "node": ">=20.0.0"
   },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "docs": "typedoc",
+    "format-and-lint": "biome check . --error-on-warnings",
+    "knip": "knip",
+    "pgdelta": "bun src/cli/bin/cli.ts",
+    "sync-base-images": "bun scripts/sync-supabase-base-images.ts",
+    "test": "bun scripts/run-tests.ts",
+    "test:unit": "bun run test src/",
+    "test:integration": "bun run test tests/",
+    "update-empty-baseline": "bun scripts/update-empty-catalog-baseline.ts",
+    "version": "changeset version && bun install --no-frozen-lockfile && bun run format-and-lint --write"
+  },
   "dependencies": {
     "@stricli/core": "^1.2.4",
     "@ts-safeql/sql-tag": "^0.2.0",
+    "@supabase/pg-topo": "^1.0.0-alpha.1",
     "chalk": "^5.6.2",
     "debug": "^4.3.7",
     "pg": "^8.17.2",
+    "picomatch": "^4.0.3",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.10",
-    "@types/pg": "^8.11.10",
-    "@changesets/cli": "^2.29.8",
+    "@supabase/bun-istanbul-coverage": "workspace:*",
     "@tsconfig/node-ts": "^23.6.2",
     "@tsconfig/node24": "^24.0.3",
+    "@types/bun": "^1.3.9",
     "@types/debug": "^4.1.12",
     "@types/node": "^24.10.4",
-    "@vitest/coverage-v8": "4.0.16",
+    "@types/pg": "^8.11.10",
+    "@types/picomatch": "^4.0.2",
     "dedent": "^1.7.1",
     "knip": "^5.75.2",
     "testcontainers": "^11.10.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
-  },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "check-types": "tsc --noEmit",
-    "format-and-lint": "biome check . --error-on-warnings",
-    "knip": "knip",
-    "pgdelta": "node src/cli/bin/cli.ts",
-    "test": "vitest",
-    "version": "changeset version && pnpm install --no-frozen-lockfile && pnpm format-and-lint --write"
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/cli/app.ts

@@ -0,0 +1,52 @@
+import { buildApplication, buildRouteMap } from "@stricli/core";
+import { applyCommand } from "./commands/apply.ts";
+import { catalogExportCommand } from "./commands/catalog-export.ts";
+import { declarativeApplyCommand } from "./commands/declarative-apply.ts";
+import { declarativeExportCommand } from "./commands/declarative-export.ts";
+import { planCommand } from "./commands/plan.ts";
+import { syncCommand } from "./commands/sync.ts";
+
+const declarativeRouteMap = buildRouteMap({
+  routes: {
+    apply: declarativeApplyCommand,
+    export: declarativeExportCommand,
+  },
+  docs: {
+    brief: "Declarative schema management",
+    fullDescription: `
+Manage declarative SQL schemas.
+
+Commands:
+  apply  - Apply a declarative SQL schema to a database
+  export - Export a declarative schema from a database diff
+    `.trim(),
+  },
+});
+
+const root = buildRouteMap({
+  routes: {
+    plan: planCommand,
+    apply: applyCommand,
+    sync: syncCommand,
+    declarative: declarativeRouteMap,
+    "catalog-export": catalogExportCommand,
+  },
+  defaultCommand: "sync",
+  docs: {
+    brief: "PostgreSQL migrations made easy",
+    fullDescription: `
+pgdelta generates migration scripts by comparing two PostgreSQL databases.
+
+Commands:
+  plan           - Compute schema diff and preview changes
+  apply          - Apply a plan's migration script to a database
+  sync           - Plan and apply changes in one go
+  declarative    - Declarative schema (apply | export)
+  catalog-export - Export a database catalog as a snapshot JSON file
+    `.trim(),
+  },
+});
+
+export const app = buildApplication(root, {
+  name: "pgdelta",
+});

package/src/cli/bin/cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { run } from "@stricli/core";
+import { app } from "../app.ts";
+import { getCommandExitCode } from "../exit-code.ts";
+
+await run(app, process.argv.slice(2), { process }).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+
+const code = getCommandExitCode();
+if (code !== undefined) {
+  process.exitCode = code;
+}

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,78 @@
+/**
+ * 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 { extractCatalog } from "../../core/catalog.model.ts";
+import {
+  serializeCatalog,
+  stringifyCatalogSnapshot,
+} from "../../core/catalog.snapshot.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,
+      },
+    },
+    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
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      target: string;
+      output: string;
+      role?: string;
+    },
+  ) {
+    const { pool, close } = await createManagedPool(flags.target, {
+      role: flags.role,
+      label: "target",
+    });
+
+    try {
+      const catalog = await extractCatalog(pool);
+      const snapshot = serializeCatalog(catalog);
+      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",
+    ]);
+  });
+});