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

package/src/core/objects/schema/changes/schema.create.ts

@@ -0,0 +1,47 @@
+import { stableId } from "../../utils.ts";
+import type { Schema } from "../schema.model.ts";
+import { CreateSchemaChange } from "./schema.base.ts";
+
+/**
+ * Create a schema.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-createschema.html
+ *
+ * Synopsis
+ * ```sql
+ * CREATE SCHEMA [ IF NOT EXISTS ] schema_name [ AUTHORIZATION role_specification ] [ schema_element [ ... ] ]
+ * CREATE SCHEMA [ IF NOT EXISTS ] AUTHORIZATION role_specification [ schema_element [ ... ] ]
+ * CREATE SCHEMA [ IF NOT EXISTS ] schema_name AUTHORIZATION role_specification [ schema_element [ ... ] ]
+ * ```
+ */
+export class CreateSchema extends CreateSchemaChange {
+  public readonly schema: Schema;
+  public readonly scope = "object" as const;
+
+  constructor(props: { schema: Schema; skipAuthorization?: boolean }) {
+    super();
+    this.schema = props.schema;
+  }
+
+  get creates() {
+    return [this.schema.stableId];
+  }
+
+  get requires() {
+    return [stableId.role(this.schema.owner)];
+  }
+
+  serialize(options?: { skipAuthorization?: boolean }): string {
+    const parts: string[] = ["CREATE SCHEMA"];
+
+    // Add schema name
+    parts.push(this.schema.name);
+
+    // Add AUTHORIZATION
+    if (!options?.skipAuthorization) {
+      parts.push("AUTHORIZATION", this.schema.owner);
+    }
+
+    return parts.join(" ");
+  }
+}

package/src/core/objects/schema/changes/schema.drop.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { Schema } from "../schema.model.ts";
+import { DropSchema } from "./schema.drop.ts";
+
+describe("schema", () => {
+  test("drop", () => {
+    const schema = new Schema({
+      name: "test_schema",
+      owner: "test",
+      comment: null,
+      privileges: [],
+    });
+
+    const change = new DropSchema({
+      schema,
+    });
+
+    expect(change.serialize()).toBe("DROP SCHEMA test_schema");
+  });
+});

package/src/core/objects/schema/changes/schema.drop.ts

@@ -0,0 +1,34 @@
+import type { Schema } from "../schema.model.ts";
+import { DropSchemaChange } from "./schema.base.ts";
+
+/**
+ * Drop a schema.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-dropschema.html
+ *
+ * Synopsis
+ * ```sql
+ * DROP SCHEMA [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ]
+ * ```
+ */
+export class DropSchema extends DropSchemaChange {
+  public readonly schema: Schema;
+  public readonly scope = "object" as const;
+
+  constructor(props: { schema: Schema }) {
+    super();
+    this.schema = props.schema;
+  }
+
+  get drops() {
+    return [this.schema.stableId];
+  }
+
+  get requires() {
+    return [this.schema.stableId];
+  }
+
+  serialize(): string {
+    return ["DROP SCHEMA", this.schema.name].join(" ");
+  }
+}

package/src/core/objects/schema/changes/schema.privilege.ts

