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

package/dist/core/sort/logical-sort.js

@@ -8,7 +8,7 @@
  * It groups related changes together while preserving the ability for the dependency
  * resolver to reorder within groups when necessary.
  */
-import { getSchema } from "../integrations/filter/extractors.js";
+import { getSchema } from "../change-utils.js";
 import { getExecutionPhase, isMetadataStableId } from "./utils.js";
 /**
  * Object type ordering for logical grouping.
@@ -145,6 +145,25 @@ function getMainStableId(change) {
         }
         return null;
     }
+    // For default_privilege operations: group by role + schema combination (before CREATE so we group and use tiebreaker)
+    if (change.scope === "default_privilege") {
+        if (change.requires.length > 0) {
+            let grantingRole = null;
+            let schemaId = null;
+            for (const id of change.requires) {
+                if (id.startsWith("role:")) {
+                    grantingRole = id;
+                }
+                else if (id.startsWith("schema:")) {
+                    schemaId = id;
+                }
+            }
+            if (schemaId && grantingRole) {
+                return `${grantingRole}:${schemaId}`;
+            }
+            return grantingRole ?? null;
+        }
+    }
     // For CREATE operations: check if creating a constraint (sub-entity of table)
     if (change.operation === "create" && change.creates.length > 0) {
         // Iterate through creates to find the first non-metadata stable ID
@@ -182,29 +201,6 @@ function getMainStableId(change) {
         // Fallback: if all drops are metadata, use first
         return change.drops[0] ?? null;
     }
-    // For default_privilege operations: group by role + schema combination
-    // This groups all "FOR ROLE X IN SCHEMA Y" statements together
-    if (change.scope === "default_privilege") {
-        if (change.requires.length > 0) {
-            // Iterate through requires to find role and schema
-            let grantingRole = null;
-            let schemaId = null;
-            for (const id of change.requires) {
-                if (id.startsWith("role:")) {
-                    grantingRole = id;
-                }
-                else if (id.startsWith("schema:")) {
-                    schemaId = id;
-                }
-            }
-            if (schemaId && grantingRole) {
-                // Create composite key: "role:postgres:schema:public"
-                return `${grantingRole}:${schemaId}`;
-            }
-            // If no schema, just group by role
-            return grantingRole ?? null;
-        }
-    }
     // For ALTER operations: check if creating/dropping a constraint
     // Skip this for privilege/comment/default_privilege scopes (handled above)
     if (change.operation === "alter") {
@@ -291,27 +287,6 @@ function getParentStableId(change) {
     // Fallback: return first requires if available
     return requires.length > 0 ? requires[0] : null;
 }
-/**
- * Extract schema name from a change.
- * Returns the schema name if present, or null for non-schema objects.
- *
- * Uses the getSchema helper which directly accesses schema properties from change objects.
- * For default_privilege changes, accesses the inSchema property directly.
- * For event_trigger changes, groups by their function's schema.
- */
-function extractSchemaFromChange(change) {
-    // Handle default_privilege changes specially (they have inSchema property)
-    if (change.scope === "default_privilege") {
-        // TypeScript doesn't know about inSchema, but we know it exists for default_privilege changes
-        return change.inSchema ?? null;
-    }
-    // Handle event_trigger changes specially - group by their function's schema
-    if (change.objectType === "event_trigger") {
-        return change.eventTrigger.function_schema;
-    }
-    // Use the getSchema helper for all other changes
-    return getSchema(change);
-}
 /**
  * Get the effective object type for sorting purposes.
  * For sub-entities, returns the parent's object type (table/view/materialized_view).
@@ -403,8 +378,8 @@ function sortPhase(changes, phase) {
         const changeA = a.change;
         const changeB = b.change;
         // 1. Compare schemas (group objects by schema)
-        const schemaA = extractSchemaFromChange(changeA);
-        const schemaB = extractSchemaFromChange(changeB);
+        const schemaA = getSchema(changeA);
+        const schemaB = getSchema(changeB);
         // Non-schema objects (roles, languages, extensions, etc.) sort first
         // Use a special prefix to ensure they come before schema objects
         const schemaKeyA = schemaA === null ? "::" : schemaA;
@@ -525,6 +500,18 @@ function sortPhase(changes, phase) {
         if (operationOrderA !== operationOrderB) {
             return operationOrderA - operationOrderB;
         }
+        // 6b. For default_privilege: deterministic tiebreaker by objtype then grantee (canonical order for objtype)
+        if (scopeA === "default_privilege" && scopeB === "default_privilege") {
+            const defPrivA = changeA;
+            const defPrivB = changeB;
+            const objtypeOrder = (code) => ({ n: 0, r: 1, S: 2, f: 3, T: 4 })[code] ?? 99;
+            const objtypeCompare = objtypeOrder(defPrivA.objtype) - objtypeOrder(defPrivB.objtype);
+            if (objtypeCompare !== 0)
+                return objtypeCompare;
+            const granteeCompare = defPrivA.grantee.localeCompare(defPrivB.grantee);
+            if (granteeCompare !== 0)
+                return granteeCompare;
+        }
         // 7. Preserve original order (stability)
         return a.originalIndex - b.originalIndex;
     });

package/dist/core/sort/sort-changes.js

@@ -12,6 +12,7 @@
  */
 import debug from "debug";
 import { generateCustomConstraints } from "./custom-constraints.js";
