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

package/src/core/catalog.diff.ts

@@ -0,0 +1,275 @@
+import debug from "debug";
+import type { Catalog } from "./catalog.model.ts";
+import { expandReplaceDependencies } from "./expand-replace-dependencies.ts";
+import { normalizePostDiffChanges } from "./post-diff-normalization.ts";
+
+const debugCatalog = debug("pg-delta:catalog");
+
+import type { Change } from "./change.types.ts";
+import { diffAggregates } from "./objects/aggregate/aggregate.diff.ts";
+import { DefaultPrivilegeState } from "./objects/base.default-privileges.ts";
+import { diffCollations } from "./objects/collation/collation.diff.ts";
+import { diffDomains } from "./objects/domain/domain.diff.ts";
+import { diffEventTriggers } from "./objects/event-trigger/event-trigger.diff.ts";
+import { diffExtensions } from "./objects/extension/extension.diff.ts";
+import { diffForeignDataWrappers } from "./objects/foreign-data-wrapper/foreign-data-wrapper/foreign-data-wrapper.diff.ts";
+import { diffForeignTables } from "./objects/foreign-data-wrapper/foreign-table/foreign-table.diff.ts";
+import { diffServers } from "./objects/foreign-data-wrapper/server/server.diff.ts";
+import { diffUserMappings } from "./objects/foreign-data-wrapper/user-mapping/user-mapping.diff.ts";
+import { diffIndexes } from "./objects/index/index.diff.ts";
+import { diffMaterializedViews } from "./objects/materialized-view/materialized-view.diff.ts";
+import { diffProcedures } from "./objects/procedure/procedure.diff.ts";
+import { diffPublications } from "./objects/publication/publication.diff.ts";
+import { diffRlsPolicies } from "./objects/rls-policy/rls-policy.diff.ts";
+import {
+  GrantRoleDefaultPrivileges,
+  RevokeRoleDefaultPrivileges,
+} from "./objects/role/changes/role.privilege.ts";
+import { diffRoles } from "./objects/role/role.diff.ts";
+import { diffRules } from "./objects/rule/rule.diff.ts";
+import { diffSchemas } from "./objects/schema/schema.diff.ts";
+import { diffSequences } from "./objects/sequence/sequence.diff.ts";
+import { diffSubscriptions } from "./objects/subscription/subscription.diff.ts";
+import { diffTables } from "./objects/table/table.diff.ts";
+import { diffTriggers } from "./objects/trigger/trigger.diff.ts";
+import { diffCompositeTypes } from "./objects/type/composite-type/composite-type.diff.ts";
+import { diffEnums } from "./objects/type/enum/enum.diff.ts";
+import { diffRanges } from "./objects/type/range/range.diff.ts";
+import { stringifyWithBigInt } from "./objects/utils.ts";
+import { diffViews } from "./objects/view/view.diff.ts";
+
+type PrivilegeChange = Extract<Change, { scope: "privilege" }>;
+
+/**
+ * Get the stableId of the target object for a privilege change.
+ * Used to filter out redundant REVOKE statements for dropped objects.
+ */
+function getPrivilegeTargetStableId(change: PrivilegeChange): string {
+  switch (change.objectType) {
+    case "composite_type":
+      return change.compositeType.stableId;
+    case "domain":
+      return change.domain.stableId;
+    case "enum":
+      return change.enum.stableId;
+    case "language":
+      return change.language.stableId;
+    case "materialized_view":
+      return change.materializedView.stableId;
+    case "aggregate":
+      return change.aggregate.stableId;
+    case "procedure":
+      return change.procedure.stableId;
+    case "range":
+      return change.range.stableId;
+    case "schema":
+      return change.schema.stableId;
+    case "sequence":
+      return change.sequence.stableId;
+    case "table":
+      return change.table.stableId;
+    case "view":
+      return change.view.stableId;
+    case "foreign_data_wrapper":
+      return change.foreignDataWrapper.stableId;
+    case "server":
+      return change.server.stableId;
+    case "foreign_table":
+      return change.foreignTable.stableId;
+    default: {
+      const _exhaustive: never = change;
+      return _exhaustive;
+    }
+  }
+}
+
+export function diffCatalogs(
+  main: Catalog,
+  branch: Catalog,
+  options?: { role?: string; skipDefaultPrivilegeSubtraction?: boolean },
+) {
+  const changes: Change[] = [];
+
+  // Step 1: Diff roles first to get default privilege changes
+  const roleChanges = diffRoles(
+    { version: main.version },
+    main.roles,
+    branch.roles,
+  );
+  changes.push(...roleChanges);
+
+  // Step 2: Compute default privileges state from role changes
+  // This represents what defaults will be in effect after all ALTER DEFAULT PRIVILEGES
+  // Since ALTER DEFAULT PRIVILEGES runs before CREATE (via constraint spec),
+  // all created objects will use these final defaults.
+  //
+  // When skipDefaultPrivilegeSubtraction is true, we use an empty state so that
+  // getEffectiveDefaults always returns [] -- no privileges are subtracted and
+  // every GRANT is emitted explicitly.  This is needed for declarative export
+  // where the output must be self-contained regardless of statement execution order.
+  const defaultPrivilegeState = options?.skipDefaultPrivilegeSubtraction
+    ? new DefaultPrivilegeState({})
+    : new DefaultPrivilegeState(main.roles);
+  if (!options?.skipDefaultPrivilegeSubtraction) {
+    for (const change of roleChanges) {
+      if (change instanceof GrantRoleDefaultPrivileges) {
+        defaultPrivilegeState.applyGrant(
+          change.role.name,
+          change.objtype,
+          change.inSchema,
+          change.grantee,
+          change.privileges,
+        );
+      } else if (change instanceof RevokeRoleDefaultPrivileges) {
+        defaultPrivilegeState.applyRevoke(
+          change.role.name,
+          change.objtype,
+          change.inSchema,
+          change.grantee,
+          change.privileges,
+        );
+      }
+    }
+  }
+
+  // Step 3: Create context with default privileges state for object diffing
+  // Use the specified role for both default privilege lookups and owner comparisons if provided,
+  // otherwise use the login role (main.currentUser). This ensures that when SET ROLE is used
+  // in the migration, both default privileges and owner comparisons match what will actually
+  // happen during execution (objects will be created with the effective role as owner).
+  const effectiveUser = options?.role ?? main.currentUser;
+  const diffContext = {
+    version: main.version,
+    currentUser: effectiveUser,
+    defaultPrivilegeState,
+    mainRoles: main.roles,
+    skipDefaultPrivilegeSubtraction: options?.skipDefaultPrivilegeSubtraction,
+  };
+
+  // Step 4: Diff all other objects with default privileges context
+  changes.push(
+    ...diffAggregates(diffContext, main.aggregates, branch.aggregates),
+  );
+  changes.push(
+    ...diffCollations(diffContext, main.collations, branch.collations),
+  );
+  changes.push(
+    ...diffCompositeTypes(
+      diffContext,
+      main.compositeTypes,
+      branch.compositeTypes,
+    ),
+  );
+  changes.push(...diffDomains(diffContext, main.domains, branch.domains));
+  changes.push(...diffEnums(diffContext, main.enums, branch.enums));
+  changes.push(...diffExtensions(main.extensions, branch.extensions));
+  changes.push(
+    ...diffIndexes(main.indexes, branch.indexes, branch.indexableObjects),
+  );
+  changes.push(
+    ...diffMaterializedViews(
+      diffContext,
+      main.materializedViews,
+      branch.materializedViews,
+    ),
+  );
+  changes.push(
+    ...diffSubscriptions(diffContext, main.subscriptions, branch.subscriptions),
+  );
+  changes.push(
+    ...diffPublications(diffContext, main.publications, branch.publications),
+  );
+  changes.push(
+    ...diffProcedures(diffContext, main.procedures, branch.procedures),
+  );
+  changes.push(...diffRlsPolicies(main.rlsPolicies, branch.rlsPolicies));
+  changes.push(...diffSchemas(diffContext, main.schemas, branch.schemas));
+  changes.push(
+    ...diffSequences(
+      diffContext,
+      main.sequences,
+      branch.sequences,
+      branch.tables,
+      main.tables,
+    ),
+  );
+  changes.push(...diffTables(diffContext, main.tables, branch.tables));
+  changes.push(
+    ...diffTriggers(main.triggers, branch.triggers, branch.indexableObjects),
+  );
+  changes.push(
+    ...diffEventTriggers(diffContext, main.eventTriggers, branch.eventTriggers),
+  );
+  changes.push(...diffRules(main.rules, branch.rules));
+  changes.push(...diffRanges(diffContext, main.ranges, branch.ranges));
+  changes.push(...diffViews(diffContext, main.views, branch.views));
+  // Foreign Data Wrapper objects (in dependency order)
+  changes.push(
+    ...diffForeignDataWrappers(
+      diffContext,
+      main.foreignDataWrappers,
+      branch.foreignDataWrappers,
+    ),
+  );
+  changes.push(...diffServers(diffContext, main.servers, branch.servers));
+  changes.push(...diffUserMappings(main.userMappings, branch.userMappings));
+  changes.push(
+    ...diffForeignTables(diffContext, main.foreignTables, branch.foreignTables),
+  );
+
+  // Filter privilege changes for objects that are only being dropped.
+  // Avoid emitting redundant ACL statements for targets that will no longer exist.
+  const droppedObjectStableIds = new Set<string>();
+  const createdStableIds = new Set<string>();
+  for (const change of changes) {
+    if (change.operation === "drop" && change.scope === "object") {
+      for (const dep of change.requires) {
+        droppedObjectStableIds.add(dep);
+      }
+    }
+    if (change.operation === "create" && change.scope === "object") {
+      for (const dep of change.creates) {
+        createdStableIds.add(dep);
+      }
+    }
+  }
+  // A pure DROP does not need ACL cleanup: the target object is going away.
+  // A replacement is different: it has both DROP and CREATE for the same stable
+  // id, and its privilege ALTERs describe the ACL state of the newly created
+  // object. Keep all of them, including REVOKE/REVOKE GRANT OPTION generated to
+  // subtract privileges inherited from ALTER DEFAULT PRIVILEGES at create time.
+  const replacementStableIds = new Set(
+    [...droppedObjectStableIds].filter((id) => createdStableIds.has(id)),
+  );
+  let filteredChanges = changes.filter((change) => {
+    if (change.operation === "alter" && change.scope === "privilege") {
+      const targetStableId = getPrivilegeTargetStableId(change);
+      // Checking only privilege creates would keep replacement GRANTs but drop
+      // replacement REVOKEs, so preserve by replacement target stable id instead.
+      if (replacementStableIds.has(targetStableId)) {
+        return true;
+      }
+      return !droppedObjectStableIds.has(targetStableId);
+    }
+    return true;
+  });
+
+  const expandedDependencies = expandReplaceDependencies({
+    changes: filteredChanges,
+    mainCatalog: main,
+    branchCatalog: branch,
+    diffContext,
+  });
+  filteredChanges = normalizePostDiffChanges({
+    changes: expandedDependencies.changes,
+    replacedTableIds: expandedDependencies.replacedTableIds,
+    branchTables: branch.tables,
+  });
+
+  debugCatalog(
+    "changes catalog diff: %O",
+    stringifyWithBigInt(filteredChanges, 2),
+  );
+
+  return filteredChanges;
+}

