@supabase/pg-delta 1.0.0-alpha.0 → 1.0.0-alpha.10

package/src/core/sort/types.ts

@@ -0,0 +1,112 @@
+/**
+ * pg_depend rows that matter for ordering.
+ *
+ * These represent dependency relationships extracted from PostgreSQL's pg_depend catalog.
+ */
+export type PgDependRow = {
+  /** Object that depends on `referenced_stable_id`. */
+  dependent_stable_id: string;
+  /** Object being depended upon. */
+  referenced_stable_id: string;
+  /**
+   * Dependency type as defined in PostgreSQL's pg_depend.deptype.
+   *
+   * - "n" (normal): Ordinary dependency — if the referenced object is dropped, the dependent object is also dropped automatically.
+   * - "a" (auto): Automatically created dependency — the dependent object was created as a result of creating the referenced object,
+   *   and should be dropped automatically when the referenced object is dropped, but not otherwise treated as a strong link.
+   * - "i" (internal): Internal dependency — the dependent object is a low-level part of the referenced object.
+   */
+  deptype: "n" | "a" | "i";
+};
+
+/**
+ * Constraint representing that one change must come before another.
+ *
+ * Unified abstraction for all ordering requirements:
+ * - Catalog dependencies (from pg_depend) → Constraints
+ * - Explicit requirements (from Change.requires) → Constraints
+ * - Custom constraints (change-to-change rules) → Constraints
+ */
+export type Constraint =
+  | CatalogConstraint
+  | ExplicitConstraint
+  | CustomConstraint;
+
+/**
+ * Base constraint properties shared by all constraint types.
+ */
+interface BaseConstraint {
+  /** Index of the change that must come first */
+  sourceChangeIndex: number;
+  /** Index of the change that must come after */
+  targetChangeIndex: number;
+}
+
+/**
+ * Constraint from catalog dependencies (pg_depend).
+ * Always has both dependent and referenced stable IDs.
+ */
+interface CatalogConstraint extends BaseConstraint {
+  source: "catalog";
+  /** The stable ID dependency that led to this constraint */
+  reason: {
+    /** The stable ID that depends on referencedStableId */
+    dependentStableId: string;
+    /** The stable ID being depended upon */
+    referencedStableId: string;
+  };
+}
+
+/**
+ * Constraint from explicit requirements (Change.requires).
+ * Always has referencedStableId, but dependentStableId is optional
+ * if the change doesn't create anything.
+ */
+interface ExplicitConstraint extends BaseConstraint {
+  source: "explicit";
+  /** The stable ID dependency that led to this constraint */
+  reason: {
+    /** The stable ID that depends on referencedStableId (undefined if change doesn't create anything) */
+    dependentStableId?: string;
+    /** The stable ID being depended upon */
+    referencedStableId: string;
+  };
+}
+
+/**
+ * Constraint from custom constraint functions.
+ * No reason field since these are direct change-to-change ordering rules.
+ */
+interface CustomConstraint extends BaseConstraint {
+  source: "custom";
+  /** Optional description for debugging */
+  description?: string;
+}
+
+export interface PhaseSortOptions {
+  /** If true, invert edges so drops run in reverse dependency order. */
+  invert?: boolean;
+}
+
+/**
+ * Edge with its originating constraint for filtering purposes.
+ */
+export interface Edge {
+  sourceIndex: number;
+  targetIndex: number;
+  constraint: Constraint;
+}
+
+/**
+ * Graph data structures for converting dependencies to Constraints.
+ */
+export interface GraphData {
+  /** Maps each change index to the set of stable IDs it creates. */
+  createdStableIdSets: Array<Set<string>>;
+  /** Maps each change index to the set of stable IDs it explicitly requires. */
+  explicitRequirementSets: Array<Set<string>>;
+  /** Maps a stable ID to the set of change indices that create it. */
+  changeIndexesByCreatedId: Map<string, Set<number>>;
+  /** Maps a stable ID to the set of change indices that explicitly require it. */
+  changeIndexesByExplicitRequirementId: Map<string, Set<number>>;
+}

package/src/core/sort/utils.ts

@@ -0,0 +1,69 @@
+import type { Change } from "../change.types.ts";
+
+/**
+ * Execution phases for changes.
+ */
+export type Phase = "drop" | "create_alter_object";
+
+/**
+ * Check if a stable ID represents metadata (ACL, default privileges, comments, etc.)
+ * rather than an actual database object.
+ *
+ * Unified check used by both logical sorting and dependency sorting.
+ */
+export function isMetadataStableId(stableId: string): boolean {
+  return (
+    stableId.startsWith("acl:") ||
+    stableId.startsWith("defacl:") ||
+    stableId.startsWith("aclcol:") ||
+    stableId.startsWith("membership:") ||
+    stableId.startsWith("comment:")
+  );
+}
+
+/**
+ * Determine the execution phase for a change based on its properties.
+ *
+ * Rules:
+ * - DROP operations → drop phase
+ * - CREATE operations → create_alter_object phase
+ * - ALTER operations with scope="privilege" → create_alter_object phase (metadata changes)
+ * - ALTER operations that drop actual objects → drop phase (destructive ALTER)
+ * - ALTER operations that don't drop objects → create_alter_object phase (non-destructive ALTER)
+ */
+export function getExecutionPhase(change: Change): Phase {
+  // DROP operations always go to drop phase
+  if (change.operation === "drop") {
+    return "drop";
+  }
+
+  // CREATE operations always go to create_alter phase
+  if (change.operation === "create") {
+    return "create_alter_object";
+  }
+
+  // For ALTER operations, determine based on what they do
+  if (change.operation === "alter") {
+    // Privilege changes (metadata) always go to create_alter phase
+    if (change.scope === "privilege") {
+      return "create_alter_object";
+    }
+
+    // Check if this ALTER drops actual objects (not metadata)
+    const droppedIds = change.drops ?? [];
+    const dropsObjects = droppedIds.some(
+      (id: string) => !isMetadataStableId(id),
+    );
+
+    if (dropsObjects) {
+      // Destructive ALTER (DROP COLUMN, DROP CONSTRAINT, etc.) → drop phase
+      return "drop";
+    }
+
+    // Non-destructive ALTER (ADD COLUMN, GRANT, etc.) → create_alter phase
+    return "create_alter_object";
+  }
+
+  // Safe default
+  return "create_alter_object";
+}