+import { tryBreakCycleByChangeInjection } from "./cycle-breakers.js";
 import { printDebugGraph } from "./debug-visualization.js";
 const debugGraph = debug("pg-delta:graph");
 import { filterEdgesForCycleBreaking, getEdgesInCycle, } from "./dependency-filter.js";
@@ -20,6 +21,13 @@ import { dedupeEdges } from "./graph-utils.js";
 import { logicalSort } from "./logical-sort.js";
 import { findCycle, formatCycleError, performStableTopologicalSort, } from "./topological-sort.js";
 import { getExecutionPhase } from "./utils.js";
+// `sortPhaseChanges` caps the change-injection breaker at one round per
+// node in the initial phase: there can never be more disjoint unbreakable
+// cycles than there are change nodes (each cycle has ≥ 2 distinct nodes).
+// The cap exists only to surface a buggy breaker as `CycleError` instead
+// of an infinite loop — the actual loop-protection guarantee comes from
+// `breakerRoundSignatures`, which throws the moment the same cycle
+// reappears after a break.
 /**
  * Sort changes using dependency information from catalogs and custom constraints.
  *
@@ -63,20 +71,38 @@ function sortChangesByPhasedGraph(catalogContext, changeList) {
     return [...sortedDropPhase, ...sortedCreateAlterPhase];
 }
 /**
- * Sort changes within a phase using Constraints derived from all dependency sources.
+ * Normalize a cycle by rotating it to start with the smallest node index, so
+ * cycles that loop through the same nodes in the same direction compare equal
+ * regardless of where DFS happened to enter them.
+ */
+function normalizeCycle(cycleNodeIndexes) {
+    if (cycleNodeIndexes.length === 0)
+        return "";
+    const minIndex = Math.min(...cycleNodeIndexes);
+    const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
+    const rotated = [
+        ...cycleNodeIndexes.slice(minIndexPos),
+        ...cycleNodeIndexes.slice(0, minIndexPos),
+    ];
+    return rotated.join(",");
+}
+/**
+ * One attempt at sorting `phaseChanges`. Builds the graph from scratch,
+ * runs the iterative edge-removal cycle handler, and either returns a
+ * topologically sorted list or reports an unbreakable cycle so the caller
+ * can decide whether to dispatch a change-injection breaker.
  *
  * Algorithm:
- * 1. Build graph data (change sets and reverse indexes)
- * 2. Convert all sources to Constraints (catalog, explicit, custom constraints)
- * 3. Convert Constraints to edges
- * 4. Iteratively detect and break cycles (deduplicate edges, detect cycles, filter problematic edges)
- * 5. Perform stable topological sort on the acyclic graph
+ * 1. Build graph data (change sets and reverse indexes).
+ * 2. Convert all sources to Constraints (catalog, explicit, custom).
+ * 3. Convert Constraints to edges.
+ * 4. Iteratively detect and break cycles by removing weak edges.
+ * 5. Perform stable topological sort on the acyclic graph.
  *
- * In DROP phase, edges are inverted so drops run in reverse dependency order.
+ * In DROP phase, edges are inverted so drops run in reverse dependency
+ * order.
  */
-function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
-    if (phaseChanges.length <= 1)
-        return phaseChanges;
+function attemptSortRound(phaseChanges, dependencyRows, options) {
     // Step 1: Build graph data structures
     const graphData = buildGraphData(phaseChanges, options);
     // Step 2: Convert all sources to Constraints
@@ -90,50 +116,31 @@ function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
     ];
     // Step 3: Convert constraints to edges and deduplicate immediately
     let edges = dedupeEdges(convertConstraintsToEdges(allConstraints, options));
-    // Step 4: Iteratively detect and break cycles
-    // Track cycles we've seen to detect when filtering fails to break a cycle.
-    // The only way we loop indefinitely is if we encounter a cycle we've already seen,
-    // which means filtering didn't break it. Otherwise, we continue until all cycles are broken.
+    // Step 4: Iteratively detect and break cycles by edge filtering.
+    // We loop until no cycles remain OR we see the same cycle twice — the
+    // latter signals that edge filtering exhausted itself. At that point
+    // the caller may dispatch a change-injection breaker; if no breaker
+    // matches, the original throw path runs.
     const seenCycles = new Set();