@@ -0,0 +1,175 @@
+import {
+  formatObjectPrivilegeList,
+  getObjectKindPrefix,
+} from "../../base.privilege.ts";
+import { stableId } from "../../utils.ts";
+import type { Schema } from "../schema.model.ts";
+import { AlterSchemaChange } from "./schema.base.ts";
+
+export type SchemaPrivilege =
+  | GrantSchemaPrivileges
+  | RevokeSchemaPrivileges
+  | RevokeGrantOptionSchemaPrivileges;
+
+/**
+ * Grant privileges on a schema.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-grant.html
+ *
+ * Synopsis
+ * ```sql
+ * GRANT { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] }
+ *    ON SCHEMA schema_name [, ...]
+ *    TO role_specification [, ...] [ WITH GRANT OPTION ]
+ *    [ GRANTED BY role_specification ]
+ * ```
+ */
+export class GrantSchemaPrivileges extends AlterSchemaChange {
+  public readonly schema: Schema;
+  public readonly grantee: string;
+  public readonly privileges: { privilege: string; grantable: boolean }[];
+  public readonly version: number | undefined;
+  public readonly scope = "privilege" as const;
+
+  constructor(props: {
+    schema: Schema;
+    grantee: string;
+    privileges: { privilege: string; grantable: boolean }[];
+    version?: number;
+  }) {
+    super();
+    this.schema = props.schema;
+    this.grantee = props.grantee;
+    this.privileges = props.privileges;
+    this.version = props.version;
+  }
+
+  get creates() {
+    return [stableId.acl(this.schema.stableId, this.grantee)];
+  }
+
+  get requires() {
+    return [this.schema.stableId, stableId.role(this.grantee)];
+  }
+
+  serialize(): string {
+    const hasGrantable = this.privileges.some((p) => p.grantable);
+    const hasBase = this.privileges.some((p) => !p.grantable);
+    if (hasGrantable && hasBase) {
+      throw new Error(
+        "GrantSchemaPrivileges expects privileges with uniform grantable flag",
+      );
+    }
+    const withGrant = hasGrantable ? " WITH GRANT OPTION" : "";
+    const kindPrefix = getObjectKindPrefix("SCHEMA");
+    const list = this.privileges.map((p) => p.privilege);
+    const privSql = formatObjectPrivilegeList("SCHEMA", list, this.version);
+    const schemaName = this.schema.name;
+    return `GRANT ${privSql} ${kindPrefix} ${schemaName} TO ${this.grantee}${withGrant}`;
+  }
+}
+
+/**
+ * Revoke privileges on a schema.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-revoke.html
+ *
+ * Synopsis
+ * ```sql
+ * REVOKE [ GRANT OPTION FOR ]
+ *     { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] }
+ *     ON SCHEMA schema_name [, ...]
+ *     FROM role_specification [, ...]
+ *     [ GRANTED BY role_specification ]
+ *     [ CASCADE | RESTRICT ]
+ * ```
+ */
+export class RevokeSchemaPrivileges extends AlterSchemaChange {
+  public readonly schema: Schema;
+  public readonly grantee: string;
+  public readonly privileges: { privilege: string; grantable: boolean }[];
+  public readonly version: number | undefined;
+  public readonly scope = "privilege" as const;
+
+  constructor(props: {
+    schema: Schema;
+    grantee: string;
+    privileges: { privilege: string; grantable: boolean }[];
+    version?: number;
+  }) {
+    super();
+    this.schema = props.schema;
+    this.grantee = props.grantee;
+    this.privileges = props.privileges;
+    this.version = props.version;
+  }
+
+  get drops() {
+    // Return ACL ID for dependency tracking, even though this is an ALTER operation
+    // Phase assignment now uses operation type, so this won't affect phase placement
+    return [stableId.acl(this.schema.stableId, this.grantee)];
+  }
+
+  get requires() {
+    return [
+      stableId.acl(this.schema.stableId, this.grantee),
+      this.schema.stableId,
+      stableId.role(this.grantee),
+    ];
+  }
+
+  serialize(): string {
+    const kindPrefix = getObjectKindPrefix("SCHEMA");
+    const list = this.privileges.map((p) => p.privilege);
+    const privSql = formatObjectPrivilegeList("SCHEMA", list, this.version);
+    const schemaName = this.schema.name;
+    return `REVOKE ${privSql} ${kindPrefix} ${schemaName} FROM ${this.grantee}`;
+  }
+}
+
+/**
+ * Revoke grant option for privileges on a schema.
+ *
+ * This removes the ability to grant the privilege to others, but keeps the privilege itself.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-revoke.html
+ */
+export class RevokeGrantOptionSchemaPrivileges extends AlterSchemaChange {
+  public readonly schema: Schema;
+  public readonly grantee: string;
+  public readonly privilegeNames: string[];
+  public readonly version: number | undefined;
+  public readonly scope = "privilege" as const;
+
+  constructor(props: {
+    schema: Schema;
+    grantee: string;
+    privilegeNames: string[];
+    version?: number;
+  }) {
+    super();
+    this.schema = props.schema;
+    this.grantee = props.grantee;
+    this.privilegeNames = [...new Set(props.privilegeNames)].sort();
+    this.version = props.version;
+  }
+
+  get requires() {
+    return [
+      stableId.acl(this.schema.stableId, this.grantee),
+      this.schema.stableId,
+      stableId.role(this.grantee),
+    ];
+  }
+
+  serialize(): string {
+    const kindPrefix = getObjectKindPrefix("SCHEMA");
+    const privSql = formatObjectPrivilegeList(
+      "SCHEMA",
+      this.privilegeNames,
+      this.version,
+    );
+    const schemaName = this.schema.name;
+    return `REVOKE GRANT OPTION FOR ${privSql} ${kindPrefix} ${schemaName} FROM ${this.grantee}`;
+  }
+}

