@supabase/pg-delta 0.0.0 → 1.0.0-alpha.0

package/dist/core/objects/base.default-privileges.js

@@ -0,0 +1,167 @@
+/**
+ * Maps object type names to PostgreSQL default privilege objtype codes.
+ * Used to look up default privileges for different object types.
+ */
+function objectTypeToObjtype(objectType) {
+    switch (objectType) {
+        case "table":
+            return "r"; // Relations (tables)
+        case "view":
+            return "r"; // Views are also relations
+        case "materialized_view":
+            return "r"; // Materialized views are also relations
+        case "sequence":
+            return "S"; // Sequences
+        case "procedure":
+        case "function":
+        case "aggregate":
+            return "f"; // Functions/routines
+        case "type":
+        case "domain":
+        case "enum":
+        case "range":
+        case "composite_type":
+            return "T"; // Types
+        case "schema":
+            return "n"; // Schemas
+        default:
+            return null;
+    }
+}
+/**
+ * Tracks the effective state of default privileges as changes are processed.
+ * This allows us to compute what default privileges would be in effect at any point
+ * in the migration script, accounting for ALTER DEFAULT PRIVILEGES statements.
+ */
+export class DefaultPrivilegeState {
+    state = new Map(); // role -> objtype -> schema -> grantee -> privileges
+    constructor(initialRoles) {
+        // Initialize state from roles' default_privileges
+        for (const [_roleId, role] of Object.entries(initialRoles)) {
+            const roleName = role.name;
+            if (!this.state.has(roleName)) {
+                this.state.set(roleName, new Map());
+            }
+            // biome-ignore lint/style/noNonNullAssertion: roleName is guaranteed to be in the state
+            const roleState = this.state.get(roleName);
+            for (const defPriv of role.default_privileges) {
+                if (!roleState.has(defPriv.objtype)) {
+                    roleState.set(defPriv.objtype, new Map());
+                }
+                // biome-ignore lint/style/noNonNullAssertion: objtype is guaranteed to be in the state
+                const objtypeState = roleState.get(defPriv.objtype);
+                const schemaKey = defPriv.in_schema ?? null;
+                if (!objtypeState.has(schemaKey)) {
+                    objtypeState.set(schemaKey, new Map());
+                }
+                // biome-ignore lint/style/noNonNullAssertion: schemaKey is guaranteed to be in the state
+                const schemaState = objtypeState.get(schemaKey);
+                if (!schemaState.has(defPriv.grantee)) {
+                    schemaState.set(defPriv.grantee, new Set());
+                }
+                // biome-ignore lint/style/noNonNullAssertion: grantee is guaranteed to be in the state
+                const privileges = schemaState.get(defPriv.grantee);
+                for (const priv of defPriv.privileges) {
+                    const key = `${priv.privilege}:${priv.grantable}`;
+                    privileges.add(key);
+                }
+            }
+        }
+    }
+    /**
+     * Apply a GrantRoleDefaultPrivileges change to the state.
+     */
+    applyGrant(roleName, objtype, inSchema, grantee, privileges) {
+        if (!this.state.has(roleName)) {
+            this.state.set(roleName, new Map());
+        }
+        // biome-ignore lint/style/noNonNullAssertion: roleName is guaranteed to be in the state
+        const roleState = this.state.get(roleName);
+        if (!roleState.has(objtype)) {
+            roleState.set(objtype, new Map());
+        }
+        // biome-ignore lint/style/noNonNullAssertion: objtype is guaranteed to be in the state
+        const objtypeState = roleState.get(objtype);
+        const schemaKey = inSchema ?? null;
+        if (!objtypeState.has(schemaKey)) {
+            objtypeState.set(schemaKey, new Map());
+        }
+        // biome-ignore lint/style/noNonNullAssertion: schemaKey is guaranteed to be in the state
+        const schemaState = objtypeState.get(schemaKey);
+        if (!schemaState.has(grantee)) {
+            schemaState.set(grantee, new Set());
+        }
+        // biome-ignore lint/style/noNonNullAssertion: grantee is guaranteed to be in the state
+        const privilegesSet = schemaState.get(grantee);
+        for (const priv of privileges) {
+            const key = `${priv.privilege}:${priv.grantable}`;
+            privilegesSet.add(key);
+        }
+    }
+    /**
+     * Apply a RevokeRoleDefaultPrivileges change to the state.
+     */
+    applyRevoke(roleName, objtype, inSchema, grantee, privileges) {
+        const roleState = this.state.get(roleName);
+        if (!roleState)
+            return;
+        const objtypeState = roleState.get(objtype);
+        if (!objtypeState)
+            return;
+        const schemaKey = inSchema ?? null;
+        const schemaState = objtypeState.get(schemaKey);
+        if (!schemaState)
+            return;
+        const privilegesSet = schemaState.get(grantee);
+        if (!privilegesSet)
+            return;
+        for (const priv of privileges) {
+            const key = `${priv.privilege}:${priv.grantable}`;
+            privilegesSet.delete(key);
+            // Also remove base privilege if grantable was revoked
+            if (priv.grantable) {
+                const baseKey = `${priv.privilege}:false`;
+                privilegesSet.delete(baseKey);
+            }
+        }
+    }
+    /**
+     * Get effective default privileges for a given object creation.
+     */
+    getEffectiveDefaults(currentUser, objectType, objectSchema) {
+        const objtype = objectTypeToObjtype(objectType);
+        if (!objtype)
+            return [];
+        const roleState = this.state.get(currentUser);
+        if (!roleState)
+            return [];
+        const objtypeState = roleState.get(objtype);
+        if (!objtypeState)
+            return [];
+        const defaultPrivs = [];
+        // Check schema-specific first, then global (null schema)
+        const schemasToCheck = [objectSchema, null];
+        for (const schemaKey of schemasToCheck) {
+            const schemaState = objtypeState.get(schemaKey);
+            if (!schemaState)
+                continue;
+            for (const [grantee, privilegesSet] of schemaState.entries()) {
+                for (const privKey of privilegesSet) {
+                    const [privilege, grantableStr] = privKey.split(":");
+                    const grantable = grantableStr === "true";
+                    defaultPrivs.push({
+                        grantee,
+                        privilege,
+                        grantable,
+                        columns: null,
+                    });
+                }
+            }
+            // Schema-specific takes precedence, so break after first match
+            if (schemaKey === objectSchema && schemaState.size > 0) {
+                break;
+            }
+        }
+        return defaultPrivs;
+    }
+}

