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

package/src/core/objects/type/enum/enum.diff.ts

@@ -0,0 +1,308 @@
+import { diffObjects } from "../../base.diff.ts";
+import {
+  diffPrivileges,
+  emitObjectPrivilegeChanges,
+  filterPublicBuiltInDefaults,
+} from "../../base.privilege-diff.ts";
+import type { ObjectDiffContext } from "../../diff-context.ts";
+import {
+  AlterEnumAddValue,
+  AlterEnumChangeOwner,
+} from "./changes/enum.alter.ts";
+import {
+  CreateCommentOnEnum,
+  DropCommentOnEnum,
+} from "./changes/enum.comment.ts";
+import { CreateEnum } from "./changes/enum.create.ts";
+import { DropEnum } from "./changes/enum.drop.ts";
+import {
+  GrantEnumPrivileges,
+  RevokeEnumPrivileges,
+  RevokeGrantOptionEnumPrivileges,
+} from "./changes/enum.privilege.ts";
+import type { EnumChange } from "./changes/enum.types.ts";
+import type { Enum } from "./enum.model.ts";
+
+/**
+ * Diff two sets of enums from main and branch catalogs.
+ *
+ * @param ctx - Context containing version, currentUser, and defaultPrivilegeState
+ * @param main - The enums in the main catalog.
+ * @param branch - The enums in the branch catalog.
+ * @returns A list of changes to apply to main to make it match branch.
+ */
+export function diffEnums(
+  ctx: Pick<
+    ObjectDiffContext,
+    "version" | "currentUser" | "defaultPrivilegeState"
+  >,
+  main: Record<string, Enum>,
+  branch: Record<string, Enum>,
+): EnumChange[] {
+  const { created, dropped, altered } = diffObjects(main, branch);
+
+  const changes: EnumChange[] = [];
+
+  for (const enumId of created) {
+    const createdEnum = branch[enumId];
+    changes.push(new CreateEnum({ enum: createdEnum }));
+
+    // OWNER: If the enum should be owned by someone other than the current user,
+    // emit ALTER TYPE ... OWNER TO after creation
+    if (createdEnum.owner !== ctx.currentUser) {
+      changes.push(
+        new AlterEnumChangeOwner({
+          enum: createdEnum,
+          owner: createdEnum.owner,
+        }),
+      );
+    }
+
+    if (createdEnum.comment !== null) {
+      changes.push(new CreateCommentOnEnum({ enum: createdEnum }));
+    }
+
+    // PRIVILEGES: For created objects, compare against default privileges state
+    // The migration script will run ALTER DEFAULT PRIVILEGES before CREATE (via constraint spec),
+    // so objects are created with the default privileges state in effect.
+    // We compare default privileges against desired privileges to generate REVOKE/GRANT statements
+    // needed to reach the final desired state.
+    const effectiveDefaults = ctx.defaultPrivilegeState.getEffectiveDefaults(
+      ctx.currentUser,
+      "enum",
+      createdEnum.schema ?? "",
+    );
+    const creatorFilteredDefaults =
+      createdEnum.owner !== ctx.currentUser
+        ? effectiveDefaults.filter((p) => p.grantee !== ctx.currentUser)
+        : effectiveDefaults;
+    // Filter out PUBLIC's built-in default USAGE privilege (PostgreSQL grants it automatically)
+    // Reference: https://www.postgresql.org/docs/17/ddl-priv.html Table 5.2
+    // This prevents generating unnecessary "GRANT USAGE TO PUBLIC" statements
+    const desiredPrivileges = filterPublicBuiltInDefaults(
+      "enum",
+      createdEnum.privileges,
+    );
+    // Filter out owner privileges - owner always has ALL privileges implicitly
+    // and shouldn't be compared. Use the enum owner as the reference.
+    const privilegeResults = diffPrivileges(
+      filterPublicBuiltInDefaults("enum", creatorFilteredDefaults),
+      desiredPrivileges,
+      createdEnum.owner,
+    );
+
+    changes.push(
+      ...(emitObjectPrivilegeChanges(
+        privilegeResults,
+        createdEnum,
+        createdEnum,
+        "enum",
+        {
+          Grant: GrantEnumPrivileges,
+          Revoke: RevokeEnumPrivileges,
+          RevokeGrantOption: RevokeGrantOptionEnumPrivileges,
+        },
+        ctx.version,
+      ) as EnumChange[]),
+    );
+  }
+
+  for (const enumId of dropped) {
+    changes.push(new DropEnum({ enum: main[enumId] }));
+  }
+
+  for (const enumId of altered) {
+    const mainEnum = main[enumId];
+    const branchEnum = branch[enumId];
+
+    // If labels were removed (branch is missing labels present in main),
+    // recreate the enum to avoid relying on unsupported DROP VALUE operations.
+    const removedLabels = mainEnum.labels
+      .map((l) => l.label)
+      .filter((label) => !branchEnum.labels.some((b) => b.label === label));
+    if (removedLabels.length > 0) {
+      changes.push(new DropEnum({ enum: mainEnum }));
+      changes.push(new CreateEnum({ enum: branchEnum }));
+
+      if (branchEnum.owner !== ctx.currentUser) {
+        changes.push(
+          new AlterEnumChangeOwner({
+            enum: branchEnum,
+            owner: branchEnum.owner,
+          }),
+        );
+      }
+
+      if (branchEnum.comment !== null) {
+        changes.push(new CreateCommentOnEnum({ enum: branchEnum }));
+      }
+
+      const effectiveDefaults = ctx.defaultPrivilegeState.getEffectiveDefaults(
+        ctx.currentUser,
+        "enum",
+        branchEnum.schema ?? "",
+      );
+      const creatorFilteredDefaults =
+        branchEnum.owner !== ctx.currentUser
+          ? effectiveDefaults.filter((p) => p.grantee !== ctx.currentUser)
+          : effectiveDefaults;
+      const desiredPrivileges = filterPublicBuiltInDefaults(
+        "enum",
+        branchEnum.privileges,
+      );
+      const privilegeResults = diffPrivileges(
+        filterPublicBuiltInDefaults("enum", creatorFilteredDefaults),
+        desiredPrivileges,
+        branchEnum.owner,
+      );
+
+      changes.push(
+        ...(emitObjectPrivilegeChanges(
+          privilegeResults,
+          branchEnum,
+          branchEnum,
+          "enum",
+          {
+            Grant: GrantEnumPrivileges,
+            Revoke: RevokeEnumPrivileges,
+            RevokeGrantOption: RevokeGrantOptionEnumPrivileges,
+          },
+          ctx.version,
+        ) as EnumChange[]),
+      );
+
+      continue;
+    }
+
+    // OWNER
+    if (mainEnum.owner !== branchEnum.owner) {
+      changes.push(
+        new AlterEnumChangeOwner({ enum: mainEnum, owner: branchEnum.owner }),
+      );
+    }
+
+    // LABELS (enum values)
+    if (JSON.stringify(mainEnum.labels) !== JSON.stringify(branchEnum.labels)) {
+      const labelChanges = diffEnumLabels(mainEnum, branchEnum);
+      changes.push(...labelChanges);
+    }
+
+    // COMMENT
+    if (mainEnum.comment !== branchEnum.comment) {
+      if (branchEnum.comment === null) {
+        changes.push(new DropCommentOnEnum({ enum: mainEnum }));
+      } else {
+        changes.push(new CreateCommentOnEnum({ enum: branchEnum }));
+      }
+    }
+
+    // PRIVILEGES
+    // Filter out PUBLIC's built-in default USAGE privilege from main catalog
+    // (PostgreSQL grants it automatically, so we shouldn't compare it)
+    const mainPrivilegesFiltered = filterPublicBuiltInDefaults(
+      "enum",
+      mainEnum.privileges,
+    );
+    // Filter out PUBLIC's built-in default USAGE privilege from branch catalog
+    const branchPrivilegesFiltered = filterPublicBuiltInDefaults(
+      "enum",
+      branchEnum.privileges,
+    );
+    // Filter out owner privileges - owner always has ALL privileges implicitly
+    // and shouldn't be compared. Use branch owner as the reference.
+    const privilegeResults = diffPrivileges(
+      mainPrivilegesFiltered,
+      branchPrivilegesFiltered,
+      branchEnum.owner,
+    );
+
+    changes.push(
+      ...(emitObjectPrivilegeChanges(
+        privilegeResults,
+        branchEnum,
+        mainEnum,
+        "enum",
+        {
+          Grant: GrantEnumPrivileges,
+          Revoke: RevokeEnumPrivileges,
+          RevokeGrantOption: RevokeGrantOptionEnumPrivileges,
+        },
+        ctx.version,
+      ) as EnumChange[]),
+    );
+
+    // Note: Enum renaming would also use ALTER TYPE ... RENAME TO ...
+    // But since our Enum model uses 'name' as the identity field,
+    // a name change would be handled as drop + create by diffObjects()
+  }
+
+  return changes;
+}
+
+/**
+ * Diff enum labels to determine what ALTER TYPE statements are needed.
+ * This implementation properly handles enum value positioning using sort_order.
+ * Note: We cannot reliably detect renames, so we only handle additions.
+ */
+function diffEnumLabels(mainEnum: Enum, branchEnum: Enum): EnumChange[] {
+  const changes: EnumChange[] = [];
+
+  // Create maps for efficient lookup
+  const mainLabelMap = new Map(
+    mainEnum.labels.map((label) => [label.label, label.sort_order]),
+  );
+  const branchLabelMap = new Map(
+    branchEnum.labels.map((label) => [label.label, label.sort_order]),
+  );
+
+  // Find added values (values in branch but not in main)
+  const addedValues = Array.from(branchLabelMap.keys()).filter(
+    (label) => !mainLabelMap.has(label),
+  );
+
+  // Maintain a working list of labels (by name) to calculate correct BEFORE/AFTER
+  // anchors as we simulate applying the additions in order.
+  const branchOrdered = [...branchEnum.labels].sort(
+    (a, b) => a.sort_order - b.sort_order,
+  );
+  const workingLabels = [...mainEnum.labels].map((l) => l.label);
+
+  for (const newValue of addedValues) {
+    const branchIdx = branchOrdered.findIndex((l) => l.label === newValue);
+    if (branchIdx === -1) continue;
+
+    const prevBranch = branchOrdered[branchIdx - 1]?.label;
+    const nextBranch = branchOrdered[branchIdx + 1]?.label;
+
+    let position: { before?: string; after?: string } | undefined;
+
+    // Prefer AFTER when prevBranch exists in workingLabels (more natural for sequential additions)
+    // Use BEFORE only when we need to insert before the first value or when prevBranch doesn't exist
+    if (prevBranch && workingLabels.includes(prevBranch)) {
+      position = { after: prevBranch };
+      // Insert after the previous label in our working list
+      const prevIdx = workingLabels.indexOf(prevBranch);
+      workingLabels.splice(prevIdx + 1, 0, newValue);
+    } else if (nextBranch && workingLabels.includes(nextBranch)) {
+      // Insert before nextBranch when prevBranch doesn't exist (e.g., adding at beginning)
+      position = { before: nextBranch };
+      const nextIdx = workingLabels.indexOf(nextBranch);
+      workingLabels.splice(nextIdx, 0, newValue);
+    } else if (nextBranch) {
+      // nextBranch exists but not in workingLabels yet (shouldn't happen in normal flow)
+      position = { before: nextBranch };
+      workingLabels.push(newValue);
+    } else {
+      // Fallback: append to the end
+      position = { after: workingLabels[workingLabels.length - 1] };
+      workingLabels.push(newValue);
+    }
+
+    changes.push(new AlterEnumAddValue({ enum: mainEnum, newValue, position }));
+  }
+
+  // Complex changes (removals, resorting) are currently not auto-handled.
+  // We intentionally avoid emitting drop+create to prevent data loss.
+
+  return changes;
+}

