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

package/src/core/integrations/supabase.ts

@@ -0,0 +1,355 @@
+/**
+ * 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",
+      },
+      // Include user-attached triggers on tables in Supabase-managed schemas.
+      //
+      // Triggers live in the schema of the table they fire on, so a user
+      // trigger on `auth.users` reports `trigger/schema = auth` and is
+      // otherwise indistinguishable from Supabase's own triggers via the
+      // schema-level deny list. Triggers also have no real owner — pg-delta
+      // surfaces the parent table's owner as `trigger/owner`, which for
+      // `auth.users` and `storage.objects` is always a Supabase system role,
+      // so the owner-level deny list catches them too.
+      //
+      // The trigger function, however, is genuinely user-owned: a customer
+      // who wants to run code on an auth event creates a function in
+      // `public` (or any non-managed schema) and points the trigger at it.
+      // Supabase's own auth/storage triggers either come from extensions
+      // (already filtered out at extract time via `pg_depend`) or call
+      // functions inside the same managed schema, so `function_schema`
+      // outside the managed list is a reliable user-defined marker.
+      {
+        and: [
+          { objectType: "trigger" },
+          { "trigger/schema": [...SUPABASE_SYSTEM_SCHEMAS] },
+          {
+            not: {
+              "trigger/function_schema": [...SUPABASE_SYSTEM_SCHEMAS],
+            },
+          },
+          // Defensive fallback for dynamically-created pgmq queue /
+          // archive tables. `pgmq.q_<name>` and `pgmq.a_<name>` are
+          // materialized by `select pgmq.create('<name>')`, NOT by
+          // `CREATE EXTENSION pgmq`, so emitting a user trigger against
+          // them fails locally with
+          // `relation "pgmq.q_<name>" does not exist`. On a healthy
+          // install the trigger extractor's `extension_table_oids` join
+          // (packages/pg-delta/src/core/objects/trigger/trigger.model.ts)
+          // already drops these via the `pg_depend deptype='e'` row pgmq
+          // records during `pgmq.create()`; this rule covers projects
+          // where that row is missing (older pgmq, manual table
+          // rewrites, `pg_dump`/restore that loses extension deps, ...).
+          // pgmq 1.4.4 — the version Supabase Cloud currently ships —
+          // does not record the dependency at all.
+          {
+            not: {
+              and: [
+                { "trigger/schema": "pgmq" },
+                {
+                  "trigger/table_name": { op: "regex", value: "^[qa]_" },
+                },
+              ],
+            },
+          },
+        ],
+      },
+      // 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],
+                },
+              ],
+            },
+            // Platform-managed foreign data wrapper ACL.
+            // `GRANT`/`REVOKE ... ON FOREIGN DATA WRAPPER` requires
+            // superuser. On Supabase Cloud `postgres` has the elevated
+            // rights to make this work, but the local Docker image does
+            // not, so `supabase db reset` aborts with
+            // `permission denied for foreign-data wrapper`. The
+            // `*/owner` rule above already covers wrappers owned by
+            // `supabase_admin`, but `pg_dump` rewrites OWNER TO clauses
+            // to whoever the dump runs under, so after a restore the
+            // FDW typically ends up owned by `postgres` and slips past
+            // the owner gate. A non-superuser `postgres` still can't
+            // grant on a FDW (this is true regardless of who owns the
+            // wrapper locally), so the ACL diff is not user-replayable.
+            // We don't apply the same blanket rule to `FOREIGN SERVER`:
+            // server GRANT/REVOKE doesn't require superuser, and
+            // user-created servers (e.g. a `dblink` server pointing to
+            // a peer DB) carry legitimate user ACL that should
+            // roundtrip — the existing `*/owner` rule already drops
+            // platform-managed servers.
+            {
+              and: [
+                { objectType: "foreign_data_wrapper" },
+                { scope: "privilege" },
+              ],
+            },
+            // Platform-managed foreign data wrappers — Wasm-based FDWs
+            // (e.g. `clerk`, `clerk_oauth`) provisioned via the `wrappers`
+            // extension. Supabase Cloud creates these as
+            // `CREATE FOREIGN DATA WRAPPER clerk_oauth HANDLER
+            // extensions.wasm_fdw_handler VALIDATOR
+            // extensions.wasm_fdw_validator` at project creation; replaying
+            // the DDL against a local image fails because the local
+            // environment has no equivalent pre-step. We can't rely on the
+            // FDW owner alone — after a dump/restore the owner is often
+            // rewritten away from `supabase_admin` — so match on the shared
+            // Wasm handler/validator (`extensions.wasm_fdw_handler` /
+            // `extensions.wasm_fdw_validator`) instead.
+            //
+            // Matching the bare `extensions.*` namespace would be too broad:
+            // contrib FDWs like `postgres_fdw` also install their
+            // handler/validator into `extensions` on Supabase, and those ARE
+            // available in the local image, so a user-created `postgres_fdw`
+            // wrapper (and its servers/foreign tables/user mappings) must
+            // still roundtrip. Keying on the `wasm_fdw_*` function names
+            // targets only the platform Wasm wrappers.
+            {
+              and: [
+                { objectType: "foreign_data_wrapper" },
+                {
+                  or: [
+                    {
+                      "foreign_data_wrapper/handler": {
+                        op: "regex",
+                        value: "^extensions\\.wasm_fdw_handler$",
+                      },
+                    },
+                    {
+                      "foreign_data_wrapper/validator": {
+                        op: "regex",
+                        value: "^extensions\\.wasm_fdw_validator$",
+                      },
+                    },
+                  ],
+                },
+              ],
+            },
+            // Platform-managed Wasm FDW dependents (CLI-1470 follow-up).
+            // Suppressing the wrapper DDL alone leaves `CREATE SERVER` /
+            // `CREATE FOREIGN TABLE` / `CREATE USER MAPPING` that reference
+            // a wrapper local Docker never provisions (`clerk_oauth`, etc.).
+            // Match on the parent wrapper's Wasm handler/validator
+            // (`extensions.wasm_fdw_handler` / `extensions.wasm_fdw_validator`,
+            // joined at extract time) — the same discriminator used for the
+            // wrapper itself above. A bare `extensions.*` match would also
+            // drop user-created `postgres_fdw` servers/foreign tables/user
+            // mappings (whose handler installs into `extensions` but which
+            // the local image CAN provision), so keep it scoped to the Wasm
+            // function names. Server _privilege_ scope is excluded here —
+            // `GRANT/REVOKE ON SERVER` does not require superuser and remains
+            // user-declarative state (see CLI-1469 companion test).
+            {
+              and: [
+                { objectType: "server" },
+                { not: { scope: "privilege" } },
+                {
+                  or: [
+                    {
+                      "{server,foreign_table,user_mapping}/wrapper_handler": {
+                        op: "regex",
+                        value: "^extensions\\.wasm_fdw_handler$",
+                      },
+                    },
+                    {
+                      "{server,foreign_table,user_mapping}/wrapper_validator": {
+                        op: "regex",
+                        value: "^extensions\\.wasm_fdw_validator$",
+                      },
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              and: [
+                { objectType: ["foreign_table", "user_mapping"] },
+                {
+                  or: [
+                    {
+                      "{server,foreign_table,user_mapping}/wrapper_handler": {
+                        op: "regex",
+                        value: "^extensions\\.wasm_fdw_handler$",
+                      },
+                    },
+                    {
+                      "{server,foreign_table,user_mapping}/wrapper_validator": {
+                        op: "regex",
+                        value: "^extensions\\.wasm_fdw_validator$",
+                      },
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      },
+    ],
+  },
+  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,
+    ]);
+  });
+});