-    /**
-     * Normalize a cycle by rotating it to start with the smallest node index.
-     * This allows us to compare cycles regardless of where they start.
-     */
-    function normalizeCycle(cycleNodeIndexes) {
-        if (cycleNodeIndexes.length === 0)
-            return "";
-        const minIndex = Math.min(...cycleNodeIndexes);
-        const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
-        const rotated = [
-            ...cycleNodeIndexes.slice(minIndexPos),
-            ...cycleNodeIndexes.slice(0, minIndexPos),
-        ];
-        return rotated.join(",");
-    }
     while (true) {
-        // Edge deduplication moved outside loop
         const edgePairs = edgesToPairs(edges);
-        // Detect cycles
         const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
-        if (!cycleNodeIndexes) {
-            // No cycles found, we're done
+        if (!cycleNodeIndexes)
             break;
-        }
-        // Normalize cycle to check if we've seen it before
         const cycleSignature = normalizeCycle(cycleNodeIndexes);
         if (seenCycles.has(cycleSignature)) {
-            // We've seen this cycle before - filtering didn't break it
-            // Get edges involved in the cycle for detailed error message
-            const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
-            throw new Error(formatCycleError(cycleNodeIndexes, phaseChanges, cycleEdges));
+            // Edge filtering can't break this cycle. Report it back to the
+            // caller so it can try change-injection before throwing.
+            return {
+                kind: "unbreakable",
+                cycleNodeIndexes,
+                cycleEdges: getEdgesInCycle(cycleNodeIndexes, edges),
+            };
         }
-        // Track this cycle
         seenCycles.add(cycleSignature);
-        // Filter only edges involved in the cycle to break it
         edges = filterEdgesForCycleBreaking(edges, cycleNodeIndexes, phaseChanges, graphData);
     }
     const finalEdgePairs = edgesToPairs(edges);
-    // Debug visualization
     if (debugGraph.enabled) {
         printDebugGraph(phaseChanges, graphData, finalEdgePairs, dependencyRows, allConstraints);
     }
@@ -143,5 +150,52 @@ function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
         // This should never happen if findCycle returned null, but guard anyway
         throw new Error("CycleError: dependency graph contains a cycle");
     }
-    return topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]);
+    return {
+        kind: "sorted",
+        sorted: topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]),
+    };
+}
+/**
+ * Sort changes within a phase. Tries `attemptSortRound`; on an unbreakable
+ * cycle, dispatches to `tryBreakCycleByChangeInjection`, retries with the
+ * rewritten changes, and bails after `MAX_CYCLE_BREAKER_ROUNDS` to surface
+ * a buggy breaker as `CycleError` instead of an infinite loop.
+ *
+ * Best case (no cycles, the vast majority of plans): one round, no
+ * change-injection breaker code runs at all.
+ */
+function sortPhaseChanges(initialPhaseChanges, dependencyRows, options = {}) {
+    if (initialPhaseChanges.length <= 1)
+        return initialPhaseChanges;
+    let phaseChanges = initialPhaseChanges;
+    const breakerRoundSignatures = new Set();
+    // `attemptSortRound` returns at most one unbreakable cycle per call,
+    // so a phase with K independent unbreakable cycles needs K+1 rounds.
+    // Every cycle contains ≥ 2 distinct change nodes, so the maximum
+    // possible value of K is `floor(initialPhaseChanges.length / 2)` —
+    // using `initialPhaseChanges.length` itself is therefore a real upper
+    // bound with one round of slack (and matches the early-return guard
+    // above, which already excluded length-0 and length-1 phases).
+    const maxRounds = initialPhaseChanges.length;
+    for (let round = 0; round <= maxRounds; round++) {
+        const result = attemptSortRound(phaseChanges, dependencyRows, options);
+        if (result.kind === "sorted")
+            return result.sorted;
+        // Edge filtering hit an unbreakable cycle. Try the change-injection
+        // breakers (FK pattern, publication↔column pattern). If none matches,
+        // throw with the same diagnostic the original code emitted.
+        const broken = tryBreakCycleByChangeInjection(result.cycleNodeIndexes, phaseChanges);
+        if (broken === null) {
+            throw new Error(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges));
+        }
+        // Loop guard: if the same cycle node-set re-appears after a break,
+        // the breaker isn't making progress. Throw with full context.
+        const signature = normalizeCycle(result.cycleNodeIndexes);
+        if (breakerRoundSignatures.has(signature)) {
+            throw new Error(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges));
+        }
+        breakerRoundSignatures.add(signature);
+        phaseChanges = broken;
+    }
+    throw new Error(`CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`);
 }

package/dist/core/test-utils/assert-valid-sql.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export declare function assertValidSql(sql: string): Promise<void>;

package/dist/core/test-utils/assert-valid-sql.js

@@ -0,0 +1,19 @@
+import { validateSqlSyntax } from "@supabase/pg-topo";
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export async function assertValidSql(sql) {
+    try {
+        await validateSqlSyntax(sql);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown parser error";
+        throw new Error(`Invalid SQL syntax: ${message}\nSQL: ${sql}`);
+    }
+}

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.21",
   "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;
+  },
+});