package/src/core/test-utils/assert-valid-sql.ts

@@ -0,0 +1,20 @@
+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: string): Promise<void> {
+  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/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @supabase/pg-delta - PostgreSQL migrations made easy
+ *
+ * This module exports the public API for the pg-delta library.
+ */
+
+// Catalog model and extraction
+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";
+
+// Declarative schema export
+export { exportDeclarativeSchema } from "./core/export/index.ts";
+export type {
+  DeclarativeSchemaOutput,
+  FileCategory,
+  FileEntry,
+  FileMetadata,
+} from "./core/export/types.ts";
+
+// Integrations
+export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
+
+// Plan operations
+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";
+
+// Postgres config
+export { createManagedPool } from "./core/postgres-config.ts";

package/dist/core/index.d.ts

@@ -1,15 +0,0 @@
-/**
- * @supabase/pg-delta - PostgreSQL migrations made easy
- *
- * This module exports the public API for the pg-delta library.
- */
-export type { ChangeGroup, ChangeScope, ChildObjectType, ClusterGroup, ClusterObjectType, CreatePlanOptions, HierarchicalPlan, MaterializedViewChildren, ObjectType, ParentType, Plan, SchemaGroup, TableChildren, TypeGroup, } from "./plan/index.ts";
-export { createPlan, groupChangesHierarchically, } from "./plan/index.ts";
-export type { Integration } from "./integrations/integration.types.ts";
-export { diffCatalogs } from "./catalog.diff.ts";
-export { Catalog, extractCatalog } from "./catalog.model.ts";
-export type { Change } from "./change.types.ts";
-export type { DiffContext } from "./context.ts";
-export { buildPlanScopeFingerprint, collectStableIds, hashStableIds, sha256, } from "./fingerprint.ts";
-export { postgresConfig } from "./postgres-config.ts";
-export { sortChanges } from "./sort/sort-changes.ts";

package/dist/core/index.js

@@ -1,14 +0,0 @@
-/**
- * @supabase/pg-delta - PostgreSQL migrations made easy
- *
- * This module exports the public API for the pg-delta library.
- */
-export { createPlan, groupChangesHierarchically, } from "./plan/index.js";
-// =============================================================================
-// Low-level APIs (for advanced usage)
-// =============================================================================
-export { diffCatalogs } from "./catalog.diff.js";
-export { Catalog, extractCatalog } from "./catalog.model.js";
-export { buildPlanScopeFingerprint, collectStableIds, hashStableIds, sha256, } from "./fingerprint.js";
-export { postgresConfig } from "./postgres-config.js";
-export { sortChanges } from "./sort/sort-changes.js";

package/dist/core/main.d.ts

@@ -1,5 +0,0 @@
-import type { Change } from "./change.types.ts";
-import type { Integration } from "./integrations/integration.types.ts";
-export type ChangeFilter = (change: Change) => boolean;
-export type ChangeSerializer = (change: Change) => string | undefined;
-export type MainOptions = Integration;

package/dist/core/main.js

@@ -1,44 +0,0 @@
-import postgres from "postgres";
-import { diffCatalogs } from "./catalog.diff.js";
-import { extractCatalog } from "./catalog.model.js";
-import { postgresConfig } from "./postgres-config.js";
-import { sortChanges } from "./sort/sort-changes.js";
-async function _main(mainDatabaseUrl, branchDatabaseUrl, options = {}) {
-    const mainSql = postgres(mainDatabaseUrl, postgresConfig);
-    const branchSql = postgres(branchDatabaseUrl, postgresConfig);
-    const [mainCatalog, branchCatalog] = await Promise.all([
-        extractCatalog(mainSql),
-        extractCatalog(branchSql),
-    ]);
-    await Promise.all([mainSql.end(), branchSql.end()]);
-    const changes = diffCatalogs(mainCatalog, branchCatalog);
-    // Use provided options as integration (optional)
-    const integration = options ?? {};
-    // Apply filter if provided
-    const ctx = { mainCatalog, branchCatalog };
-    let filteredChanges = changes;
-    const integrationFilter = integration.filter;
-    if (integrationFilter) {
-        filteredChanges = filteredChanges.filter((change) => integrationFilter(change));
-    }
-    if (filteredChanges.length === 0) {
-        return null;
-    }
-    const sortedChanges = sortChanges(ctx, filteredChanges);
-    const hasRoutineChanges = sortedChanges.some((change) => change.objectType === "procedure" || change.objectType === "aggregate");
-    const sessionConfig = hasRoutineChanges
-        ? ["SET check_function_bodies = false"]
-        : [];
-    // Build migration script
-    const scriptParts = [];
-    scriptParts.push(...sessionConfig);
-    // Serialize changes using integration serialize hook (applies masking) or fallback
-    const changeStatements = sortedChanges.map((change) => {
-        return integration.serialize?.(change) ?? change.serialize();
-    });
-    scriptParts.push(...changeStatements);
-    const migrationScript = `${scriptParts.join(";\n\n")};`;
-    return {
-        migrationScript,
-    };
-}