@supabase/pg-delta 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/core/objects/base.privilege-diff.ts

@@ -0,0 +1,447 @@
+import z from "zod";
+import type { Change } from "../change.types.ts";
+import type { BaseChange } from "./base.change.ts";
+
+/**
+ * Privilege properties that all privilege objects share.
+ */
+export const privilegePropsSchema = z.object({
+  grantee: z.string(),
+  privilege: z.string(),
+  grantable: z.boolean(),
+  columns: z.array(z.string()).nullable().optional(),
+});
+
+export type PrivilegeProps = z.infer<typeof privilegePropsSchema>;
+
+/**
+ * Result of privilege diffing for a single grantee
+ */
+interface PrivilegeDiffResult<T extends PrivilegeProps> {
+  grants: T[];
+  revokes: T[];
+  revokeGrantOption: string[];
+}
+
+/**
+ * Groups privileges by grantee for efficient diffing
+ */
+function groupPrivilegesByGrantee<T extends PrivilegeProps>(
+  privileges: T[],
+): Map<string, T[]> {
+  const byGrantee = new Map<string, T[]>();
+
+  for (const privilege of privileges) {
+    const existing = byGrantee.get(privilege.grantee) || [];
+    existing.push(privilege);
+    byGrantee.set(privilege.grantee, existing);
+  }
+
+  return byGrantee;
+}
+
+/**
+ * Diffs privileges for a single grantee between main and branch
+ */
+function diffPrivilegesForGrantee<T extends PrivilegeProps>(
+  mainPrivs: T[],
+  branchPrivs: T[],
+): PrivilegeDiffResult<T> {
+  // Create comparison key - always include columns (null for object-level privileges)
+  const toKey = (p: T) => {
+    const cols = p.columns || [];
+    return `${p.privilege}:${p.grantable}:${cols.sort().join(",")}`;
+  };
+
+  // Create key-to-object mappings to retain original data structures
+  const mainKeyToObj = new Map(mainPrivs.map((p) => [toKey(p), p]));
+  const branchKeyToObj = new Map(branchPrivs.map((p) => [toKey(p), p]));
+
+  const aSet = new Set(mainPrivs.map(toKey));
+  const bSet = new Set(branchPrivs.map(toKey));
+
+  const grants: T[] = [];
+  const revokes: T[] = [];
+  const revokeGrantOption: string[] = [];
+
+  // Find privileges to grant
+  for (const key of bSet) {
+    if (!aSet.has(key)) {
+      const obj = branchKeyToObj.get(key);
+      if (obj) grants.push(obj);
+    }
+  }
+
+  // Find privileges to revoke
+  for (const key of aSet) {
+    if (!bSet.has(key)) {
+      const obj = mainKeyToObj.get(key);
+      if (!obj) continue;
+
+      const wasGrantable = obj.grantable;
+
+      // Upgrade: base -> with grant option (no base revoke)
+      const upgradedKey = key.replace(":false", ":true");
+      const upgraded = !wasGrantable && bSet.has(upgradedKey);
+      if (upgraded) continue;
+
+      // If only grantable flipped from true to false, emit REVOKE GRANT OPTION FOR
+      const stillHasBase = checkStillHasBase(branchPrivs, obj.privilege, key);
+      if (wasGrantable && stillHasBase) {
+        revokeGrantOption.push(obj.privilege);
+      } else {
+        revokes.push(obj);
+      }
+    }
+  }
+
+  return { grants, revokes, revokeGrantOption };
+}
+
+/**
+ * Check if a privilege still exists in the target set
+ */
+function checkStillHasBase<T extends PrivilegeProps>(
+  targetPrivs: T[],
+  privilege: string,
+  key: string,
+): boolean {
+  const [, , columnsStr] = key.split(":");
+  return targetPrivs.some(
+    (p) =>
+      p.privilege === privilege &&
+      (p.columns || []).sort().join(",") === columnsStr,
+  );
+}
+
+/**
+ * Groups privileges by grantable flag for efficient SQL generation
+ */
+function groupPrivilegesByGrantable<T extends PrivilegeProps>(
+  privileges: T[],
+): Map<boolean, T[]> {
+  const groups = new Map<boolean, T[]>();
+
+  for (const privilege of privileges) {
+    const arr = groups.get(privilege.grantable) ?? [];
+    arr.push(privilege);
+    groups.set(privilege.grantable, arr);
+  }
+
+  return groups;
+}
+
+/**
+ * Groups privileges by columns and grantable flag
+ */
+function groupPrivilegesByColumns<T extends PrivilegeProps>(
+  privileges: T[],
+): Map<string, { columns?: string[]; byGrant: Map<boolean, Set<string>> }> {
+  const groups = new Map<
+    string,
+    { columns?: string[]; byGrant: Map<boolean, Set<string>> }
+  >();
+
+  for (const privilege of privileges) {
+    const key = privilege.columns ? privilege.columns.sort().join(",") : "";
+
+    if (!groups.has(key)) {
+      groups.set(key, {
+        columns: privilege.columns ? [...privilege.columns] : undefined,
+        byGrant: new Map(),
+      });
+    }
+
+    const group = groups.get(key);
+    if (!group) continue;
+
+    if (!group.byGrant.has(privilege.grantable)) {
+      group.byGrant.set(privilege.grantable, new Set());
+    }
+
+    const privSet = group.byGrant.get(privilege.grantable);
+    if (!privSet) continue;
+
+    privSet.add(privilege.privilege);
+  }
+
+  return groups;
+}
+
+/**
+ * Filters out PUBLIC's built-in default privileges that PostgreSQL automatically grants
+ * when creating certain object types. This prevents generating unnecessary GRANT statements
+ * for privileges that PostgreSQL grants automatically.
+ *
+ * Reference: PostgreSQL 17 Documentation, Table 5.2 "Summary of Access Privileges"
+ * https://www.postgresql.org/docs/17/ddl-priv.html
+ *
+ * Objects with default PUBLIC privileges:
+ * - Functions/Procedures/Aggregates: EXECUTE
+ * - Types/Domains/Enums/Ranges/Composite Types: USAGE
+ * - Languages: USAGE
+ *
+ * Objects WITHOUT default PUBLIC privileges (so we should generate GRANT statements):
+ * - Tables, Views, Materialized Views, Sequences, Schemas, etc.
+ */
+export function filterPublicBuiltInDefaults<T extends PrivilegeProps>(
+  objectType: Change["objectType"],
+  privileges: T[],
+): T[] {
+  // Only filter PUBLIC privileges
+  return privileges.filter((priv) => {
+    if (priv.grantee !== "PUBLIC") {
+      return true; // Keep all non-PUBLIC privileges
+    }
+
+    // Check if this is a built-in default privilege for this object type
+    switch (objectType) {
+      case "procedure":
+      case "aggregate":
+        // Functions/Procedures/Aggregates: EXECUTE is granted to PUBLIC by default
+        // Filter it out so we don't generate unnecessary GRANT EXECUTE TO PUBLIC
+        return priv.privilege !== "EXECUTE";
+
+      case "domain":
+      case "enum":
+      case "range":
+      case "composite_type":
+        // Types/Domains/Enums/Ranges/Composite Types: USAGE is granted to PUBLIC by default
+        // Filter it out so we don't generate unnecessary GRANT USAGE TO PUBLIC
+        return priv.privilege !== "USAGE";
+
+      case "language":
+        // Languages: USAGE is granted to PUBLIC by default
+        // Filter it out so we don't generate unnecessary GRANT USAGE TO PUBLIC
+        return priv.privilege !== "USAGE";
+
+      default:
+        // For other object types (tables, views, sequences, schemas, etc.),
+        // PUBLIC has NO default privileges, so we should keep all PUBLIC privileges
+        // and generate GRANT statements for them
+        return true;
+    }
+  });
+}
+
+/**
+ * Filter out owner privileges from a privilege list.
+ * Owner privileges are implicit (owner always has ALL) and shouldn't be compared.
+ */
+function filterOwnerPrivileges<T extends PrivilegeProps>(
+  privileges: T[],
+  owner: string,
+): T[] {
+  return privileges.filter((p) => p.grantee !== owner);
+}
+
+/**
+ * Generic privilege diffing function that works for any object type
+ */
+export function diffPrivileges<T extends PrivilegeProps>(
+  mainPrivileges: T[],
+  branchPrivileges: T[],
+  owner?: string,
+): Map<string, PrivilegeDiffResult<T>> {
+  // Filter out owner privileges if owner is provided
+  const mainFiltered = owner
+    ? filterOwnerPrivileges(mainPrivileges, owner)
+    : mainPrivileges;
+  const branchFiltered = owner
+    ? filterOwnerPrivileges(branchPrivileges, owner)
+    : branchPrivileges;
+
+  const mainByGrantee = groupPrivilegesByGrantee(mainFiltered);
+  const branchByGrantee = groupPrivilegesByGrantee(branchFiltered);
+
+  // Get all grantees
+  const allGrantees = new Set([
+    ...mainByGrantee.keys(),
+    ...branchByGrantee.keys(),
+  ]);
+
+  const results = new Map<string, PrivilegeDiffResult<T>>();
+
+  for (const grantee of allGrantees) {
+    const mainPrivs = mainByGrantee.get(grantee) || [];
+    const branchPrivs = branchByGrantee.get(grantee) || [];
+
+    const result = diffPrivilegesForGrantee(mainPrivs, branchPrivs);
+    results.set(grantee, result);
+  }
+
+  return results;
+}
+
+// ==== Privilege Change Emission Helpers ====
+//
+// These helpers convert the output of `diffPrivileges` (per-grantee grant /
+// revoke / revoke-grant-option lists) into concrete Change instances so that
+// individual object diffs don't have to repeat the same iteration and grouping
+// logic.
+//
+// Callers pass a `PrivilegeChangeFactories` bag containing the three class
+// constructors (Grant, Revoke, RevokeGrantOption) for their object type.  The
+// helpers instantiate them with a common props shape: an object reference keyed
+// by `objectKey`, a `grantee`, `privileges` or `privilegeNames`, an optional
+// `version`, and (for column-level privileges) optional `columns`.
+
+/**
+ * Factory constructors for Grant / Revoke / RevokeGrantOption change classes.
+ * Every object type provides its own concrete classes.  The `any` props type
+ * is intentional: the helpers build props with a computed `[objectKey]` key
+ * whose name varies per object type, so no single concrete type can unify
+ * all call sites without an unsafe cast elsewhere.
+ */
+interface PrivilegeChangeFactories {
+  Grant: new (
+    // biome-ignore lint/suspicious/noExplicitAny: factory accepts heterogeneous prop bags keyed by object type
+    props: any,
+  ) => BaseChange;
+  Revoke: new (
+    // biome-ignore lint/suspicious/noExplicitAny: factory accepts heterogeneous prop bags keyed by object type
+    props: any,
+  ) => BaseChange;
+  RevokeGrantOption: new (
+    // biome-ignore lint/suspicious/noExplicitAny: factory accepts heterogeneous prop bags keyed by object type
+    props: any,
+  ) => BaseChange;
+}
+
+/**
+ * Emit privilege changes for object-level privileges (schema, sequence,
+ * procedure, etc.).
+ *
+ * For each grantee in `privilegeResults` the function groups grants and revokes
+ * by the `grantable` flag and pushes one change per group.  Revoke-grant-option
+ * entries produce a single change carrying `privilegeNames`.
+ *
+ * `grantTarget` is the *branch* object (the desired state) while `revokeTarget`
+ * is the *main* object (the current state), so that GRANTs reference the
+ * newly-created/altered object and REVOKEs reference the existing one.
+ */
+export function emitObjectPrivilegeChanges(
+  privilegeResults: Map<string, PrivilegeDiffResult<PrivilegeProps>>,
+  grantTarget: unknown,
+  revokeTarget: unknown,
+  objectKey: string,
+  factories: PrivilegeChangeFactories,
+  version?: number,
+): BaseChange[] {
+  const changes: BaseChange[] = [];
+
+  for (const [grantee, result] of privilegeResults) {
+    for (const [, revokes] of groupPrivilegesByGrantable(result.revokes)) {
+      changes.push(
+        new factories.Revoke({
+          [objectKey]: revokeTarget,
+          privileges: revokes,
+          grantee,
+          version,
+        }),
+      );
+    }
+    if (result.revokeGrantOption.length > 0) {
+      changes.push(
+        new factories.RevokeGrantOption({
+          [objectKey]: revokeTarget,
+          privilegeNames: result.revokeGrantOption,
+          grantee,
+          version,
+        }),
+      );
+    }
+    for (const [, grants] of groupPrivilegesByGrantable(result.grants)) {
+      changes.push(
+        new factories.Grant({
+          [objectKey]: grantTarget,
+          privileges: grants,
+          grantee,
+          version,
+        }),
+      );
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Emit privilege changes for column-level privileges (table, view,
+ * materialized view).
+ *
+ * Like {@link emitObjectPrivilegeChanges} but groups by column set (via
+ * `groupPrivilegesByColumns`) instead of only by grantable.  For
+ * revoke-grant-option the column sets come from `sourcePrivileges` so that
+ * `REVOKE GRANT OPTION FOR` is emitted per column set that originally carried
+ * the privilege.
+ */
+export function emitColumnPrivilegeChanges(
+  privilegeResults: Map<string, PrivilegeDiffResult<PrivilegeProps>>,
+  grantTarget: unknown,
+  revokeTarget: unknown,
+  objectKey: string,
+  factories: PrivilegeChangeFactories,
+  sourcePrivileges: PrivilegeProps[],
+  version?: number,
+): BaseChange[] {
+  const changes: BaseChange[] = [];
+
+  for (const [grantee, result] of privilegeResults) {
+    for (const [, group] of groupPrivilegesByColumns(result.revokes)) {
+      const allPrivileges = new Set<string>();
+      for (const [, privSet] of group.byGrant) {
+        for (const priv of privSet) {
+          allPrivileges.add(priv);
+        }
+      }
+      changes.push(
+        new factories.Revoke({
+          [objectKey]: revokeTarget,
+          privileges: [...allPrivileges].map((p) => ({
+            privilege: p,
+            grantable: false,
+          })),
+          grantee,
+          columns: group.columns,
+          version,
+        }),
+      );
+    }
+    if (result.revokeGrantOption.length > 0) {
+      const sourcePrivsForGrantee = sourcePrivileges.filter(
+        (p) => p.grantee === grantee,
+      );
+      for (const [, group] of groupPrivilegesByColumns(
+        sourcePrivsForGrantee.filter((p) =>
+          result.revokeGrantOption.includes(p.privilege),
+        ),
+      )) {
+        changes.push(
+          new factories.RevokeGrantOption({
+            [objectKey]: revokeTarget,
+            privilegeNames: result.revokeGrantOption,
+            grantee,
+            columns: group.columns,
+            version,
+          }),
+        );
+      }
+    }
+    for (const [, group] of groupPrivilegesByColumns(result.grants)) {
+      for (const [grantable, privSet] of group.byGrant) {
+        changes.push(
+          new factories.Grant({
+            [objectKey]: grantTarget,
+            privileges: [...privSet].map((p) => ({ privilege: p, grantable })),
+            grantee,
+            columns: group.columns,
+            version,
+          }),
+        );
+      }
+    }
+  }
+
+  return changes;
+}

package/src/core/objects/base.privilege.ts

@@ -0,0 +1,191 @@
+/**
+ * Base utilities and helpers for object privilege changes.
+ * These functions support GRANT/REVOKE operations across different database objects.
+ */
+
+import type { PrivilegeProps } from "./base.privilege-diff.ts";
+
+/**
+ * Returns the complete set of available privileges for a given object kind.
+ * This is used to determine whether a privilege list represents "ALL PRIVILEGES".
+ *
+ * @param kind - The PostgreSQL object kind (TABLE, VIEW, SEQUENCE, etc.)
+ * @param version - The PostgreSQL version number (e.g., 170000 for 17.0.0)
+ * @returns An array of privilege names available for this object kind
+ */
+function objectPrivilegeUniverse(
+  kind: string,
+  version: number | undefined,
+): string[] {
+  switch (kind) {
+    case "TABLE": {
+      const includesMaintain = (version ?? 170000) >= 170000;
+      return [
+        "DELETE",
+        "INSERT",
+        ...(includesMaintain ? (["MAINTAIN"] as const) : []),
+        "REFERENCES",
+        "SELECT",
+        "TRIGGER",
+        "TRUNCATE",
+        "UPDATE",
+      ];
+    }
+    case "VIEW": {
+      // Per PostgreSQL docs, views are table-like and share the table privilege set
+      // for GRANT/REVOKE purposes. MAINTAIN exists on PostgreSQL >= 17
+      const includesMaintain = (version ?? 170000) >= 170000;
+      return [
+        "DELETE",
+        "INSERT",
+        ...(includesMaintain ? (["MAINTAIN"] as const) : []),
+        "REFERENCES",
+        "SELECT",
+        "TRIGGER",
+        "TRUNCATE",
+        "UPDATE",
+      ];
+    }
+    case "MATERIALIZED VIEW": {
+      // Materialized views support the same table-like privileges as tables/views
+      // Per PostgreSQL docs, materialized views are table-like for GRANT/REVOKE purposes
+      const includesMaintain = (version ?? 170000) >= 170000;
+      return [
+        "DELETE",
+        "INSERT",
+        ...(includesMaintain ? (["MAINTAIN"] as const) : []),
+        "REFERENCES",
+        "SELECT",
+        "TRIGGER",
+        "TRUNCATE",
+        "UPDATE",
+      ];
+    }
+    case "SEQUENCE":
+      return ["SELECT", "UPDATE", "USAGE"].sort();
+    case "SCHEMA":
+      return ["CREATE", "USAGE"].sort();
+    case "LANGUAGE":
+      return ["USAGE"];
+    case "FUNCTION":
+    case "PROCEDURE":
+    case "ROUTINE":
+      return ["EXECUTE"];
+    case "TYPE":
+    case "DOMAIN":
+      return ["USAGE"];
+    case "FOREIGN DATA WRAPPER":
+      return ["USAGE"];
+    case "SERVER":
+      return ["USAGE"];
+    case "FOREIGN TABLE": {
+      const includesMaintain = (version ?? 170000) >= 170000;
+      return [
+        "DELETE",
+        "INSERT",
+        ...(includesMaintain ? (["MAINTAIN"] as const) : []),
+        "REFERENCES",
+        "SELECT",
+        "TRIGGER",
+        "TRUNCATE",
+        "UPDATE",
+      ];
+    }
+    default:
+      return [];
+  }
+}
+
+/**
+ * Checks if a privilege list represents the full set of privileges for an object kind.
+ * This determines whether we can use "ALL PRIVILEGES" shorthand in SQL.
+ *
+ * @param kind - The PostgreSQL object kind
+ * @param list - Array of privilege names to check
+ * @param version - The PostgreSQL version number
+ * @returns true if the list contains all available privileges for this object kind
+ */
+function isFullObjectPrivilegeSet(
+  kind: string,
+  list: string[],
+  version: number | undefined,
+): boolean {
+  const uniqSorted = [...new Set(list)].sort();
+  const fullSorted = [...objectPrivilegeUniverse(kind, version)].sort();
+  if (uniqSorted.length !== fullSorted.length) return false;
+  for (let i = 0; i < uniqSorted.length; i++) {
+    if (uniqSorted[i] !== fullSorted[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Formats a list of privileges for use in GRANT/REVOKE statements.
+ * If the list represents all privileges, returns "ALL", otherwise returns a comma-separated list.
+ *
+ * @param kind - The PostgreSQL object kind
+ * @param list - Array of privilege names to format
+ * @param version - The PostgreSQL version number
+ * @returns A SQL-formatted privilege list (either "ALL" or "PRIV1, PRIV2, ...")
+ */
+export function formatObjectPrivilegeList(
+  kind: string,
+  list: string[],
+  version: number | undefined,
+): string {
+  const uniqSorted = [...new Set(list)].sort();
+  return isFullObjectPrivilegeSet(kind, uniqSorted, version)
+    ? "ALL"
+    : uniqSorted.join(", ");
+}
+
+/**
+ * Gets the SQL keyword prefix for a given object kind in GRANT/REVOKE statements.
+ *
+ * @param objectKind - The PostgreSQL object kind
+ * @returns The SQL prefix (e.g., "ON SCHEMA", "ON DOMAIN", "ON")
+ */
+export function getObjectKindPrefix(objectKind: string): string {
+  switch (objectKind) {
+    case "FUNCTION":
+      return "ON FUNCTION";
+    case "PROCEDURE":
+      return "ON PROCEDURE";
+    case "ROUTINE":
+      return "ON ROUTINE";
+    case "LANGUAGE":
+      return "ON LANGUAGE";
+    case "SCHEMA":
+      return "ON SCHEMA";
+    case "SEQUENCE":
+      return "ON SEQUENCE";
+    case "DOMAIN":
+      return "ON DOMAIN";
+    case "TYPE":
+      return "ON TYPE";
+    case "FOREIGN TABLE":
+      return "ON TABLE";
+    default:
+      return "ON";
+  }
+}
+
+export function normalizePrivileges(privileges: PrivilegeProps[]) {
+  return privileges
+    .map((privilege) => ({
+      grantee: privilege.grantee,
+      privilege: privilege.privilege,
+      grantable: privilege.grantable,
+      columns: privilege.columns
+        ? [...privilege.columns].sort()
+        : privilege.columns,
+    }))
+    .sort((a, b) => {
+      if (a.grantee !== b.grantee) return a.grantee.localeCompare(b.grantee);
+      if (a.privilege !== b.privilege)
+        return a.privilege.localeCompare(b.privilege);
+      const colA = a.columns?.join(",") ?? "";
+      const colB = b.columns?.join(",") ?? "";
+      return colA.localeCompare(colB);
+    });
+}

package/src/core/objects/collation/changes/collation.alter.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { assertValidSql } from "../../../test-utils/assert-valid-sql.ts";
+import { Collation } from "../collation.model.ts";
+import {
+  AlterCollationChangeOwner,
+  AlterCollationRefreshVersion,
+} from "./collation.alter.ts";
+
+describe.concurrent("collation", () => {
+  describe("alter", () => {
+    test("change owner", async () => {
+      const collation = new Collation({
+        schema: "public",
+        name: "test",
+        provider: "c",
+        is_deterministic: true,
+        encoding: 1,
+        collate: "en_US",
+        locale: "en_US",
+        version: "1.0",
+        ctype: "test",
+        icu_rules: "test",
+        comment: null,
+        owner: "old_owner",
+      });
+
+      const change = new AlterCollationChangeOwner({
+        collation,
+        owner: "new_owner",
+      });
+
+      await assertValidSql(change.serialize());
+
+      expect(change.serialize()).toBe(
+        "ALTER COLLATION public.test OWNER TO new_owner",
+      );
+    });
+
+    test("refresh version", async () => {
+      const collation = new Collation({
+        schema: "public",
+        name: "test",
+        provider: "c",
+        is_deterministic: true,
+        encoding: 1,
+        collate: "en_US",
+        locale: "en_US",
+        ctype: "test",
+        icu_rules: "test",
+        comment: null,
+        owner: "test",
+        version: "1.0",
+      });
+
+      const change = new AlterCollationRefreshVersion({
+        collation,
+      });
+
+      await assertValidSql(change.serialize());
+
+      expect(change.serialize()).toBe(
+        "ALTER COLLATION public.test REFRESH VERSION",
+      );
+    });
+
+    // replace behavior moved into collation.diff.ts as separate Drop + Create
+  });
+});