package/src/core/objects/schema/changes/schema.types.ts

@@ -0,0 +1,12 @@
+import type { AlterSchema } from "./schema.alter.ts";
+import type { CommentSchema } from "./schema.comment.ts";
+import type { CreateSchema } from "./schema.create.ts";
+import type { DropSchema } from "./schema.drop.ts";
+import type { SchemaPrivilege } from "./schema.privilege.ts";
+
+export type SchemaChange =
+  | AlterSchema
+  | CommentSchema
+  | CreateSchema
+  | DropSchema
+  | SchemaPrivilege;

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

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { DefaultPrivilegeState } from "../base.default-privileges.ts";
+import { AlterSchemaChangeOwner } from "./changes/schema.alter.ts";
+import { CreateSchema } from "./changes/schema.create.ts";
+import { DropSchema } from "./changes/schema.drop.ts";
+import { diffSchemas } from "./schema.diff.ts";
+import { Schema, type SchemaProps } from "./schema.model.ts";
+
+const base: SchemaProps = {
+  name: "utils",
+  owner: "o1",
+  comment: null,
+  privileges: [],
+};
+
+const testContext = {
+  version: 170000,
+  currentUser: "postgres",
+  defaultPrivilegeState: new DefaultPrivilegeState({}),
+  mainRoles: {},
+};
+
+describe.concurrent("schema.diff", () => {
+  test("create and drop", () => {
+    const s = new Schema(base);
+    const created = diffSchemas(testContext, {}, { [s.stableId]: s });
+    expect(created[0]).toBeInstanceOf(CreateSchema);
+    const dropped = diffSchemas(testContext, { [s.stableId]: s }, {});
+    expect(dropped[0]).toBeInstanceOf(DropSchema);
+  });
+
+  test("alter owner", () => {
+    const main = new Schema(base);
+    const branch = new Schema({ ...base, owner: "o2" });
+    const changes = diffSchemas(
+      testContext,
+      { [main.stableId]: main },
+      { [branch.stableId]: branch },
+    );
+    expect(changes[0]).toBeInstanceOf(AlterSchemaChangeOwner);
+  });
+});

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