package/src/core/catalog.filter.ts

@@ -0,0 +1,96 @@
+/**
+ * Prune a catalog to the objects that match a Filter DSL expression.
+ *
+ * The Filter DSL is defined over Change objects, so the catalog is
+ * diffed against an empty baseline first to materialize one CREATE
+ * change per object. The filter then evaluates against the same shape
+ * it would at plan time, and the surviving stableIds drive the prune.
+ *
+ * Dependency cascade is not applied. A scoped snapshot is partial by
+ * design: out-of-scope owners, roles, and types must exist on the
+ * target DB at apply time. Cascading would expand the filter beyond
+ * what the caller asked for and, in practice, collapse schema-scoped
+ * exports whose kept objects reference cluster-scoped owners.
+ */
+
+import { diffCatalogs } from "./catalog.diff.ts";
+import { Catalog, createEmptyCatalog } from "./catalog.model.ts";
+import { compileFilterDSL, type FilterDSL } from "./integrations/filter/dsl.ts";
+
+export async function filterCatalog(
+  catalog: Catalog,
+  filter: FilterDSL,
+): Promise<Catalog> {
+  if (
+    typeof filter === "object" &&
+    filter !== null &&
+    (filter as Record<string, unknown>).cascade === true
+  ) {
+    throw new Error(
+      "Filter DSL `cascade: true` is not supported by catalog-export: " +
+        "scoped snapshots are intentionally partial. Out-of-scope owners, " +
+        "roles, and types must exist on the target DB at apply time.",
+    );
+  }
+
+  const empty = await createEmptyCatalog(catalog.version, catalog.currentUser);
+  const changes = diffCatalogs(empty, catalog);
+  const filterFn = compileFilterDSL(filter);
+
+  const keep = new Set<string>();
+  for (const change of changes) {
+    if (!filterFn(change)) continue;
+    for (const id of change.creates ?? []) keep.add(id);
+  }
+
+  return pruneCatalog(catalog, keep);
+}
+
+function filterRecord<T>(
+  record: Record<string, T>,
+  keep: ReadonlySet<string>,
+): Record<string, T> {
+  return Object.fromEntries(
+    Object.entries(record).filter(([id]) => keep.has(id)),
+  );
+}
+
+function pruneCatalog(catalog: Catalog, keep: ReadonlySet<string>): Catalog {
+  const tables = filterRecord(catalog.tables, keep);
+  const materializedViews = filterRecord(catalog.materializedViews, keep);
+
+  return new Catalog({
+    aggregates: filterRecord(catalog.aggregates, keep),
+    collations: filterRecord(catalog.collations, keep),
+    compositeTypes: filterRecord(catalog.compositeTypes, keep),
+    domains: filterRecord(catalog.domains, keep),
+    enums: filterRecord(catalog.enums, keep),
+    extensions: filterRecord(catalog.extensions, keep),
+    procedures: filterRecord(catalog.procedures, keep),
+    indexes: filterRecord(catalog.indexes, keep),
+    materializedViews,
+    subscriptions: filterRecord(catalog.subscriptions, keep),
+    publications: filterRecord(catalog.publications, keep),
+    rlsPolicies: filterRecord(catalog.rlsPolicies, keep),
+    roles: filterRecord(catalog.roles, keep),
+    schemas: filterRecord(catalog.schemas, keep),
+    sequences: filterRecord(catalog.sequences, keep),
+    tables,
+    triggers: filterRecord(catalog.triggers, keep),
+    eventTriggers: filterRecord(catalog.eventTriggers, keep),
+    rules: filterRecord(catalog.rules, keep),
+    ranges: filterRecord(catalog.ranges, keep),
+    views: filterRecord(catalog.views, keep),
+    foreignDataWrappers: filterRecord(catalog.foreignDataWrappers, keep),
+    servers: filterRecord(catalog.servers, keep),
+    userMappings: filterRecord(catalog.userMappings, keep),
+    foreignTables: filterRecord(catalog.foreignTables, keep),
+    depends: catalog.depends.filter(
+      (d) =>
+        keep.has(d.dependent_stable_id) && keep.has(d.referenced_stable_id),
+    ),
+    indexableObjects: { ...tables, ...materializedViews },
+    version: catalog.version,
+    currentUser: catalog.currentUser,
+  });
+}

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

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import { createEmptyCatalog } from "./catalog.model.ts";
+
+describe("createEmptyCatalog", () => {
+  test("PG < 15 returns a minimal catalog with only a public schema", async () => {
+    const catalog = await createEmptyCatalog(140000, "myuser");
+
+    // version and currentUser forwarded
+    expect(catalog.version).toBe(140000);
+    expect(catalog.currentUser).toBe("myuser");
+
+    // public schema owned by the provided currentUser (pre-PG15 behavior)
+    const publicSchema = catalog.schemas["schema:public"];
+    expect(publicSchema).toBeDefined();
+    expect(publicSchema.owner).toBe("myuser");
+
+    // everything else is empty
+    expect(Object.keys(catalog.schemas)).toEqual(["schema:public"]);
+    const emptyRecords = [
+      catalog.aggregates,
+      catalog.collations,
+      catalog.compositeTypes,
+      catalog.domains,
+      catalog.enums,
+      catalog.extensions,
+      catalog.procedures,
+      catalog.indexes,
+      catalog.materializedViews,
+      catalog.subscriptions,
+      catalog.publications,
+      catalog.rlsPolicies,
+      catalog.roles,
+      catalog.sequences,
+      catalog.tables,
+      catalog.triggers,
+      catalog.eventTriggers,
+      catalog.rules,
+      catalog.ranges,
+      catalog.views,
+      catalog.foreignDataWrappers,
+      catalog.servers,
+      catalog.userMappings,
+      catalog.foreignTables,
+      catalog.indexableObjects,
+    ];
+    for (const record of emptyRecords) {
+      expect(record).toEqual({});
+    }
+    expect(catalog.depends).toEqual([]);
+  });
+
+  test("PG 15-16 returns a full baseline catalog from snapshot", async () => {
+    const catalog = await createEmptyCatalog(160004, "admin_user");
+
+    // version and currentUser forwarded (not hardcoded from JSON)
+    expect(catalog.version).toBe(160004);
+    expect(catalog.currentUser).toBe("admin_user");
+
+    // public schema with pg_database_owner (PG 15+ default) and ACLs
+    const publicSchema = catalog.schemas["schema:public"];
+    expect(publicSchema.owner).toBe("pg_database_owner");
+    expect(publicSchema.privileges.length).toBeGreaterThan(0);
+
+    // plpgsql extension pre-installed
+    expect(catalog.extensions["extension:plpgsql"]).toBeDefined();
+    expect(catalog.extensions["extension:plpgsql"].name).toBe("plpgsql");
+
+    // postgres superuser role with default privileges
+    const role = catalog.roles["role:postgres"];
+    expect(role.name).toBe("postgres");
+    expect(role.is_superuser).toBe(true);
+    expect(role.default_privileges.length).toBeGreaterThan(0);
+
+    // no MAINTAIN privilege (PG 17+ only)
+    const relPrivs = role.default_privileges.find(
+      (dp) => dp.objtype === "r" && dp.grantee === "postgres",
+    );
+    expect(relPrivs).toBeDefined();
+    expect(relPrivs?.privileges.map((p) => p.privilege)).not.toContain(
+      "MAINTAIN",
+    );
+
+    // dependency graph populated
+    expect(catalog.depends.length).toBeGreaterThan(0);
+  });
+
+  test("PG 17 baseline adds MAINTAIN privilege to default relation grants", async () => {
+    const catalog = await createEmptyCatalog(170009, "admin_user");
+
+    // version and currentUser forwarded
+    expect(catalog.version).toBe(170009);
+    expect(catalog.currentUser).toBe("admin_user");
+
+    // same baseline objects as PG 15-16
+    expect(catalog.extensions["extension:plpgsql"]).toBeDefined();
+    expect(catalog.roles["role:postgres"]).toBeDefined();
+    expect(catalog.depends.length).toBeGreaterThan(0);
+
+    // MAINTAIN privilege present and in alphabetical order
+    const relPrivs = catalog.roles["role:postgres"].default_privileges.find(
+      (dp) => dp.objtype === "r" && dp.grantee === "postgres",
+    );
+    expect(relPrivs).toBeDefined();
+    const privNames = relPrivs?.privileges.map((p) => p.privilege) ?? [];
+    expect(privNames).toContain("MAINTAIN");
+    expect(privNames).toEqual([...privNames].sort());
+  });
+
+  test("PG 17 patching does not mutate the cached PG 15-16 baseline", async () => {
+    // force PG 17 baseline to be built first
+    await createEmptyCatalog(170000, "postgres");
+
+    const pg16 = await createEmptyCatalog(160000, "postgres");
+    const relPrivs = pg16.roles["role:postgres"].default_privileges.find(
+      (dp) => dp.objtype === "r" && dp.grantee === "postgres",
+    );
+    expect(relPrivs).toBeDefined();
+    expect(relPrivs?.privileges.map((p) => p.privilege)).not.toContain(
+      "MAINTAIN",
+    );
+  });
+});