package/src/core/objects/type/enum/enum.model.ts

@@ -0,0 +1,194 @@
+import { sql } from "@ts-safeql/sql-tag";
+import type { Pool } from "pg";
+import z from "zod";
+import { BasePgModel } from "../../base.model.ts";
+import {
+  type PrivilegeProps,
+  privilegePropsSchema,
+} from "../../base.privilege-diff.ts";
+
+const enumLabelSchema = z.object({
+  sort_order: z.number(),
+  label: z.string(),
+});
+
+/**
+ * All properties exposed by CREATE TYPE AS ENUM statement are included in diff output.
+ * https://www.postgresql.org/docs/current/sql-createtype.html
+ *
+ * ALTER TYPE statement can be generated for changes to the following properties:
+ *  - name, owner, schema, add or rename value
+ * https://www.postgresql.org/docs/current/sql-altertype.html
+ *
+ * Sort order of values may be negative or fractional.
+ * https://www.postgresql.org/docs/current/catalog-pg-enum.html
+ *
+ * Type ACL will be supported separately.
+ * https://www.postgresql.org/docs/current/ddl-priv.html
+ */
+const enumPropsSchema = z.object({
+  schema: z.string(),
+  name: z.string(),
+  owner: z.string(),
+  labels: z.array(enumLabelSchema),
+  comment: z.string().nullable(),
+  privileges: z.array(privilegePropsSchema),
+});
+
+type EnumPrivilegeProps = PrivilegeProps;
+export type EnumProps = z.infer<typeof enumPropsSchema>;
+
+export class Enum extends BasePgModel {
+  public readonly schema: EnumProps["schema"];
+  public readonly name: EnumProps["name"];
+  public readonly owner: EnumProps["owner"];
+  public readonly labels: EnumProps["labels"];
+  public readonly comment: EnumProps["comment"];
+  public readonly privileges: EnumPrivilegeProps[];
+
+  constructor(props: EnumProps) {
+    super();
+
+    // Identity fields
+    this.schema = props.schema;
+    this.name = props.name;
+
+    // Data fields
+    this.owner = props.owner;
+    this.labels = props.labels;
+    this.comment = props.comment;
+    this.privileges = props.privileges;
+  }
+
+  get stableId(): `type:${string}` {
+    return `type:${this.schema}.${this.name}`;
+  }
+
+  get identityFields() {
+    return {
+      schema: this.schema,
+      name: this.name,
+    };
+  }
+
+  get dataFields() {
+    const orderedLabels = [...this.labels]
+      .map((label) => ({ ...label }))
+      .sort(
+        (a, b) => a.sort_order - b.sort_order || a.label.localeCompare(b.label),
+      );
+    // Normalize sort_order to a deterministic 1..N sequence to avoid float gaps
+    // that occur when adding multiple enum values with AFTER clauses.
+    const labels = orderedLabels.map((label, idx) => ({
+      sort_order: idx + 1,
+      label: label.label,
+    }));
+
+    const privileges = [...this.privileges]
+      .map((priv) => ({
+        ...priv,
+        columns: priv.columns ? [...priv.columns].sort() : priv.columns,
+      }))
+      .sort((a, b) => {
+        const byGrantee = a.grantee.localeCompare(b.grantee);
+        if (byGrantee !== 0) return byGrantee;
+        const byPriv = a.privilege.localeCompare(b.privilege);
+        if (byPriv !== 0) return byPriv;
+        if (a.grantable !== b.grantable) return a.grantable ? 1 : -1;
+        const colsA = (a.columns ?? []).join(",");
+        const colsB = (b.columns ?? []).join(",");
+        return colsA.localeCompare(colsB);
+      });
+
+    return {
+      owner: this.owner,
+      labels,
+      comment: this.comment,
+      privileges,
+    };
+  }
+}
+
+export async function extractEnums(pool: Pool): Promise<Enum[]> {
+  const { rows: enumRows } = await pool.query<{
+    schema: string;
+    name: string;
+    sort_order: number;
+    label: string;
+    owner: string;
+    comment: string | null;
+    privileges: { grantee: string; privilege: string; grantable: boolean }[];
+  }>(sql`
+with extension_oids as (
+  select
+    objid
+  from
+    pg_depend d
+  where
+    d.refclassid = 'pg_extension'::regclass
+    and d.classid = 'pg_type'::regclass
+)
+select
+  t.typnamespace::regnamespace::text as schema,
+  quote_ident(t.typname) as name,
+  e.enumsortorder as sort_order,
+  e.enumlabel as label,
+  t.typowner::regrole::text as owner,
+  obj_description(t.oid, 'pg_type') as comment,
+  coalesce(
+    (
+      select json_agg(
+        json_build_object(
+          'grantee', case when x.grantee = 0 then 'PUBLIC' else x.grantee::regrole::text end,
+          'privilege', x.privilege_type,
+          'grantable', x.is_grantable
+        )
+        order by x.grantee, x.privilege_type
+      )
+      from lateral aclexplode(COALESCE(t.typacl, acldefault('T', t.typowner))) as x(grantor, grantee, privilege_type, is_grantable)
+    ), '[]'
+  ) as privileges
+from
+  pg_catalog.pg_enum e
+  inner join pg_catalog.pg_type t on t.oid = e.enumtypid
+  left outer join extension_oids ext on t.oid = ext.objid
+  where not t.typnamespace::regnamespace::text like any(array['pg\\_%', 'information\\_schema'])
+  and ext.objid is null
+order by
+  1, 2, 3
+  `);
+  const grouped: Record<
+    string,
+    {
+      schema: string;
+      name: string;
+      owner: string;
+      labels: { sort_order: number; label: string }[];
+      comment: string | null;
+      privileges: {
+        grantee: string;
+        privilege: string;
+        grantable: boolean;
+      }[];
+    }
+  > = {};
+  for (const e of enumRows) {
+    const key = `${e.schema}.${e.name}`;
+    if (!grouped[key]) {
+      grouped[key] = {
+        schema: e.schema,
+        name: e.name,
+        owner: e.owner,
+        labels: [],
+        comment: e.comment,
+        privileges: e.privileges,
+      };
+    }
+    grouped[key].labels.push({ sort_order: e.sort_order, label: e.label });
+  }
+  // Validate and parse each enum using the Zod schema
+  const validatedEnums = Object.values(grouped).map((e) =>
+    enumPropsSchema.parse(e),
+  );
+  return validatedEnums.map((e: EnumProps) => new Enum(e));
+}