@@ -0,0 +1,209 @@
+import type { DefaultPrivilegeState } from "../base.default-privileges.ts";
+import { diffObjects } from "../base.diff.ts";
+import {
+  diffPrivileges,
+  groupPrivilegesByGrantable,
+} from "../base.privilege-diff.ts";
+import type { Role } from "../role/role.model.ts";
+import { AlterSchemaChangeOwner } from "./changes/schema.alter.ts";
+import {
+  CreateCommentOnSchema,
+  DropCommentOnSchema,
+} from "./changes/schema.comment.ts";
+import { CreateSchema } from "./changes/schema.create.ts";
+import { DropSchema } from "./changes/schema.drop.ts";
+import {
+  GrantSchemaPrivileges,
+  RevokeGrantOptionSchemaPrivileges,
+  RevokeSchemaPrivileges,
+} from "./changes/schema.privilege.ts";
+import type { SchemaChange } from "./changes/schema.types.ts";
+import type { Schema } from "./schema.model.ts";
+
+/**
+ * Diff two sets of schemas from main and branch catalogs.
+ *
+ * @param ctx - Context containing version, currentUser, and defaultPrivilegeState
+ * @param main - The schemas in the main catalog.
+ * @param branch - The schemas in the branch catalog.
+ * @returns A list of changes to apply to main to make it match branch.
+ */
+export function diffSchemas(
+  ctx: {
+    version: number;
+    currentUser: string;
+    defaultPrivilegeState: DefaultPrivilegeState;
+    mainRoles: Record<string, Role>;
+  },
+  main: Record<string, Schema>,
+  branch: Record<string, Schema>,
+): SchemaChange[] {
+  const { created, dropped, altered } = diffObjects(main, branch);
+
+  const changes: SchemaChange[] = [];
+
+  for (const schemaId of created) {
+    const sc = branch[schemaId];
+    changes.push(new CreateSchema({ schema: sc }));
+    if (sc.comment !== null) {
+      changes.push(new CreateCommentOnSchema({ schema: sc }));
+    }
+
+    // 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.
+    // Note: Schemas don't have a schema property, so we pass empty string
+    const effectiveDefaults = ctx.defaultPrivilegeState.getEffectiveDefaults(
+      ctx.currentUser,
+      "schema",
+      "",
+    );
+    const desiredPrivileges = sc.privileges;
+    // Filter out owner privileges - owner always has ALL privileges implicitly
+    // and shouldn't be compared. Use the schema owner as the reference.
+    const privilegeResults = diffPrivileges(
+      effectiveDefaults,
+      desiredPrivileges,
+      sc.owner,
+      ctx.mainRoles,
+    );
+
+    // Generate grant changes
+    for (const [grantee, result] of privilegeResults) {
+      if (result.grants.length > 0) {
+        const grantGroups = groupPrivilegesByGrantable(result.grants);
+        for (const [grantable, list] of grantGroups) {
+          void grantable;
+          changes.push(
+            new GrantSchemaPrivileges({
+              schema: sc,
+              grantee,
+              privileges: list,
+              version: ctx.version,
+            }),
+          );
+        }
+      }
+
+      // Generate revoke changes
+      if (result.revokes.length > 0) {
+        const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+        for (const [grantable, list] of revokeGroups) {
+          void grantable;
+          changes.push(
+            new RevokeSchemaPrivileges({
+              schema: sc,
+              grantee,
+              privileges: list,
+              version: ctx.version,
+            }),
+          );
+        }
+      }
+
+      // Generate revoke grant option changes
+      if (result.revokeGrantOption.length > 0) {
+        changes.push(
+          new RevokeGrantOptionSchemaPrivileges({
+            schema: sc,
+            grantee,
+            privilegeNames: result.revokeGrantOption,
+            version: ctx.version,
+          }),
+        );
+      }
+    }
+  }
+
+  for (const schemaId of dropped) {
+    changes.push(new DropSchema({ schema: main[schemaId] }));
+  }
+
+  for (const schemaId of altered) {
+    const mainSchema = main[schemaId];
+    const branchSchema = branch[schemaId];
+
+    // OWNER
+    if (mainSchema.owner !== branchSchema.owner) {
+      changes.push(
+        new AlterSchemaChangeOwner({
+          schema: mainSchema,
+          owner: branchSchema.owner,
+        }),
+      );
+    }
+
+    // COMMENT
+    if (mainSchema.comment !== branchSchema.comment) {
+      if (branchSchema.comment === null) {
+        changes.push(new DropCommentOnSchema({ schema: mainSchema }));
+      } else {
+        changes.push(new CreateCommentOnSchema({ schema: branchSchema }));
+      }
+    }
+
+    // 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(
+      mainSchema.privileges,
+      branchSchema.privileges,
+      branchSchema.owner,
+      ctx.mainRoles,
+    );
+
+    for (const [grantee, result] of privilegeResults) {
+      // Generate grant changes
+      if (result.grants.length > 0) {
+        const grantGroups = groupPrivilegesByGrantable(result.grants);
+        for (const [grantable, list] of grantGroups) {
+          void grantable;
+          changes.push(
+            new GrantSchemaPrivileges({
+              schema: branchSchema,
+              grantee,
+              privileges: list,
+              version: ctx.version,
+            }),
+          );
+        }
+      }
+
+      // Generate revoke changes
+      if (result.revokes.length > 0) {
+        const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+        for (const [grantable, list] of revokeGroups) {
+          void grantable;
+          changes.push(
+            new RevokeSchemaPrivileges({
+              schema: mainSchema,
+              grantee,
+              privileges: list,
+              version: ctx.version,
+            }),
+          );
+        }
+      }
+
+      // Generate revoke grant option changes
+      if (result.revokeGrantOption.length > 0) {
+        changes.push(
+          new RevokeGrantOptionSchemaPrivileges({
+            schema: mainSchema,
+            grantee,
+            privilegeNames: result.revokeGrantOption,
+            version: ctx.version,
+          }),
+        );
+      }
+    }
+
+    // Note: Schema renaming would also use ALTER SCHEMA ... RENAME TO ...
+    // But since our Schema model uses 'schema' as the identity field,
+    // a name change would be handled as drop + create by diffObjects()
+  }
+
+  return changes;
+}

