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

package/src/core/sort/utils.ts

@@ -0,0 +1,107 @@
+import type { Change } from "../change.types.ts";
+import {
+  AlterTableAlterColumnDropDefault,
+  AlterTableAlterColumnDropIdentity,
+  AlterTableAlterColumnType,
+} from "../objects/table/changes/table.alter.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)
+ *
+ * Dependency-breaking ALTERs that remove a `pg_depend` edge to another
+ * object that may be dropped in the same plan (for example
+ * `ALTER COLUMN ... DROP DEFAULT` releasing a sequence reference, or
+ * `ALTER COLUMN ... TYPE <built-in>` releasing a user-defined type
+ * reference) are routed to the drop phase. The drop phase sorts in reverse
+ * dependency order using the main catalog, so the catalog edges already
+ * in `pg_depend` order the ALTER before any dependent `DROP TYPE` /
+ * `DROP SEQUENCE` / `DROP FUNCTION` and PostgreSQL no longer rejects the
+ * drop with error 2BP01.
+ */
+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";
+    }
+
+    // Dependency-breaking column ALTERs that release a pg_depend edge.
+    // Routing these to the drop phase lets the existing catalog dependency
+    // edges (column → sequence, column → identity sequence) order them
+    // before the matching DROP statement.
+    if (
+      change instanceof AlterTableAlterColumnDropDefault ||
+      change instanceof AlterTableAlterColumnDropIdentity
+    ) {
+      return "drop";
+    }
+
+    // ALTER COLUMN ... TYPE only safely runs in the drop phase when the
+    // target type is built-in. For user-defined target types we cannot tell
+    // here whether the type is created in the same plan, and the create
+    // happens in create_alter phase, so we keep the alter in that phase to
+    // preserve the create-then-alter ordering.
+    if (
+      change instanceof AlterTableAlterColumnType &&
+      !change.column.is_custom_type
+    ) {
+      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,58 @@
+/**
+ * @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 type { Change } from "./core/change.types.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 {
+  RenderedPlanFile,
+  RenderPlanSqlOptions,
+} from "./core/plan/render.ts";
+export {
+  flattenPlanStatements,
+  renderPlanFiles,
+  renderPlanSql,
+} from "./core/plan/render.ts";
+export type { SqlFormatOptions } from "./core/plan/sql-format.ts";
+export { formatSqlStatements } from "./core/plan/sql-format.ts";
+export type {
+  CreatePlanOptions,
+  ExecutionBoundaryReason,
+  MigrationUnit,
+  Plan,
+  TransactionMode,
+} from "./core/plan/types.ts";
+export { UnorderableCycleError } from "./core/sort/unorderable-cycle-error.ts";
+
+// Postgres config
+export { createManagedPool } from "./core/postgres-config.ts";

package/src/typedoc.ts

@@ -0,0 +1,253 @@
+/**
+ * @supabase/pg-delta — API Reference
+ *
+ * This module is a dedicated documentation entry point. It re-exports only the
+ * types relevant to authoring custom integration filters and does **not** affect
+ * the public API surface exposed by the package's main entry point.
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Filter DSL
+// ---------------------------------------------------------------------------
+
+export type {
+  FilterDSL,
+  FilterPattern,
+  PathPattern,
+} from "./core/integrations/filter/dsl.ts";
+export type { FlatValue } from "./core/integrations/filter/flatten.ts";
+
+// ---------------------------------------------------------------------------
+// Integration
+// ---------------------------------------------------------------------------
+
+export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
+export type { SerializeDSL } from "./core/integrations/serialize/dsl.ts";
+export type {
+  ExtensionSerializeOptions,
+  SchemaSerializeOptions,
+  SerializeOptions,
+} from "./core/integrations/serialize/serialize.types.ts";
+
+// ---------------------------------------------------------------------------
+// Change Types — Base & Top-Level Unions
+// ---------------------------------------------------------------------------
+
+export type {
+  Change,
+  OBJECT_TYPE_TO_PROPERTY_KEY,
+} from "./core/change.types.ts";
+// Top-level union types (each combines all change variants for an object type)
+export type { AggregateChange } from "./core/objects/aggregate/changes/aggregate.types.ts";
+export { BaseChange } from "./core/objects/base.change.ts";
+export type { CollationChange } from "./core/objects/collation/changes/collation.types.ts";
+export type { DomainChange } from "./core/objects/domain/changes/domain.types.ts";
+export type { EventTriggerChange } from "./core/objects/event-trigger/changes/event-trigger.types.ts";
+export type { ExtensionChange } from "./core/objects/extension/changes/extension.types.ts";
+export type { ForeignDataWrapperChange } from "./core/objects/foreign-data-wrapper/foreign-data-wrapper.types.ts";
+export type { IndexChange } from "./core/objects/index/changes/index.types.ts";
+export type { LanguageChange } from "./core/objects/language/changes/language.types.ts";
+export type { MaterializedViewChange } from "./core/objects/materialized-view/changes/materialized-view.types.ts";
+export type { ProcedureChange } from "./core/objects/procedure/changes/procedure.types.ts";
+export type { PublicationChange } from "./core/objects/publication/changes/publication.types.ts";
+export type { RlsPolicyChange } from "./core/objects/rls-policy/changes/rls-policy.types.ts";
+export type { RoleChange } from "./core/objects/role/changes/role.types.ts";
+export type { RuleChange } from "./core/objects/rule/changes/rule.types.ts";
+export type { SchemaChange } from "./core/objects/schema/changes/schema.types.ts";
+export type { SequenceChange } from "./core/objects/sequence/changes/sequence.types.ts";
+export type { SubscriptionChange } from "./core/objects/subscription/changes/subscription.types.ts";
+export type { TableChange } from "./core/objects/table/changes/table.types.ts";
+export type { TriggerChange } from "./core/objects/trigger/changes/trigger.types.ts";
+export type { TypeChange } from "./core/objects/type/type.types.ts";
+export type { ViewChange } from "./core/objects/view/changes/view.types.ts";
+
+// ---------------------------------------------------------------------------
+// Change Types — FDW & Type Sub-Unions
+// ---------------------------------------------------------------------------
+
+// Inner FDW union renamed to avoid collision with the outer ForeignDataWrapperChange
+export type { ForeignDataWrapperChange as FDWChange } from "./core/objects/foreign-data-wrapper/foreign-data-wrapper/changes/foreign-data-wrapper.types.ts";
+export type { ForeignTableChange } from "./core/objects/foreign-data-wrapper/foreign-table/changes/foreign-table.types.ts";
+export type { ServerChange } from "./core/objects/foreign-data-wrapper/server/changes/server.types.ts";
+export type { UserMappingChange } from "./core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.types.ts";
+
+export type { CompositeTypeChange } from "./core/objects/type/composite-type/changes/composite-type.types.ts";
+export type { EnumChange } from "./core/objects/type/enum/changes/enum.types.ts";
+export type { RangeChange } from "./core/objects/type/range/changes/range.types.ts";
+
+// ---------------------------------------------------------------------------
+// Change Types — Concrete Change Classes (all object types)
+// ---------------------------------------------------------------------------
+
+// Aggregate
+export * from "./core/objects/aggregate/changes/aggregate.alter.ts";
+export * from "./core/objects/aggregate/changes/aggregate.comment.ts";
+export * from "./core/objects/aggregate/changes/aggregate.create.ts";
+export * from "./core/objects/aggregate/changes/aggregate.drop.ts";
+export * from "./core/objects/aggregate/changes/aggregate.privilege.ts";
+
+// Collation
+export * from "./core/objects/collation/changes/collation.alter.ts";
+export * from "./core/objects/collation/changes/collation.comment.ts";
+export * from "./core/objects/collation/changes/collation.create.ts";
+export * from "./core/objects/collation/changes/collation.drop.ts";
+
+// Domain
+export * from "./core/objects/domain/changes/domain.alter.ts";
+export * from "./core/objects/domain/changes/domain.comment.ts";
+export * from "./core/objects/domain/changes/domain.create.ts";
+export * from "./core/objects/domain/changes/domain.drop.ts";
+export * from "./core/objects/domain/changes/domain.privilege.ts";
+
+// Event Trigger
+export * from "./core/objects/event-trigger/changes/event-trigger.alter.ts";
+export * from "./core/objects/event-trigger/changes/event-trigger.comment.ts";
+export * from "./core/objects/event-trigger/changes/event-trigger.create.ts";
+export * from "./core/objects/event-trigger/changes/event-trigger.drop.ts";
+
+// Extension
+export * from "./core/objects/extension/changes/extension.alter.ts";
+export * from "./core/objects/extension/changes/extension.comment.ts";
+export * from "./core/objects/extension/changes/extension.create.ts";
+export * from "./core/objects/extension/changes/extension.drop.ts";
+
+// Foreign Data Wrapper — FDW wrapper
+export * from "./core/objects/foreign-data-wrapper/foreign-data-wrapper/changes/foreign-data-wrapper.alter.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-data-wrapper/changes/foreign-data-wrapper.comment.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-data-wrapper/changes/foreign-data-wrapper.create.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-data-wrapper/changes/foreign-data-wrapper.drop.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-data-wrapper/changes/foreign-data-wrapper.privilege.ts";
+
+// Foreign Data Wrapper — Foreign Table
+export * from "./core/objects/foreign-data-wrapper/foreign-table/changes/foreign-table.alter.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-table/changes/foreign-table.comment.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-table/changes/foreign-table.create.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-table/changes/foreign-table.drop.ts";
+export * from "./core/objects/foreign-data-wrapper/foreign-table/changes/foreign-table.privilege.ts";
+
+// Foreign Data Wrapper — Server
+export * from "./core/objects/foreign-data-wrapper/server/changes/server.alter.ts";
+export * from "./core/objects/foreign-data-wrapper/server/changes/server.comment.ts";
+export * from "./core/objects/foreign-data-wrapper/server/changes/server.create.ts";
+export * from "./core/objects/foreign-data-wrapper/server/changes/server.drop.ts";
+export * from "./core/objects/foreign-data-wrapper/server/changes/server.privilege.ts";
+
+// Foreign Data Wrapper — User Mapping
+export * from "./core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.alter.ts";
+export * from "./core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.create.ts";
+export * from "./core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.drop.ts";
+
+// Index
+export * from "./core/objects/index/changes/index.alter.ts";
+export * from "./core/objects/index/changes/index.comment.ts";
+export * from "./core/objects/index/changes/index.create.ts";
+export * from "./core/objects/index/changes/index.drop.ts";
+
+// Language
+export * from "./core/objects/language/changes/language.alter.ts";
+export * from "./core/objects/language/changes/language.comment.ts";
+export * from "./core/objects/language/changes/language.create.ts";
+export * from "./core/objects/language/changes/language.drop.ts";
+export * from "./core/objects/language/changes/language.privilege.ts";
+
+// Materialized View
+export * from "./core/objects/materialized-view/changes/materialized-view.alter.ts";
+export * from "./core/objects/materialized-view/changes/materialized-view.comment.ts";
+export * from "./core/objects/materialized-view/changes/materialized-view.create.ts";
+export * from "./core/objects/materialized-view/changes/materialized-view.drop.ts";
+export * from "./core/objects/materialized-view/changes/materialized-view.privilege.ts";
+
+// Procedure
+export * from "./core/objects/procedure/changes/procedure.alter.ts";
+export * from "./core/objects/procedure/changes/procedure.comment.ts";
+export * from "./core/objects/procedure/changes/procedure.create.ts";
+export * from "./core/objects/procedure/changes/procedure.drop.ts";
+export * from "./core/objects/procedure/changes/procedure.privilege.ts";
+
+// Publication
+export * from "./core/objects/publication/changes/publication.alter.ts";
+export * from "./core/objects/publication/changes/publication.comment.ts";
+export * from "./core/objects/publication/changes/publication.create.ts";
+export * from "./core/objects/publication/changes/publication.drop.ts";
+
+// RLS Policy
+export * from "./core/objects/rls-policy/changes/rls-policy.alter.ts";
+export * from "./core/objects/rls-policy/changes/rls-policy.comment.ts";
+export * from "./core/objects/rls-policy/changes/rls-policy.create.ts";
+export * from "./core/objects/rls-policy/changes/rls-policy.drop.ts";
+
+// Role
+export * from "./core/objects/role/changes/role.alter.ts";
+export * from "./core/objects/role/changes/role.comment.ts";
+export * from "./core/objects/role/changes/role.create.ts";
+export * from "./core/objects/role/changes/role.drop.ts";
+export * from "./core/objects/role/changes/role.privilege.ts";
+
+// Rule
+export * from "./core/objects/rule/changes/rule.alter.ts";
+export * from "./core/objects/rule/changes/rule.comment.ts";
+export * from "./core/objects/rule/changes/rule.create.ts";
+export * from "./core/objects/rule/changes/rule.drop.ts";
+
+// Schema
+export * from "./core/objects/schema/changes/schema.alter.ts";
+export * from "./core/objects/schema/changes/schema.comment.ts";
+export * from "./core/objects/schema/changes/schema.create.ts";
+export * from "./core/objects/schema/changes/schema.drop.ts";
+export * from "./core/objects/schema/changes/schema.privilege.ts";
+
+// Sequence
+export * from "./core/objects/sequence/changes/sequence.alter.ts";
+export * from "./core/objects/sequence/changes/sequence.comment.ts";
+export * from "./core/objects/sequence/changes/sequence.create.ts";
+export * from "./core/objects/sequence/changes/sequence.drop.ts";
+export * from "./core/objects/sequence/changes/sequence.privilege.ts";
+
+// Subscription
+export * from "./core/objects/subscription/changes/subscription.alter.ts";
+export * from "./core/objects/subscription/changes/subscription.comment.ts";
+export * from "./core/objects/subscription/changes/subscription.create.ts";
+export * from "./core/objects/subscription/changes/subscription.drop.ts";
+
+// Table
+export * from "./core/objects/table/changes/table.alter.ts";
+export * from "./core/objects/table/changes/table.comment.ts";
+export * from "./core/objects/table/changes/table.create.ts";
+export * from "./core/objects/table/changes/table.drop.ts";
+export * from "./core/objects/table/changes/table.privilege.ts";
+
+// Trigger
+export * from "./core/objects/trigger/changes/trigger.alter.ts";
+export * from "./core/objects/trigger/changes/trigger.comment.ts";
+export * from "./core/objects/trigger/changes/trigger.create.ts";
+export * from "./core/objects/trigger/changes/trigger.drop.ts";
+
+// Type — Composite
+export * from "./core/objects/type/composite-type/changes/composite-type.alter.ts";
+export * from "./core/objects/type/composite-type/changes/composite-type.comment.ts";
+export * from "./core/objects/type/composite-type/changes/composite-type.create.ts";
+export * from "./core/objects/type/composite-type/changes/composite-type.drop.ts";
+export * from "./core/objects/type/composite-type/changes/composite-type.privilege.ts";
+
+// Type — Enum
+export * from "./core/objects/type/enum/changes/enum.alter.ts";
+export * from "./core/objects/type/enum/changes/enum.comment.ts";
+export * from "./core/objects/type/enum/changes/enum.create.ts";
+export * from "./core/objects/type/enum/changes/enum.drop.ts";
+export * from "./core/objects/type/enum/changes/enum.privilege.ts";
+
+// Type — Range
+export * from "./core/objects/type/range/changes/range.alter.ts";
+export * from "./core/objects/type/range/changes/range.comment.ts";
+export * from "./core/objects/type/range/changes/range.create.ts";
+export * from "./core/objects/type/range/changes/range.drop.ts";
+export * from "./core/objects/type/range/changes/range.privilege.ts";
+
+// View
+export * from "./core/objects/view/changes/view.alter.ts";
+export * from "./core/objects/view/changes/view.comment.ts";
+export * from "./core/objects/view/changes/view.create.ts";
+export * from "./core/objects/view/changes/view.drop.ts";
+export * from "./core/objects/view/changes/view.privilege.ts";

package/dist/core/integrations/filter/extractors.d.ts

@@ -1,12 +0,0 @@
-import type { Change } from "../../change.types.ts";
-/**
- * Property extractor function that extracts a value from a change.
- */
-type PropertyExtractor = (change: Change) => string | null;
-/**
- * Registry of property extractors.
- * Maps property names to extractor functions.
- */
-export declare const PROPERTY_EXTRACTORS: Record<string, PropertyExtractor>;
-export declare function getSchema(change: Change): string | null;
-export {};

package/dist/core/integrations/filter/extractors.js

@@ -1,136 +0,0 @@
-/**
- * Registry of property extractors.
- * Maps property names to extractor functions.
- */
-export const PROPERTY_EXTRACTORS = {
-    schema: getSchema,
-    owner: getOwner,
-    member: (change) => {
-        if (change.scope === "membership") {
-            return change.member;
-        }
-        return null;
-    },
-};
-export function getSchema(change) {
-    switch (change.objectType) {
-        case "aggregate":
-            return change.aggregate.schema;
-        case "collation":
-            return change.collation.schema;
-        case "composite_type":
-            return change.compositeType.schema;
-        case "domain":
-            return change.domain.schema;
-        case "enum":
-            return change.enum.schema;
-        case "event_trigger":
-            return null;
-        case "extension":
-            return change.extension.schema;
-        case "index":
-            return change.index.schema;
-        case "language":
-            return null;
-        case "materialized_view":
-            return change.materializedView.schema;
-        case "procedure":
-            return change.procedure.schema;
-        case "publication":
-            return null;
-        case "range":
-            return change.range.schema;
-        case "rls_policy":
-            return change.policy.schema;
-        case "role":
-            return null;
-        case "rule":
-            return change.rule.schema;
-        case "schema":
-            return change.schema.name;
-        case "sequence":
-            return change.sequence.schema;
-        case "subscription":
-            return null;
-        case "table":
-            return change.table.schema;
-        case "trigger":
-            return change.trigger.schema;
-        case "view":
-            return change.view.schema;
-        case "foreign_data_wrapper":
-            return null;
-        case "server":
-            return null;
-        case "user_mapping":
-            return null;
-        case "foreign_table":
-            return change.foreignTable.schema;
-        default: {
-            // exhaustiveness check
-            const _exhaustive = change;
-            return _exhaustive;
-        }
-    }
-}
-function getOwner(change) {
-    switch (change.objectType) {
-        case "aggregate":
-            return change.aggregate.owner;
-        case "collation":
-            return change.collation.owner;
-        case "composite_type":
-            return change.compositeType.owner;
-        case "domain":
-            return change.domain.owner;
-        case "enum":
-            return change.enum.owner;
-        case "event_trigger":
-            return change.eventTrigger.owner;
-        case "extension":
-            return change.extension.owner;
-        case "index":
-            return change.index.owner;
-        case "language":
-            return change.language.owner;
-        case "materialized_view":
-            return change.materializedView.owner;
-        case "procedure":
-            return change.procedure.owner;
-        case "publication":
-            return change.publication.owner;
-        case "range":
-            return change.range.owner;
-        case "rls_policy":
-            return change.policy.owner;
-        case "role":
-            return change.role.name;
-        case "rule":
-            return change.rule.owner;
-        case "schema":
-            return change.schema.owner;
-        case "sequence":
-            return change.sequence.owner;
-        case "subscription":
-            return change.subscription.owner;
-        case "table":
-            return change.table.owner;
-        case "trigger":
-            return change.trigger.owner;
-        case "view":
-            return change.view.owner;
-        case "foreign_data_wrapper":
-            return change.foreignDataWrapper.owner;
-        case "server":
-            return change.server.owner;
-        case "user_mapping":
-            return null;
-        case "foreign_table":
-            return change.foreignTable.owner;
-        default: {
-            // exhaustiveness check
-            const _exhaustive = change;
-            return _exhaustive;
-        }
-    }
-}