package/dist/core/objects/base.diff.d.ts

@@ -0,0 +1,6 @@
+import type { BasePgModel } from "./base.model.ts";
+export declare function diffObjects<T extends BasePgModel>(main: Record<string, T>, branch: Record<string, T>): {
+    created: string[];
+    dropped: string[];
+    altered: string[];
+};

package/dist/core/objects/base.diff.js

@@ -0,0 +1,12 @@
+export function diffObjects(main, branch) {
+    const mainIds = new Set(Object.keys(main));
+    const branchIds = new Set(Object.keys(branch));
+    const created = [...branchIds.difference(mainIds)];
+    const dropped = [...mainIds.difference(branchIds)];
+    const altered = [...mainIds.intersection(branchIds)].filter((id) => {
+        const mainModel = main[id];
+        const branchModel = branch[id];
+        return !mainModel.equals(branchModel);
+    });
+    return { created, dropped, altered };
+}

package/dist/core/objects/base.model.d.ts

@@ -0,0 +1,74 @@
+import z from "zod";
+export declare const columnPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    position: z.ZodNumber;
+    data_type: z.ZodString;
+    data_type_str: z.ZodString;
+    is_custom_type: z.ZodBoolean;
+    custom_type_type: z.ZodNullable<z.ZodString>;
+    custom_type_category: z.ZodNullable<z.ZodString>;
+    custom_type_schema: z.ZodNullable<z.ZodString>;
+    custom_type_name: z.ZodNullable<z.ZodString>;
+    not_null: z.ZodBoolean;
+    is_identity: z.ZodBoolean;
+    is_identity_always: z.ZodBoolean;
+    is_generated: z.ZodBoolean;
+    collation: z.ZodNullable<z.ZodString>;
+    default: z.ZodNullable<z.ZodString>;
+    comment: z.ZodNullable<z.ZodString>;
+}, z.z.core.$strip>;
+export type ColumnProps = z.infer<typeof columnPropsSchema>;
+export declare function normalizeColumns(columns: ColumnProps[]): {
+    name: string;
+    data_type: string;
+    data_type_str: string;
+    is_custom_type: boolean;
+    custom_type_type: string | null;
+    custom_type_category: string | null;
+    custom_type_schema: string | null;
+    custom_type_name: string | null;
+    not_null: boolean;
+    is_identity: boolean;
+    is_identity_always: boolean;
+    is_generated: boolean;
+    collation: string | null;
+    default: string | null;
+    comment: string | null;
+}[];
+/**
+ * Interface for table-like objects that have columns (tables, views, materialized views).
+ * In PostgreSQL, these are relations with relkind in ('r', 'p', 'v', 'm').
+ */
+export interface TableLikeObject {
+    readonly columns: ColumnProps[];
+}
+export declare abstract class BasePgModel {
+    /**
+     * Database-portable stable identifier for dependency resolution.
+     * This identifier remains constant across database dumps/restores and
+     * is used for cross-database dependency resolution.
+     */
+    abstract get stableId(): string;
+    /**
+     * Get all identity fields and their values.
+     * Subclasses should override this to return the identity fields.
+     */
+    abstract get identityFields(): Record<string, unknown>;
+    /**
+     * Get all data fields and their values.
+     * Subclasses should override this to return the data fields.
+     */
+    abstract get dataFields(): Record<string, unknown>;
+    /**
+     * Compare this object with another BasePgModel for equality based on stableId and dataFields.
+     */
+    equals(other: BasePgModel): boolean;
+    /**
+     * Stable representation used for equality/fingerprints.
+     * Subclasses can override to normalize unstable fields.
+     */
+    stableSnapshot(): {
+        identity: Record<string, unknown>;
+        data: Record<string, unknown>;
+    };
+}

