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

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

@@ -0,0 +1,299 @@
+import z from "zod";
+import type { Change } from "../change.types.ts";
+import type { Role } from "./role/role.model.ts";
+import { stableId } from "./utils.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
+ */
+export 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
+ */
+export 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);
+}
+
+/**
+ * Filter out privileges for superuser roles, as PostgreSQL doesn't store
+ * GRANTs to superusers in relacl (they already have all privileges implicitly).
+ * Reference: https://www.postgresql.org/docs/current/role-attributes.html
+ */
+function filterSuperuserPrivileges<T extends PrivilegeProps>(
+  privileges: T[],
+  mainRoles?: Record<string, Role>,
+): T[] {
+  if (!mainRoles) return privileges;
+  return privileges.filter((priv) => {
+    const role = mainRoles[stableId.role(priv.grantee)];
+    return !role?.is_superuser;
+  });
+}
+
+/**
+ * Generic privilege diffing function that works for any object type
+ */
+export function diffPrivileges<T extends PrivilegeProps>(
+  mainPrivileges: T[],
+  branchPrivileges: T[],
+  owner?: string,
+  mainRoles?: Record<string, Role>,
+): Map<string, PrivilegeDiffResult<T>> {
+  // Filter out superuser privileges from branch - PostgreSQL doesn't store GRANTs
+  // to superusers in relacl because they already have all privileges implicitly
+  const branchPrivilegesFiltered = filterSuperuserPrivileges(
+    branchPrivileges,
+    mainRoles,
+  );
+
+  // Filter out owner privileges if owner is provided
+  const mainFiltered = owner
+    ? filterOwnerPrivileges(mainPrivileges, owner)
+    : mainPrivileges;
+  const branchFiltered = owner
+    ? filterOwnerPrivileges(branchPrivilegesFiltered, owner)
+    : branchPrivilegesFiltered;
+
+  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;
+}

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

@@ -0,0 +1,184 @@
+/**
+ * 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 FOREIGN TABLE";
+    default:
+      return "ON";
+  }
+}
+
+export function normalizePrivileges(privileges: PrivilegeProps[]) {
+  return privileges
+    .map((privilege) => ({
+      grantee: privilege.grantee,
+      privilege: privilege.privilege,
+      grantable: privilege.grantable,
+    }))
+    .sort((a, b) => {
+      if (a.grantee !== b.grantee) return a.grantee.localeCompare(b.grantee);
+      return a.privilege.localeCompare(b.privilege);
+    });
+}

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

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { Collation } from "../collation.model.ts";
+import {
+  AlterCollationChangeOwner,
+  AlterCollationRefreshVersion,
+} from "./collation.alter.ts";
+
+describe.concurrent("collation", () => {
+  describe("alter", () => {
+    test("change owner", () => {
+      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",
+      });
+
+      expect(change.serialize()).toBe(
+        "ALTER COLLATION public.test OWNER TO new_owner",
+      );
+    });
+
+    test("refresh version", () => {
+      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,
+      });
+
+      expect(change.serialize()).toBe(
+        "ALTER COLLATION public.test REFRESH VERSION",
+      );
+    });
+
+    // replace behavior moved into collation.diff.ts as separate Drop + Create
+  });
+});

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

@@ -0,0 +1,79 @@
+import type { Collation } from "../collation.model.ts";
+import { AlterCollationChange } from "./collation.base.ts";
+
+/**
+ * Alter a collation.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-altercollation.html
+ *
+ * Synopsis
+ * ```sql
+ * ALTER COLLATION name REFRESH VERSION
+ * ALTER COLLATION name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ * ALTER COLLATION name RENAME TO new_name
+ * ```
+ */
+
+export type AlterCollation =
+  | AlterCollationChangeOwner
+  | AlterCollationRefreshVersion;
+
+/**
+ * ALTER COLLATION ... OWNER TO ...
+ */
+export class AlterCollationChangeOwner extends AlterCollationChange {
+  public readonly collation: Collation;
+  public readonly owner: string;
+  public readonly scope = "object" as const;
+
+  constructor(props: { collation: Collation; owner: string }) {
+    super();
+    this.collation = props.collation;
+    this.owner = props.owner;
+  }
+
+  get requires() {
+    return [this.collation.stableId];
+  }
+
+  serialize(): string {
+    return [
+      "ALTER COLLATION",
+      `${this.collation.schema}.${this.collation.name}`,
+      "OWNER TO",
+      this.owner,
+    ].join(" ");
+  }
+}
+
+/**
+ * ALTER COLLATION ... REFRESH VERSION
+ */
+export class AlterCollationRefreshVersion extends AlterCollationChange {
+  public readonly collation: Collation;
+  public readonly scope = "object" as const;
+
+  constructor(props: { collation: Collation }) {
+    super();
+    this.collation = props.collation;
+  }
+
+  get requires() {
+    return [this.collation.stableId];
+  }
+
+  serialize(): string {
+    return [
+      "ALTER COLLATION",
+      `${this.collation.schema}.${this.collation.name}`,
+      "REFRESH VERSION",
+    ].join(" ");
+  }
+}
+
+/**
+ * Replace a collation by dropping and recreating it.
+ * This is used when properties that cannot be altered via ALTER COLLATION change.
+ */
+// NOTE: ReplaceCollation has been removed. Non-alterable property changes
+// are modeled as separate DropCollation + CreateCollation changes in collation.diff.ts.

package/src/core/objects/collation/changes/collation.base.ts

@@ -0,0 +1,20 @@
+import { BaseChange } from "../../base.change.ts";
+import type { Collation } from "../collation.model.ts";
+
+abstract class BaseCollationChange extends BaseChange {
+  abstract readonly collation: Collation;
+  abstract readonly scope: "object" | "comment";
+  readonly objectType: "collation" = "collation";
+}
+
+export abstract class CreateCollationChange extends BaseCollationChange {
+  readonly operation = "create" as const;
+}
+
+export abstract class AlterCollationChange extends BaseCollationChange {
+  readonly operation = "alter" as const;
+}
+
+export abstract class DropCollationChange extends BaseCollationChange {
+  readonly operation = "drop" as const;
+}