package/src/core/objects/type/range/changes/range.alter.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { assertValidSql } from "../../../../test-utils/assert-valid-sql.ts";
+import { Range, type RangeProps } from "../range.model.ts";
+import { AlterRangeChangeOwner } from "./range.alter.ts";
+
+describe.concurrent("range", () => {
+  test("change owner", async () => {
+    const base: RangeProps = {
+      schema: "public",
+      name: "ts_custom",
+      owner: "o1",
+      subtype_schema: "pg_catalog",
+      subtype_str: "int4",
+      collation: null,
+      canonical_function_schema: null,
+      canonical_function_name: null,
+      subtype_diff_schema: null,
+      subtype_diff_name: null,
+      subtype_opclass_schema: null,
+      subtype_opclass_name: null,
+      comment: null,
+      privileges: [],
+    };
+    const main = new Range(base);
+    const change = new AlterRangeChangeOwner({ range: main, owner: "o2" });
+    await assertValidSql(change.serialize());
+    expect(change.serialize()).toBe("ALTER TYPE public.ts_custom OWNER TO o2");
+  });
+});

package/src/core/objects/type/range/changes/range.alter.ts

@@ -0,0 +1,52 @@
+import type { SerializeOptions } from "../../../../integrations/serialize/serialize.types.ts";
+import type { Range } from "../range.model.ts";
+import { AlterRangeChange } from "./range.base.ts";
+
+/**
+ * Alter a range type.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-altertype.html
+ *
+ * Synopsis
+ * ```sql
+ * ALTER TYPE name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ * ALTER TYPE name RENAME TO new_name
+ * ALTER TYPE name SET SCHEMA new_schema
+ * ```
+ */
+
+export type AlterRange = AlterRangeChangeOwner;
+
+/**
+ * ALTER TYPE ... OWNER TO ...
+ */
+export class AlterRangeChangeOwner extends AlterRangeChange {
+  public readonly range: Range;
+  public readonly owner: string;
+  public readonly scope = "object" as const;
+
+  constructor(props: { range: Range; owner: string }) {
+    super();
+    this.range = props.range;
+    this.owner = props.owner;
+  }
+
+  get requires() {
+    return [this.range.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return [
+      "ALTER TYPE",
+      `${this.range.schema}.${this.range.name}`,
+      "OWNER TO",
+      this.owner,
+    ].join(" ");
+  }
+}
+
+/**
+ * Replace a range type by dropping and recreating it.
+ * This is used when properties that cannot be altered via ALTER TYPE change.
+ */
+// NOTE: ReplaceRange removed. Non-alterable changes are emitted as Drop + Create in range.diff.ts.

package/src/core/objects/type/range/changes/range.base.ts

@@ -0,0 +1,20 @@
+import { BaseChange } from "../../../base.change.ts";
+import type { Range } from "../range.model.ts";
+
+abstract class BaseRangeChange extends BaseChange {
+  abstract readonly range: Range;
+  abstract readonly scope: "object" | "comment" | "privilege";
+  readonly objectType: "range" = "range";
+}
+
+export abstract class CreateRangeChange extends BaseRangeChange {
+  readonly operation = "create" as const;
+}
+
+export abstract class AlterRangeChange extends BaseRangeChange {
+  readonly operation = "alter" as const;
+}
+
+export abstract class DropRangeChange extends BaseRangeChange {
+  readonly operation = "drop" as const;
+}

package/src/core/objects/type/range/changes/range.comment.ts

@@ -0,0 +1,65 @@
+import type { SerializeOptions } from "../../../../integrations/serialize/serialize.types.ts";
+import { quoteLiteral } from "../../../base.change.ts";
+import { stableId } from "../../../utils.ts";
+import type { Range } from "../range.model.ts";
+import { CreateRangeChange, DropRangeChange } from "./range.base.ts";
+
+/**
+ * Create/drop comments on range types.
+ */
+
+export type CommentRange = CreateCommentOnRange | DropCommentOnRange;
+
+export class CreateCommentOnRange extends CreateRangeChange {
+  public readonly range: Range;
+  public readonly scope = "comment" as const;
+
+  constructor(props: { range: Range }) {
+    super();
+    this.range = props.range;
+  }
+
+  get creates() {
+    return [stableId.comment(this.range.stableId)];
+  }
+
+  get requires() {
+    return [this.range.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return [
+      "COMMENT ON TYPE",
+      `${this.range.schema}.${this.range.name}`,
+      "IS",
+      // biome-ignore lint/style/noNonNullAssertion: range comment is not nullable in this case
+      quoteLiteral(this.range.comment!),
+    ].join(" ");
+  }
+}
+
+export class DropCommentOnRange extends DropRangeChange {
+  public readonly range: Range;
+  public readonly scope = "comment" as const;
+
+  constructor(props: { range: Range }) {
+    super();
+    this.range = props.range;
+  }
+
+  get drops() {
+    return [stableId.comment(this.range.stableId)];
+  }
+
+  get requires() {
+    return [stableId.comment(this.range.stableId), this.range.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return [
+      "COMMENT ON TYPE",
+      `${this.range.schema}.${this.range.name}`,
+      "IS NULL",
+    ].join(" ");
+  }
+}