package/dist/core/objects/base.model.js

@@ -0,0 +1,47 @@
+import z from "zod";
+import { deepEqual } from "./utils.js";
+export const columnPropsSchema = z.object({
+    name: z.string(),
+    position: z.number(),
+    data_type: z.string(),
+    data_type_str: z.string(),
+    is_custom_type: z.boolean(),
+    custom_type_type: z.string().nullable(),
+    custom_type_category: z.string().nullable(),
+    custom_type_schema: z.string().nullable(),
+    custom_type_name: z.string().nullable(),
+    not_null: z.boolean(),
+    is_identity: z.boolean(),
+    is_identity_always: z.boolean(),
+    is_generated: z.boolean(),
+    collation: z.string().nullable(),
+    default: z.string().nullable(),
+    comment: z.string().nullable(),
+});
+export function normalizeColumns(columns) {
+    return columns
+        .map((column) => {
+        const { position: _position, ...rest } = column;
+        return rest;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export class BasePgModel {
+    /**
+     * Compare this object with another BasePgModel for equality based on stableId and dataFields.
+     */
+    equals(other) {
+        return (this.stableId === other.stableId &&
+            deepEqual(this.dataFields, other.dataFields));
+    }
+    /**
+     * Stable representation used for equality/fingerprints.
+     * Subclasses can override to normalize unstable fields.
+     */
+    stableSnapshot() {
+        return {
+            identity: this.identityFields,
+            data: this.dataFields,
+        };
+    }
+}

package/dist/core/objects/base.privilege-diff.d.ts

@@ -0,0 +1,54 @@
+import z from "zod";
+import type { Change } from "../change.types.ts";
+import type { Role } from "./role/role.model.ts";
+/**
+ * Privilege properties that all privilege objects share.
+ */
+export declare const privilegePropsSchema: z.ZodObject<{
+    grantee: z.ZodString;
+    privilege: z.ZodString;
+    grantable: z.ZodBoolean;
+    columns: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.z.core.$strip>;
+export type PrivilegeProps = z.infer<typeof privilegePropsSchema>;
+/**
+ * Result of privilege diffing for a single grantee
+ */
+interface PrivilegeDiffResult<T extends PrivilegeProps> {
+    grants: T[];
+    revokes: T[];
+    revokeGrantOption: string[];
+}
+/**
+ * Groups privileges by grantable flag for efficient SQL generation
+ */
+export declare function groupPrivilegesByGrantable<T extends PrivilegeProps>(privileges: T[]): Map<boolean, T[]>;
+/**
+ * Groups privileges by columns and grantable flag
+ */
+export declare function groupPrivilegesByColumns<T extends PrivilegeProps>(privileges: T[]): Map<string, {
+    columns?: string[];
+    byGrant: Map<boolean, Set<string>>;
+}>;
+/**
+ * Filters out PUBLIC's built-in default privileges that PostgreSQL automatically grants
+ * when creating certain object types. This prevents generating unnecessary GRANT statements
+ * for privileges that PostgreSQL grants automatically.
+ *
+ * Reference: PostgreSQL 17 Documentation, Table 5.2 "Summary of Access Privileges"
+ * https://www.postgresql.org/docs/17/ddl-priv.html
+ *
+ * Objects with default PUBLIC privileges:
+ * - Functions/Procedures/Aggregates: EXECUTE
+ * - Types/Domains/Enums/Ranges/Composite Types: USAGE
+ * - Languages: USAGE
+ *
+ * Objects WITHOUT default PUBLIC privileges (so we should generate GRANT statements):
+ * - Tables, Views, Materialized Views, Sequences, Schemas, etc.
+ */
+export declare function filterPublicBuiltInDefaults<T extends PrivilegeProps>(objectType: Change["objectType"], privileges: T[]): T[];
+/**
+ * Generic privilege diffing function that works for any object type
+ */
+export declare function diffPrivileges<T extends PrivilegeProps>(mainPrivileges: T[], branchPrivileges: T[], owner?: string, mainRoles?: Record<string, Role>): Map<string, PrivilegeDiffResult<T>>;
+export {};

package/dist/core/objects/base.privilege-diff.js

@@ -0,0 +1,216 @@
+import z from "zod";
+import { stableId } from "./utils.js";
+/**
+ * Privilege properties that all privilege objects share.
+ */
+export const privilegePropsSchema = z.object({
+    grantee: z.string(),
+    privilege: z.string(),
+    grantable: z.boolean(),
+    columns: z.array(z.string()).nullable().optional(),
+});
+/**
+ * Groups privileges by grantee for efficient diffing
+ */
+function groupPrivilegesByGrantee(privileges) {
+    const byGrantee = new Map();
+    for (const privilege of privileges) {
+        const existing = byGrantee.get(privilege.grantee) || [];
+        existing.push(privilege);
+        byGrantee.set(privilege.grantee, existing);
+    }
+    return byGrantee;
+}
+/**
+ * Diffs privileges for a single grantee between main and branch
+ */
+function diffPrivilegesForGrantee(mainPrivs, branchPrivs) {
+    // Create comparison key - always include columns (null for object-level privileges)
+    const toKey = (p) => {
+        const cols = p.columns || [];
+        return `${p.privilege}:${p.grantable}:${cols.sort().join(",")}`;
+    };
+    // Create key-to-object mappings to retain original data structures
+    const mainKeyToObj = new Map(mainPrivs.map((p) => [toKey(p), p]));
+    const branchKeyToObj = new Map(branchPrivs.map((p) => [toKey(p), p]));
+    const aSet = new Set(mainPrivs.map(toKey));
+    const bSet = new Set(branchPrivs.map(toKey));
+    const grants = [];
+    const revokes = [];
+    const revokeGrantOption = [];
+    // Find privileges to grant
+    for (const key of bSet) {
+        if (!aSet.has(key)) {
+            const obj = branchKeyToObj.get(key);
+            if (obj)
+                grants.push(obj);
+        }
+    }
+    // Find privileges to revoke
+    for (const key of aSet) {
+        if (!bSet.has(key)) {
+            const obj = mainKeyToObj.get(key);
+            if (!obj)
+                continue;
+            const wasGrantable = obj.grantable;
+            // Upgrade: base -> with grant option (no base revoke)
+            const upgradedKey = key.replace(":false", ":true");
+            const upgraded = !wasGrantable && bSet.has(upgradedKey);
+            if (upgraded)
+                continue;
+            // If only grantable flipped from true to false, emit REVOKE GRANT OPTION FOR
+            const stillHasBase = checkStillHasBase(branchPrivs, obj.privilege, key);
+            if (wasGrantable && stillHasBase) {
+                revokeGrantOption.push(obj.privilege);
+            }
+            else {
+                revokes.push(obj);
+            }
+        }
+    }
+    return { grants, revokes, revokeGrantOption };
+}
+/**
+ * Check if a privilege still exists in the target set
+ */
+function checkStillHasBase(targetPrivs, privilege, key) {
+    const [, , columnsStr] = key.split(":");
+    return targetPrivs.some((p) => p.privilege === privilege &&
+        (p.columns || []).sort().join(",") === columnsStr);
+}
+/**
+ * Groups privileges by grantable flag for efficient SQL generation
+ */
+export function groupPrivilegesByGrantable(privileges) {
+    const groups = new Map();
+    for (const privilege of privileges) {
+        const arr = groups.get(privilege.grantable) ?? [];
+        arr.push(privilege);
+        groups.set(privilege.grantable, arr);
+    }
+    return groups;
+}
+/**
+ * Groups privileges by columns and grantable flag
+ */
+export function groupPrivilegesByColumns(privileges) {
+    const groups = new Map();
+    for (const privilege of privileges) {
+        const key = privilege.columns ? privilege.columns.sort().join(",") : "";
+        if (!groups.has(key)) {
+            groups.set(key, {
+                columns: privilege.columns ? [...privilege.columns] : undefined,
+                byGrant: new Map(),
+            });
+        }
+        const group = groups.get(key);
+        if (!group)
+            continue;
+        if (!group.byGrant.has(privilege.grantable)) {
+            group.byGrant.set(privilege.grantable, new Set());
+        }
+        const privSet = group.byGrant.get(privilege.grantable);
+        if (!privSet)
+            continue;
+        privSet.add(privilege.privilege);
+    }
+    return groups;
+}
+/**
+ * Filters out PUBLIC's built-in default privileges that PostgreSQL automatically grants
+ * when creating certain object types. This prevents generating unnecessary GRANT statements
+ * for privileges that PostgreSQL grants automatically.
+ *
+ * Reference: PostgreSQL 17 Documentation, Table 5.2 "Summary of Access Privileges"
+ * https://www.postgresql.org/docs/17/ddl-priv.html
+ *
+ * Objects with default PUBLIC privileges:
+ * - Functions/Procedures/Aggregates: EXECUTE
+ * - Types/Domains/Enums/Ranges/Composite Types: USAGE
+ * - Languages: USAGE
+ *
+ * Objects WITHOUT default PUBLIC privileges (so we should generate GRANT statements):
+ * - Tables, Views, Materialized Views, Sequences, Schemas, etc.
+ */
+export function filterPublicBuiltInDefaults(objectType, privileges) {
+    // Only filter PUBLIC privileges
+    return privileges.filter((priv) => {
+        if (priv.grantee !== "PUBLIC") {
+            return true; // Keep all non-PUBLIC privileges
+        }
+        // Check if this is a built-in default privilege for this object type
+        switch (objectType) {
+            case "procedure":
+            case "aggregate":
+                // Functions/Procedures/Aggregates: EXECUTE is granted to PUBLIC by default
+                // Filter it out so we don't generate unnecessary GRANT EXECUTE TO PUBLIC
+                return priv.privilege !== "EXECUTE";
+            case "domain":
+            case "enum":
+            case "range":
+            case "composite_type":
+                // Types/Domains/Enums/Ranges/Composite Types: USAGE is granted to PUBLIC by default
+                // Filter it out so we don't generate unnecessary GRANT USAGE TO PUBLIC
+                return priv.privilege !== "USAGE";
+            case "language":
+                // Languages: USAGE is granted to PUBLIC by default
+                // Filter it out so we don't generate unnecessary GRANT USAGE TO PUBLIC
+                return priv.privilege !== "USAGE";
+            default:
+                // For other object types (tables, views, sequences, schemas, etc.),
+                // PUBLIC has NO default privileges, so we should keep all PUBLIC privileges
+                // and generate GRANT statements for them
+                return true;
+        }
+    });
+}
+/**
+ * Filter out owner privileges from a privilege list.
+ * Owner privileges are implicit (owner always has ALL) and shouldn't be compared.
+ */
+function filterOwnerPrivileges(privileges, owner) {
+    return privileges.filter((p) => p.grantee !== owner);
+}
+/**
+ * Filter out privileges for superuser roles, as PostgreSQL doesn't store
+ * GRANTs to superusers in relacl (they already have all privileges implicitly).
+ * Reference: https://www.postgresql.org/docs/current/role-attributes.html
+ */
+function filterSuperuserPrivileges(privileges, mainRoles) {
+    if (!mainRoles)
+        return privileges;
+    return privileges.filter((priv) => {
+        const role = mainRoles[stableId.role(priv.grantee)];
+        return !role?.is_superuser;
+    });
+}
+/**
+ * Generic privilege diffing function that works for any object type
+ */
+export function diffPrivileges(mainPrivileges, branchPrivileges, owner, mainRoles) {
+    // Filter out superuser privileges from branch - PostgreSQL doesn't store GRANTs
+    // to superusers in relacl because they already have all privileges implicitly
+    const branchPrivilegesFiltered = filterSuperuserPrivileges(branchPrivileges, mainRoles);
+    // Filter out owner privileges if owner is provided
+    const mainFiltered = owner
+        ? filterOwnerPrivileges(mainPrivileges, owner)
+        : mainPrivileges;
+    const branchFiltered = owner
+        ? filterOwnerPrivileges(branchPrivilegesFiltered, owner)
+        : branchPrivilegesFiltered;
+    const mainByGrantee = groupPrivilegesByGrantee(mainFiltered);
+    const branchByGrantee = groupPrivilegesByGrantee(branchFiltered);
+    // Get all grantees
+    const allGrantees = new Set([
+        ...mainByGrantee.keys(),
+        ...branchByGrantee.keys(),
+    ]);
+    const results = new Map();
+    for (const grantee of allGrantees) {
+        const mainPrivs = mainByGrantee.get(grantee) || [];
+        const branchPrivs = branchByGrantee.get(grantee) || [];
+        const result = diffPrivilegesForGrantee(mainPrivs, branchPrivs);
+        results.set(grantee, result);
+    }
+    return results;
+}

package/dist/core/objects/base.privilege.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Base utilities and helpers for object privilege changes.
+ * These functions support GRANT/REVOKE operations across different database objects.
+ */
+import type { PrivilegeProps } from "./base.privilege-diff.ts";
+/**
+ * Formats a list of privileges for use in GRANT/REVOKE statements.
+ * If the list represents all privileges, returns "ALL", otherwise returns a comma-separated list.
+ *
+ * @param kind - The PostgreSQL object kind
+ * @param list - Array of privilege names to format
+ * @param version - The PostgreSQL version number
+ * @returns A SQL-formatted privilege list (either "ALL" or "PRIV1, PRIV2, ...")
+ */
+export declare function formatObjectPrivilegeList(kind: string, list: string[], version: number | undefined): string;
+/**
+ * Gets the SQL keyword prefix for a given object kind in GRANT/REVOKE statements.
+ *
+ * @param objectKind - The PostgreSQL object kind
+ * @returns The SQL prefix (e.g., "ON SCHEMA", "ON DOMAIN", "ON")
+ */
+export declare function getObjectKindPrefix(objectKind: string): string;
+export declare function normalizePrivileges(privileges: PrivilegeProps[]): {
+    grantee: string;
+    privilege: string;
+    grantable: boolean;
+}[];