package/src/core/objects/schema/schema.model.ts

@@ -0,0 +1,107 @@
+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";
+
+/**
+ * All properties exposed by CREATE SCHEMA statement are included in diff output.
+ * https://www.postgresql.org/docs/current/sql-createschema.html
+ *
+ * ALTER SCHEMA statement can be generated for all properties.
+ * https://www.postgresql.org/docs/current/sql-alterschema.html
+ */
+const schemaPropsSchema = z.object({
+  name: z.string(),
+  owner: z.string(),
+  comment: z.string().nullable(),
+  privileges: z.array(privilegePropsSchema),
+});
+
+type SchemaPrivilegeProps = PrivilegeProps;
+export type SchemaProps = z.infer<typeof schemaPropsSchema>;
+
+export class Schema extends BasePgModel {
+  public readonly name: SchemaProps["name"];
+  public readonly owner: SchemaProps["owner"];
+  public readonly comment: SchemaProps["comment"];
+  public readonly privileges: SchemaPrivilegeProps[];
+
+  constructor(props: SchemaProps) {
+    super();
+
+    // Identity fields
+    this.name = props.name;
+
+    // Data fields
+    this.owner = props.owner;
+    this.comment = props.comment;
+    this.privileges = props.privileges;
+  }
+
+  get stableId(): `schema:${string}` {
+    return `schema:${this.name}`;
+  }
+
+  get identityFields() {
+    return {
+      name: this.name,
+    };
+  }
+
+  get dataFields() {
+    return {
+      owner: this.owner,
+      comment: this.comment,
+      privileges: this.privileges,
+    };
+  }
+}
+
+export async function extractSchemas(pool: Pool): Promise<Schema[]> {
+  const { rows: schemaRows } = await pool.query<SchemaProps>(sql`
+    with extension_oids as (
+      select
+        objid
+      from
+        pg_depend d
+      where
+        d.refclassid = 'pg_extension'::regclass
+        and d.classid = 'pg_namespace'::regclass
+    )
+    select
+      quote_ident(nspname) as name,
+      nspowner::regrole::text as owner,
+      obj_description(oid, 'pg_namespace') 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(nspacl) as x(grantor, grantee, privilege_type, is_grantable)
+        ), '[]'
+      ) as privileges
+    from
+      pg_catalog.pg_namespace
+      left outer join extension_oids e on e.objid = oid
+      -- <EXCLUDE_INTERNAL>
+      where not nspname like any(array['pg\\_%', 'information\\_schema'])
+      and e.objid is null
+      -- </EXCLUDE_INTERNAL>
+    order by
+      1
+  `);
+  // Validate and parse each row using the Zod schema
+  const validatedRows = schemaRows.map((row: unknown) =>
+    schemaPropsSchema.parse(row),
+  );
+  return validatedRows.map((row: SchemaProps) => new Schema(row));
+}