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

package/src/core/integrations/supabase.ts

@@ -0,0 +1,180 @@
+/**
+ * Supabase integration - filtering and serialization rules for Supabase databases.
+ *
+ * This integration:
+ * - Filters out Supabase system schemas and roles
+ * - Includes user schemas and extensions
+ * - Skips authorization for schema creates owned by Supabase system roles
+ */
+
+import type { IntegrationDSL } from "./integration-dsl.ts";
+
+// Supabase system schemas that should be excluded
+const SUPABASE_SYSTEM_SCHEMAS = [
+  "_analytics",
+  "_realtime",
+  "_supavisor",
+  "auth",
+  "cron",
+  "etl",
+  "extensions",
+  "graphql",
+  "graphql_public",
+  "information_schema",
+  "net",
+  "pgbouncer",
+  "pgmq",
+  "pgmq_public",
+  "pgsodium",
+  "pgsodium_masks",
+  "pgtle",
+  "realtime",
+  "storage",
+  "supabase_functions",
+  "supabase_migrations",
+  "vault",
+] as const;
+
+// Supabase system roles that should be excluded
+const SUPABASE_SYSTEM_ROLES = [
+  "anon",
+  "authenticated",
+  "authenticator",
+  "cli_login_postgres",
+  "dashboard_user",
+  "pgbouncer",
+  "pgsodium_keyholder",
+  "pgsodium_keyiduser",
+  "pgsodium_keymaker",
+  "pgtle_admin",
+  "service_role",
+  "supabase_admin",
+  "supabase_auth_admin",
+  "supabase_etl_admin",
+  "supabase_functions_admin",
+  "supabase_read_only_user",
+  "supabase_realtime_admin",
+  "supabase_replication_admin",
+  "supabase_storage_admin",
+  "supabase_superuser",
+] as const;
+
+/**
+ * To generate the emptyCatalog snapshot, run catalog-export against a fresh
+ * supabase/postgres container:
+ *
+ *   pgdelta catalog-export --target postgres://postgres:postgres@localhost:54322/postgres --output supabase-baseline.json
+ *
+ * Then import and assign the JSON content to the emptyCatalog field below.
+ */
+export const supabase: IntegrationDSL = {
+  // TODO: emptyCatalog: undefined -- populate by running catalog-export on a clean Supabase container
+  filter: {
+    or: [
+      // Include user schema CREATE operations (only schemas not in system list)
+      {
+        and: [
+          {
+            objectType: "schema",
+            operation: "create",
+            scope: "object",
+          },
+          {
+            not: {
+              // Schema objects have name, not schema — use schema/name
+              "schema/name": [...SUPABASE_SYSTEM_SCHEMAS],
+            },
+          },
+        ],
+      },
+      // Include extension CREATEs
+      {
+        objectType: "extension",
+        operation: "create",
+        scope: "object",
+      },
+      // Include extension DROPs used to disable some extensions (eg: pg-net)
+      {
+        objectType: "extension",
+        operation: "drop",
+        scope: "object",
+      },
+      // Exclude system objects
+      {
+        not: {
+          or: [
+            // Objects in system schemas (*/schema matches table/schema, view/schema, etc.)
+            {
+              "*/schema": [...SUPABASE_SYSTEM_SCHEMAS],
+            },
+            // Schema objects whose own name is a system schema
+            {
+              "schema/name": [...SUPABASE_SYSTEM_SCHEMAS],
+            },
+            // Objects owned by system roles (*/owner matches table/owner, schema/owner, etc.)
+            {
+              "*/owner": [...SUPABASE_SYSTEM_ROLES],
+            },
+            // Role objects whose own name is a system role
+            {
+              "role/name": [...SUPABASE_SYSTEM_ROLES],
+            },
+            // Membership changes for system roles
+            {
+              and: [
+                {
+                  objectType: "role",
+                  scope: "membership",
+                },
+                {
+                  member: [...SUPABASE_SYSTEM_ROLES],
+                },
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+  serialize: [
+    {
+      when: {
+        objectType: "schema",
+        operation: "create",
+        scope: "object",
+        "schema/owner": [...SUPABASE_SYSTEM_ROLES],
+      },
+      options: {
+        skipAuthorization: true,
+      },
+    },
+    // Extensions whose install script creates its own target schema cannot
+    // tolerate `CREATE EXTENSION … WITH SCHEMA <self>` against a fresh
+    // database: Postgres resolves WITH SCHEMA before running the extension's
+    // script, so the schema referenced by the clause does not exist yet.
+    // These extensions also install into schemas listed in
+    // SUPABASE_SYSTEM_SCHEMAS, so pg-delta filters their CREATE SCHEMA out
+    // of the declarative plan — nothing else will pre-create the schema.
+    // Emitting a bare `CREATE EXTENSION <name>` lets the extension's own
+    // install script create the schema it expects.
+    //
+    // Note: other extensions install into SUPABASE_SYSTEM_SCHEMAS too
+    // (`pg_graphql` → `graphql`, `supabase_vault` → `vault`,
+    // `uuid-ossp`/`pgcrypto`/`pg_net`/`pg_stat_statements` → `extensions`),
+    // but those schemas are created by the supabase/postgres image baseline
+    // and survive `DROP EXTENSION … CASCADE`, so `CREATE EXTENSION … WITH
+    // SCHEMA <schema>` finds the schema and succeeds. Only the three below
+    // have self-created schemas that are absent from the baseline.
+    {
+      when: {
+        objectType: "extension",
+        operation: "create",
+        scope: "object",
+        "extension/schema": ["pgmq", "pgsodium", "pgtle"],
+      },
+      options: {
+        skipSchema: true,
+      },
+    },
+  ],
+};

package/src/core/objects/aggregate/aggregate.diff.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, test } from "bun:test";
+import { DefaultPrivilegeState } from "../base.default-privileges.ts";
+import { diffAggregates } from "./aggregate.diff.ts";
+import { Aggregate } from "./aggregate.model.ts";
+import { AlterAggregateChangeOwner } from "./changes/aggregate.alter.ts";
+import {
+  CreateCommentOnAggregate,
+  DropCommentOnAggregate,
+} from "./changes/aggregate.comment.ts";
+import { CreateAggregate } from "./changes/aggregate.create.ts";
+import { DropAggregate } from "./changes/aggregate.drop.ts";
+import {
+  GrantAggregatePrivileges,
+  RevokeAggregatePrivileges,
+  RevokeGrantOptionAggregatePrivileges,
+} from "./changes/aggregate.privilege.ts";
+
+type AggregateProps = ConstructorParameters<typeof Aggregate>[0];
+
+const base: AggregateProps = {
+  schema: "public",
+  name: "agg_sum",
+  identity_arguments: "integer",
+  kind: "a",
+  aggkind: "n",
+  num_direct_args: 0,
+  return_type: "integer",
+  return_type_schema: "pg_catalog",
+  parallel_safety: "u",
+  is_strict: false,
+  transition_function: "pg_catalog.int4pl(integer,integer)",
+  state_data_type: "integer",
+  state_data_type_schema: "pg_catalog",
+  state_data_space: 0,
+  final_function: null,
+  final_function_extra_args: false,
+  final_function_modify: null,
+  combine_function: null,
+  serial_function: null,
+  deserial_function: null,
+  initial_condition: null,
+  moving_transition_function: null,
+  moving_inverse_function: null,
+  moving_state_data_type: null,
+  moving_state_data_type_schema: null,
+  moving_state_data_space: null,
+  moving_final_function: null,
+  moving_final_function_extra_args: false,
+  moving_final_function_modify: null,
+  moving_initial_condition: null,
+  sort_operator: null,
+  argument_count: 1,
+  argument_default_count: 0,
+  argument_names: null,
+  argument_types: ["integer"],
+  all_argument_types: null,
+  argument_modes: null,
+  argument_defaults: null,
+  owner: "owner1",
+  comment: null,
+  privileges: [],
+};
+
+const makeAggregate = (override: Partial<AggregateProps> = {}) =>
+  new Aggregate({
+    ...base,
+    ...override,
+    privileges: override.privileges ?? [...base.privileges],
+  });
+
+const testContext = {
+  version: 170000,
+  currentUser: "postgres",
+  defaultPrivilegeState: new DefaultPrivilegeState({}),
+  mainRoles: {},
+};
+
+describe.concurrent("aggregate.diff", () => {
+  test("create and drop emit expected changes", () => {
+    const aggregate = makeAggregate({ comment: "sum comment" });
+    const created = diffAggregates(
+      testContext,
+      {},
+      { [aggregate.stableId]: aggregate },
+    );
+
+    expect(created[0]).toBeInstanceOf(CreateAggregate);
+    expect(
+      created.some((change) => change instanceof CreateCommentOnAggregate),
+    ).toBe(true);
+
+    const dropped = diffAggregates(
+      testContext,
+      { [aggregate.stableId]: aggregate },
+      {},
+    );
+
+    expect(dropped[0]).toBeInstanceOf(DropAggregate);
+  });
+
+  test("alter owner produces change owner statement", () => {
+    const main = makeAggregate();
+    const branch = makeAggregate({ owner: "owner2" });
+    const changes = diffAggregates(
+      testContext,
+      { [main.stableId]: main },
+      { [branch.stableId]: branch },
+    );
+
+    expect(changes).toHaveLength(1);
+    expect(changes[0]).toBeInstanceOf(AlterAggregateChangeOwner);
+  });
+
+  test("comment changes emit create/drop comment statements", () => {
+    const main = makeAggregate();
+    const withComment = makeAggregate({ comment: "sum comment" });
+    const addComment = diffAggregates(
+      testContext,
+      { [main.stableId]: main },
+      { [withComment.stableId]: withComment },
+    );
+
+    expect(addComment[0]).toBeInstanceOf(CreateCommentOnAggregate);
+
+    const dropComment = diffAggregates(
+      testContext,
+      { [withComment.stableId]: withComment },
+      { [main.stableId]: main },
+    );
+
+    expect(dropComment[0]).toBeInstanceOf(DropCommentOnAggregate);
+  });
+
+  test("non-alterable changes force create or replace", () => {
+    const main = makeAggregate();
+    const branch = makeAggregate({ return_type: "text" });
+    const changes = diffAggregates(
+      testContext,
+      { [main.stableId]: main },
+      { [branch.stableId]: branch },
+    );
+
+    expect(changes).toHaveLength(1);
+    expect(changes[0]).toBeInstanceOf(CreateAggregate);
+    expect((changes[0] as CreateAggregate).orReplace).toBe(true);
+  });
+
+  test("privilege diffs emit grant, revoke, and revoke grant option statements", () => {
+    const main = makeAggregate({
+      privileges: [
+        { grantee: "role_exec", privilege: "EXECUTE", grantable: false },
+        { grantee: "role_with_option", privilege: "EXECUTE", grantable: true },
+        { grantee: "role_removed", privilege: "EXECUTE", grantable: false },
+      ],
+    });
+    const branch = makeAggregate({
+      privileges: [
+        { grantee: "role_exec", privilege: "EXECUTE", grantable: true },
+        { grantee: "role_with_option", privilege: "EXECUTE", grantable: false },
+        { grantee: "role_new", privilege: "EXECUTE", grantable: false },
+      ],
+    });
+
+    const changes = diffAggregates(
+      testContext,
+      { [main.stableId]: main },
+      { [branch.stableId]: branch },
+    );
+
+    expect(
+      changes.some((change) => change instanceof GrantAggregatePrivileges),
+    ).toBe(true);
+    expect(
+      changes.some((change) => change instanceof RevokeAggregatePrivileges),
+    ).toBe(true);
+    expect(
+      changes.some(
+        (change) => change instanceof RevokeGrantOptionAggregatePrivileges,
+      ),
+    ).toBe(true);
+
+    const grantBase = changes.find(
+      (change) =>
+        change instanceof GrantAggregatePrivileges &&
+        change.grantee === "role_with_option",
+    ) as GrantAggregatePrivileges | undefined;
+    expect(grantBase?.privileges).toEqual([
+      {
+        grantee: "role_with_option",
+        privilege: "EXECUTE",
+        grantable: false,
+      } as never,
+    ]);
+
+    const revokeGrantOption = changes.find(
+      (change) =>
+        change instanceof RevokeGrantOptionAggregatePrivileges &&
+        change.grantee === "role_with_option",
+    ) as RevokeGrantOptionAggregatePrivileges | undefined;
+    expect(revokeGrantOption?.privilegeNames).toEqual(["EXECUTE"]);
+
+    const revokePrivilege = changes.find(
+      (change) =>
+        change instanceof RevokeAggregatePrivileges &&
+        change.grantee === "role_removed",
+    ) as RevokeAggregatePrivileges | undefined;
+    expect(revokePrivilege?.privileges).toEqual([
+      {
+        grantee: "role_removed",
+        privilege: "EXECUTE",
+        grantable: false,
+      } as never,
+    ]);
+  });
+});

package/src/core/objects/aggregate/aggregate.diff.ts

@@ -0,0 +1,222 @@
+import { diffObjects } from "../base.diff.ts";
+import {
+  diffPrivileges,
+  emitObjectPrivilegeChanges,
+  filterPublicBuiltInDefaults,
+} from "../base.privilege-diff.ts";
+import type { ObjectDiffContext } from "../diff-context.ts";
+import { deepEqual, hasNonAlterableChanges } from "../utils.ts";
+import type { Aggregate } from "./aggregate.model.ts";
+import { AlterAggregateChangeOwner } from "./changes/aggregate.alter.ts";
+import {
+  CreateCommentOnAggregate,
+  DropCommentOnAggregate,
+} from "./changes/aggregate.comment.ts";
+import { CreateAggregate } from "./changes/aggregate.create.ts";
+import { DropAggregate } from "./changes/aggregate.drop.ts";
+import {
+  GrantAggregatePrivileges,
+  RevokeAggregatePrivileges,
+  RevokeGrantOptionAggregatePrivileges,
+} from "./changes/aggregate.privilege.ts";
+import type { AggregateChange } from "./changes/aggregate.types.ts";
+
+export function diffAggregates(
+  ctx: Pick<
+    ObjectDiffContext,
+    "version" | "currentUser" | "defaultPrivilegeState"
+  >,
+  main: Record<string, Aggregate>,
+  branch: Record<string, Aggregate>,
+): AggregateChange[] {
+  const { created, dropped, altered } = diffObjects(main, branch);
+
+  const changes: AggregateChange[] = [];
+
+  for (const aggregateId of created) {
+    const aggregate = branch[aggregateId];
+    changes.push(new CreateAggregate({ aggregate }));
+
+    // OWNER: If the aggregate should be owned by someone other than the current user,
+    // emit ALTER AGGREGATE ... OWNER TO after creation
+    if (aggregate.owner !== ctx.currentUser) {
+      changes.push(
+        new AlterAggregateChangeOwner({
+          aggregate,
+          owner: aggregate.owner,
+        }),
+      );
+    }
+
+    if (aggregate.comment !== null) {
+      changes.push(new CreateCommentOnAggregate({ aggregate }));
+    }
+
+    // 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,
+      "aggregate",
+      aggregate.schema ?? "",
+    );
+    const creatorFilteredDefaults =
+      aggregate.owner !== ctx.currentUser
+        ? effectiveDefaults.filter((p) => p.grantee !== ctx.currentUser)
+        : effectiveDefaults;
+    // Filter out PUBLIC's built-in default EXECUTE privilege (PostgreSQL grants it automatically)
+    // Reference: https://www.postgresql.org/docs/17/ddl-priv.html Table 5.2
+    // This prevents generating unnecessary "GRANT EXECUTE TO PUBLIC" statements
+    const desiredPrivileges = filterPublicBuiltInDefaults(
+      "aggregate",
+      aggregate.privileges,
+    );
+    // Filter out owner privileges - owner always has ALL privileges implicitly
+    // and shouldn't be compared. Use the aggregate owner as the reference.
+    const privilegeResults = diffPrivileges(
+      filterPublicBuiltInDefaults("aggregate", creatorFilteredDefaults),
+      desiredPrivileges,
+      aggregate.owner,
+    );
+
+    changes.push(
+      ...(emitObjectPrivilegeChanges(
+        privilegeResults,
+        aggregate,
+        aggregate,
+        "aggregate",
+        {
+          Grant: GrantAggregatePrivileges,
+          Revoke: RevokeAggregatePrivileges,
+          RevokeGrantOption: RevokeGrantOptionAggregatePrivileges,
+        },
+        ctx.version,
+      ) as AggregateChange[]),
+    );
+  }
+
+  for (const aggregateId of dropped) {
+    changes.push(new DropAggregate({ aggregate: main[aggregateId] }));
+  }
+
+  for (const aggregateId of altered) {
+    const mainAggregate = main[aggregateId];
+    const branchAggregate = branch[aggregateId];
+
+    const NON_ALTERABLE_FIELDS: Array<keyof Aggregate> = [
+      "kind",
+      "aggkind",
+      "num_direct_args",
+      "return_type",
+      "return_type_schema",
+      "parallel_safety",
+      "is_strict",
+      "transition_function",
+      "state_data_type",
+      "state_data_type_schema",
+      "state_data_space",
+      "final_function",
+      "final_function_extra_args",
+      "final_function_modify",
+      "combine_function",
+      "serial_function",
+      "deserial_function",
+      "initial_condition",
+      "moving_transition_function",
+      "moving_inverse_function",
+      "moving_state_data_type",
+      "moving_state_data_type_schema",
+      "moving_state_data_space",
+      "moving_final_function",
+      "moving_final_function_extra_args",
+      "moving_final_function_modify",
+      "moving_initial_condition",
+      "sort_operator",
+      "argument_count",
+      "argument_default_count",
+      "argument_names",
+      "argument_types",
+      "all_argument_types",
+      "argument_modes",
+      "argument_defaults",
+      "identityArguments",
+    ];
+
+    const nonAlterableChanged = hasNonAlterableChanges(
+      mainAggregate,
+      branchAggregate,
+      NON_ALTERABLE_FIELDS,
+      {
+        argument_names: deepEqual,
+        argument_types: deepEqual,
+        all_argument_types: deepEqual,
+        argument_modes: deepEqual,
+      },
+    );
+
+    if (nonAlterableChanged) {
+      changes.push(
+        new CreateAggregate({ aggregate: branchAggregate, orReplace: true }),
+      );
+      continue;
+    }
+
+    if (mainAggregate.owner !== branchAggregate.owner) {
+      changes.push(
+        new AlterAggregateChangeOwner({
+          aggregate: mainAggregate,
+          owner: branchAggregate.owner,
+        }),
+      );
+    }
+
+    if (mainAggregate.comment !== branchAggregate.comment) {
+      if (branchAggregate.comment === null) {
+        changes.push(new DropCommentOnAggregate({ aggregate: mainAggregate }));
+      } else {
+        changes.push(
+          new CreateCommentOnAggregate({ aggregate: branchAggregate }),
+        );
+      }
+    }
+
+    // PRIVILEGES
+    // Filter out PUBLIC's built-in default EXECUTE privilege from main catalog
+    // (PostgreSQL grants it automatically, so we shouldn't compare it)
+    const mainPrivilegesFiltered = filterPublicBuiltInDefaults(
+      "aggregate",
+      mainAggregate.privileges,
+    );
+    // Filter out PUBLIC's built-in default EXECUTE privilege from branch catalog
+    const branchPrivilegesFiltered = filterPublicBuiltInDefaults(
+      "aggregate",
+      branchAggregate.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,
+      branchAggregate.owner,
+    );
+
+    changes.push(
+      ...(emitObjectPrivilegeChanges(
+        privilegeResults,
+        branchAggregate,
+        mainAggregate,
+        "aggregate",
+        {
+          Grant: GrantAggregatePrivileges,
+          Revoke: RevokeAggregatePrivileges,
+          RevokeGrantOption: RevokeGrantOptionAggregatePrivileges,
+        },
+        ctx.version,
+      ) as AggregateChange[]),
+    );
+  }
+
+  return changes;
+}