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

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

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

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

@@ -0,0 +1,20 @@
+import { BaseChange } from "../../base.change.ts";
+import type { Schema } from "../schema.model.ts";
+
+abstract class BaseSchemaChange extends BaseChange {
+  abstract readonly schema: Schema;
+  abstract readonly scope: "object" | "comment" | "privilege";
+  readonly objectType: "schema" = "schema";
+}
+
+export abstract class CreateSchemaChange extends BaseSchemaChange {
+  readonly operation = "create" as const;
+}
+
+export abstract class AlterSchemaChange extends BaseSchemaChange {
+  readonly operation = "alter" as const;
+}
+
+export abstract class DropSchemaChange extends BaseSchemaChange {
+  readonly operation = "drop" as const;
+}

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

@@ -0,0 +1,57 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
+import { quoteLiteral } from "../../base.change.ts";
+import { stableId } from "../../utils.ts";
+import type { Schema } from "../schema.model.ts";
+import { CreateSchemaChange, DropSchemaChange } from "./schema.base.ts";
+
+export type CommentSchema = CreateCommentOnSchema | DropCommentOnSchema;
+
+export class CreateCommentOnSchema extends CreateSchemaChange {
+  public readonly schema: Schema;
+  public readonly scope = "comment" as const;
+
+  constructor(props: { schema: Schema }) {
+    super();
+    this.schema = props.schema;
+  }
+
+  get creates() {
+    return [stableId.comment(this.schema.stableId)];
+  }
+
+  get requires() {
+    return [this.schema.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return [
+      "COMMENT ON SCHEMA",
+      this.schema.name,
+      "IS",
+      // biome-ignore lint/style/noNonNullAssertion: schema comment is not nullable in this case
+      quoteLiteral(this.schema.comment!),
+    ].join(" ");
+  }
+}
+
+export class DropCommentOnSchema extends DropSchemaChange {
+  public readonly schema: Schema;
+  public readonly scope = "comment" as const;
+
+  constructor(props: { schema: Schema }) {
+    super();
+    this.schema = props.schema;
+  }
+
+  get drops() {
+    return [stableId.comment(this.schema.stableId)];
+  }
+
+  get requires() {
+    return [stableId.comment(this.schema.stableId), this.schema.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return ["COMMENT ON SCHEMA", this.schema.name, "IS NULL"].join(" ");
+  }
+}

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

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { assertValidSql } from "../../../test-utils/assert-valid-sql.ts";
+import { Schema } from "../schema.model.ts";
+import { CreateSchema } from "./schema.create.ts";
+
+describe("schema", () => {
+  test("create", async () => {
+    const schema = new Schema({
+      name: "test_schema",
+      owner: "test",
+      comment: null,
+      privileges: [],
+    });
+
+    const change = new CreateSchema({
+      schema,
+    });
+
+    await assertValidSql(change.serialize());
+
+    expect(change.serialize()).toBe(
+      "CREATE SCHEMA test_schema AUTHORIZATION test",
+    );
+  });
+});

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

@@ -0,0 +1,47 @@
+import type { SchemaSerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
+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 } & SchemaSerializeOptions) {
+    super();
+    this.schema = props.schema;
+  }
+
+  get creates() {
+    return [this.schema.stableId];
+  }
+
+  get requires() {
+    return [stableId.role(this.schema.owner)];
+  }
+
+  serialize(options?: SchemaSerializeOptions): 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,23 @@
+import { describe, expect, test } from "bun:test";
+import { assertValidSql } from "../../../test-utils/assert-valid-sql.ts";
+import { Schema } from "../schema.model.ts";
+import { DropSchema } from "./schema.drop.ts";
+
+describe("schema", () => {
+  test("drop", async () => {
+    const schema = new Schema({
+      name: "test_schema",
+      owner: "test",
+      comment: null,
+      privileges: [],
+    });
+
+    const change = new DropSchema({
+      schema,
+    });
+
+    await assertValidSql(change.serialize());
+
+    expect(change.serialize()).toBe("DROP SCHEMA test_schema");
+  });
+});

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

@@ -0,0 +1,35 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
+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(_options?: SerializeOptions): string {
+    return ["DROP SCHEMA", this.schema.name].join(" ");
+  }
+}

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

@@ -0,0 +1,176 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
+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(_options?: SerializeOptions): 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(_options?: SerializeOptions): 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(_options?: SerializeOptions): 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,13 @@
+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";
+
+/** Union of all schema-related change variants (`objectType: "schema"`). @category Change Types */
+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,146 @@
+import { diffObjects } from "../base.diff.ts";
+import {
+  diffPrivileges,
+  emitObjectPrivilegeChanges,
+} from "../base.privilege-diff.ts";
+import type { ObjectDiffContext } from "../diff-context.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: Pick<
+    ObjectDiffContext,
+    "version" | "currentUser" | "defaultPrivilegeState"
+  >,
+  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 creatorFilteredDefaults =
+      sc.owner !== ctx.currentUser
+        ? effectiveDefaults.filter((p) => p.grantee !== ctx.currentUser)
+        : effectiveDefaults;
+    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(
+      creatorFilteredDefaults,
+      desiredPrivileges,
+      sc.owner,
+    );
+
+    changes.push(
+      ...(emitObjectPrivilegeChanges(
+        privilegeResults,
+        sc,
+        sc,
+        "schema",
+        {
+          Grant: GrantSchemaPrivileges,
+          Revoke: RevokeSchemaPrivileges,
+          RevokeGrantOption: RevokeGrantOptionSchemaPrivileges,
+        },
+        ctx.version,
+      ) as SchemaChange[]),
+    );
+  }
+
+  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,
+    );
+
+    changes.push(
+      ...(emitObjectPrivilegeChanges(
+        privilegeResults,
+        branchSchema,
+        mainSchema,
+        "schema",
+        {
+          Grant: GrantSchemaPrivileges,
+          Revoke: RevokeSchemaPrivileges,
+          RevokeGrantOption: RevokeGrantOptionSchemaPrivileges,
+        },
+        ctx.version,
+      ) as SchemaChange[]),
+    );
+
+    // 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;
+}