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

package/dist/core/integrations/filter/dsl.js

@@ -0,0 +1,107 @@
+/**
+ * Filter DSL - A serializable domain-specific language for change filtering.
+ */
+import { PROPERTY_EXTRACTORS } from "./extractors.js";
+/**
+ * Evaluate a pattern against a change.
+ *
+ * @param pattern - The pattern to evaluate
+ * @param change - The change to match against
+ * @returns true if the pattern matches, false otherwise
+ */
+export function evaluatePattern(pattern, change) {
+    // Handle composition operators first (they take precedence)
+    // NOT operator - negate the result
+    if (pattern.not) {
+        return !evaluatePattern(pattern.not, change);
+    }
+    // AND operator - all patterns must match
+    if (pattern.and) {
+        return pattern.and.every((p) => evaluatePattern(p, change));
+    }
+    // OR operator - any pattern must match
+    if (pattern.or) {
+        return pattern.or.some((p) => evaluatePattern(p, change));
+    }
+    // Evaluate basic pattern matching
+    // Multiple properties in a pattern are combined with AND (all must match)
+    // Match objectType
+    if (pattern.type) {
+        if (change.objectType !== pattern.type) {
+            return false;
+        }
+    }
+    // Match operation
+    if (pattern.operation) {
+        if (change.operation !== pattern.operation) {
+            return false;
+        }
+    }
+    // Match scope
+    if (pattern.scope) {
+        if (change.scope !== pattern.scope) {
+            return false;
+        }
+    }
+    // Match extracted properties
+    for (const [key, value] of Object.entries(pattern)) {
+        // Skip composition operators and core properties
+        if (["and", "or", "not", "type", "operation", "scope"].includes(key)) {
+            continue;
+        }
+        // Check if this is a registered property extractor
+        const extractor = PROPERTY_EXTRACTORS[key];
+        if (!extractor) {
+            // Unknown property - ignore
+            continue;
+        }
+        // Extract the actual value from the change
+        const actualValue = extractor(change);
+        // Property matching rules:
+        // - String value: exact match
+        // - Array value: value must be in array
+        // - Missing properties (null) don't match
+        if (actualValue === null) {
+            return false;
+        }
+        if (typeof value === "string") {
+            // Exact match
+            if (actualValue !== value) {
+                return false;
+            }
+        }
+        else if (Array.isArray(value)) {
+            // Value must be in array
+            if (!value.includes(actualValue)) {
+                return false;
+            }
+        }
+        else {
+            // Invalid value type - don't match
+            return false;
+        }
+    }
+    // All checks passed
+    return true;
+}
+/**
+ * Compile a Filter DSL to a ChangeFilter function.
+ *
+ * @param dsl - The filter DSL pattern
+ * @returns A ChangeFilter function that evaluates the pattern
+ *
+ * @example
+ * ```ts
+ * const filter = compileFilterDSL({
+ *   or: [
+ *     { type: "schema", operation: "create" },
+ *     { schema: "public" }
+ *   ]
+ * });
+ * ```
+ */
+export function compileFilterDSL(dsl) {
+    return (change) => {
+        return evaluatePattern(dsl, change);
+    };
+}

package/dist/core/integrations/filter/extractors.d.ts

@@ -0,0 +1,12 @@
+import type { Change } from "../../change.types.ts";
+/**
+ * Property extractor function that extracts a value from a change.
+ */
+type PropertyExtractor = (change: Change) => string | null;
+/**
+ * Registry of property extractors.
+ * Maps property names to extractor functions.
+ */
+export declare const PROPERTY_EXTRACTORS: Record<string, PropertyExtractor>;
+export declare function getSchema(change: Change): string | null;
+export {};

package/dist/core/integrations/filter/extractors.js

@@ -0,0 +1,136 @@
+/**
+ * Registry of property extractors.
+ * Maps property names to extractor functions.
+ */
+export const PROPERTY_EXTRACTORS = {
+    schema: getSchema,
+    owner: getOwner,
+    member: (change) => {
+        if (change.scope === "membership") {
+            return change.member;
+        }
+        return null;
+    },
+};
+export function getSchema(change) {
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.schema;
+        case "collation":
+            return change.collation.schema;
+        case "composite_type":
+            return change.compositeType.schema;
+        case "domain":
+            return change.domain.schema;
+        case "enum":
+            return change.enum.schema;
+        case "event_trigger":
+            return null;
+        case "extension":
+            return change.extension.schema;
+        case "index":
+            return change.index.schema;
+        case "language":
+            return null;
+        case "materialized_view":
+            return change.materializedView.schema;
+        case "procedure":
+            return change.procedure.schema;
+        case "publication":
+            return null;
+        case "range":
+            return change.range.schema;
+        case "rls_policy":
+            return change.policy.schema;
+        case "role":
+            return null;
+        case "rule":
+            return change.rule.schema;
+        case "schema":
+            return change.schema.name;
+        case "sequence":
+            return change.sequence.schema;
+        case "subscription":
+            return null;
+        case "table":
+            return change.table.schema;
+        case "trigger":
+            return change.trigger.schema;
+        case "view":
+            return change.view.schema;
+        case "foreign_data_wrapper":
+            return null;
+        case "server":
+            return null;
+        case "user_mapping":
+            return null;
+        case "foreign_table":
+            return change.foreignTable.schema;
+        default: {
+            // exhaustiveness check
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}
+function getOwner(change) {
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.owner;
+        case "collation":
+            return change.collation.owner;
+        case "composite_type":
+            return change.compositeType.owner;
+        case "domain":
+            return change.domain.owner;
+        case "enum":
+            return change.enum.owner;
+        case "event_trigger":
+            return change.eventTrigger.owner;
+        case "extension":
+            return change.extension.owner;
+        case "index":
+            return change.index.owner;
+        case "language":
+            return change.language.owner;
+        case "materialized_view":
+            return change.materializedView.owner;
+        case "procedure":
+            return change.procedure.owner;
+        case "publication":
+            return change.publication.owner;
+        case "range":
+            return change.range.owner;
+        case "rls_policy":
+            return change.policy.owner;
+        case "role":
+            return change.role.name;
+        case "rule":
+            return change.rule.owner;
+        case "schema":
+            return change.schema.owner;
+        case "sequence":
+            return change.sequence.owner;
+        case "subscription":
+            return change.subscription.owner;
+        case "table":
+            return change.table.owner;
+        case "trigger":
+            return change.trigger.owner;
+        case "view":
+            return change.view.owner;
+        case "foreign_data_wrapper":
+            return change.foreignDataWrapper.owner;
+        case "server":
+            return change.server.owner;
+        case "user_mapping":
+            return null;
+        case "foreign_table":
+            return change.foreignTable.owner;
+        default: {
+            // exhaustiveness check
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}

package/dist/core/integrations/integration-dsl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Integration DSL - A serializable domain-specific language for integrations.
+ *
+ * Combines filter and serialization DSLs into a single serializable structure.
+ */
+import type { FilterDSL } from "./filter/dsl.ts";
+import type { SerializeDSL } from "./serialize/dsl.ts";
+/**
+ * Integration DSL - serializable representation of an integration.
+ */
+export type IntegrationDSL = {
+    /**
+     * Filter DSL - determines which changes to include/exclude.
+     * If not provided, all changes are included.
+     */
+    filter?: FilterDSL;
+    /**
+     * Serialization DSL - customizes how changes are serialized.
+     * If not provided, changes are serialized with default options.
+     */
+    serialize?: SerializeDSL;
+};

package/dist/core/integrations/integration-dsl.js

@@ -0,0 +1,6 @@
+/**
+ * Integration DSL - A serializable domain-specific language for integrations.
+ *
+ * Combines filter and serialization DSLs into a single serializable structure.
+ */
+export {};

package/dist/core/integrations/integration.types.d.ts

@@ -0,0 +1,5 @@
+import type { ChangeFilter, ChangeSerializer } from "../main.ts";
+export type Integration = {
+    filter?: ChangeFilter;
+    serialize?: ChangeSerializer;
+};

package/dist/core/integrations/integration.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/integrations/serialize/dsl.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Serialization DSL - A serializable domain-specific language for customizing change serialization.
+ *
+ * Reuses the filter pattern matching logic to determine when to apply serialization options.
+ */
+import type { ChangeSerializer } from "../../main.ts";
+import { type FilterPattern } from "../filter/dsl.ts";
+/**
+ * Serialization options that can be passed to change.serialize().
+ */
+type SerializeOptions = {
+    skipAuthorization?: boolean;
+    [key: string]: unknown;
+};
+/**
+ * A serialization rule that applies options when a pattern matches.
+ */
+type SerializeRule = {
+    /**
+     * Pattern to match against changes.
+     * Uses the same pattern matching logic as filters.
+     */
+    when: FilterPattern;
+    /**
+     * Serialization options to apply when the pattern matches.
+     */
+    options: SerializeOptions;
+};
+/**
+ * Serialization DSL - array of rules evaluated in order.
+ * First matching rule's options are applied.
+ */
+export type SerializeDSL = SerializeRule[];
+/**
+ * Compile a Serialization DSL to a ChangeSerializer function.
+ *
+ * Rules are evaluated in order, and the first matching rule's options are applied.
+ * If no rule matches, the change is serialized with default options.
+ *
+ * @param dsl - The serialization DSL
+ * @returns A ChangeSerializer function that applies the rules
+ *
+ * @example
+ * ```ts
+ * const serializer = compileSerializeDSL([
+ *   {
+ *     when: {
+ *       type: "schema",
+ *       operation: "create",
+ *       owner: ["service_role"]
+ *     },
+ *     options: { skipAuthorization: true }
+ *   }
+ * ]);
+ * ```
+ */
+export declare function compileSerializeDSL(dsl: SerializeDSL): ChangeSerializer;
+export {};

package/dist/core/integrations/serialize/dsl.js

@@ -0,0 +1,42 @@
+/**
+ * Serialization DSL - A serializable domain-specific language for customizing change serialization.
+ *
+ * Reuses the filter pattern matching logic to determine when to apply serialization options.
+ */
+import { evaluatePattern } from "../filter/dsl.js";
+/**
+ * Compile a Serialization DSL to a ChangeSerializer function.
+ *
+ * Rules are evaluated in order, and the first matching rule's options are applied.
+ * If no rule matches, the change is serialized with default options.
+ *
+ * @param dsl - The serialization DSL
+ * @returns A ChangeSerializer function that applies the rules
+ *
+ * @example
+ * ```ts
+ * const serializer = compileSerializeDSL([
+ *   {
+ *     when: {
+ *       type: "schema",
+ *       operation: "create",
+ *       owner: ["service_role"]
+ *     },
+ *     options: { skipAuthorization: true }
+ *   }
+ * ]);
+ * ```
+ */
+export function compileSerializeDSL(dsl) {
+    return (change) => {
+        // Find first matching rule
+        for (const rule of dsl) {
+            if (evaluatePattern(rule.when, change)) {
+                // Apply this rule's options
+                return change.serialize(rule.options);
+            }
+        }
+        // No rule matched - use default serialization
+        return change.serialize();
+    };
+}

package/dist/core/main.d.ts

@@ -0,0 +1,5 @@
+import type { Change } from "./change.types.ts";
+import type { Integration } from "./integrations/integration.types.ts";
+export type ChangeFilter = (change: Change) => boolean;
+export type ChangeSerializer = (change: Change) => string | undefined;
+export type MainOptions = Integration;

package/dist/core/main.js

@@ -0,0 +1,44 @@
+import postgres from "postgres";
+import { diffCatalogs } from "./catalog.diff.js";
+import { extractCatalog } from "./catalog.model.js";
+import { postgresConfig } from "./postgres-config.js";
+import { sortChanges } from "./sort/sort-changes.js";
+async function _main(mainDatabaseUrl, branchDatabaseUrl, options = {}) {
+    const mainSql = postgres(mainDatabaseUrl, postgresConfig);
+    const branchSql = postgres(branchDatabaseUrl, postgresConfig);
+    const [mainCatalog, branchCatalog] = await Promise.all([
+        extractCatalog(mainSql),
+        extractCatalog(branchSql),
+    ]);
+    await Promise.all([mainSql.end(), branchSql.end()]);
+    const changes = diffCatalogs(mainCatalog, branchCatalog);
+    // Use provided options as integration (optional)
+    const integration = options ?? {};
+    // Apply filter if provided
+    const ctx = { mainCatalog, branchCatalog };
+    let filteredChanges = changes;
+    const integrationFilter = integration.filter;
+    if (integrationFilter) {
+        filteredChanges = filteredChanges.filter((change) => integrationFilter(change));
+    }
+    if (filteredChanges.length === 0) {
+        return null;
+    }
+    const sortedChanges = sortChanges(ctx, filteredChanges);
+    const hasRoutineChanges = sortedChanges.some((change) => change.objectType === "procedure" || change.objectType === "aggregate");
+    const sessionConfig = hasRoutineChanges
+        ? ["SET check_function_bodies = false"]
+        : [];
+    // Build migration script
+    const scriptParts = [];
+    scriptParts.push(...sessionConfig);
+    // Serialize changes using integration serialize hook (applies masking) or fallback
+    const changeStatements = sortedChanges.map((change) => {
+        return integration.serialize?.(change) ?? change.serialize();
+    });
+    scriptParts.push(...changeStatements);
+    const migrationScript = `${scriptParts.join(";\n\n")};`;
+    return {
+        migrationScript,
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { DefaultPrivilegeState } from "../base.default-privileges.ts";
+import type { Role } from "../role/role.model.ts";
+import type { Aggregate } from "./aggregate.model.ts";
+import type { AggregateChange } from "./changes/aggregate.types.ts";
+export declare function diffAggregates(ctx: {
+    version: number;
+    currentUser: string;
+    defaultPrivilegeState: DefaultPrivilegeState;
+    mainRoles: Record<string, Role>;
+}, main: Record<string, Aggregate>, branch: Record<string, Aggregate>): AggregateChange[];

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

@@ -0,0 +1,186 @@
+import { diffObjects } from "../base.diff.js";
+import { diffPrivileges, filterPublicBuiltInDefaults, groupPrivilegesByGrantable, } from "../base.privilege-diff.js";
+import { deepEqual, hasNonAlterableChanges } from "../utils.js";
+import { AlterAggregateChangeOwner } from "./changes/aggregate.alter.js";
+import { CreateCommentOnAggregate, DropCommentOnAggregate, } from "./changes/aggregate.comment.js";
+import { CreateAggregate } from "./changes/aggregate.create.js";
+import { DropAggregate } from "./changes/aggregate.drop.js";
+import { GrantAggregatePrivileges, RevokeAggregatePrivileges, RevokeGrantOptionAggregatePrivileges, } from "./changes/aggregate.privilege.js";
+export function diffAggregates(ctx, main, branch) {
+    const { created, dropped, altered } = diffObjects(main, branch);
+    const changes = [];
+    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 ?? "");
+        // 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(effectiveDefaults, desiredPrivileges, aggregate.owner, ctx.mainRoles);
+        // Generate grant changes
+        for (const [grantee, result] of privilegeResults) {
+            if (result.grants.length > 0) {
+                const grantGroups = groupPrivilegesByGrantable(result.grants);
+                for (const [, list] of grantGroups) {
+                    changes.push(new GrantAggregatePrivileges({
+                        aggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke changes
+            if (result.revokes.length > 0) {
+                const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+                for (const [, list] of revokeGroups) {
+                    changes.push(new RevokeAggregatePrivileges({
+                        aggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke grant option changes
+            if (result.revokeGrantOption.length > 0) {
+                changes.push(new RevokeGrantOptionAggregatePrivileges({
+                    aggregate,
+                    grantee,
+                    privilegeNames: result.revokeGrantOption,
+                    version: ctx.version,
+                }));
+            }
+        }
+    }
+    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 = [
+            "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, ctx.mainRoles);
+        for (const [grantee, result] of privilegeResults) {
+            if (result.grants.length > 0) {
+                const grantGroups = groupPrivilegesByGrantable(result.grants);
+                for (const [, list] of grantGroups) {
+                    changes.push(new GrantAggregatePrivileges({
+                        aggregate: branchAggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            if (result.revokes.length > 0) {
+                const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+                for (const [, list] of revokeGroups) {
+                    changes.push(new RevokeAggregatePrivileges({
+                        aggregate: mainAggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            if (result.revokeGrantOption.length > 0) {
+                changes.push(new RevokeGrantOptionAggregatePrivileges({
+                    aggregate: mainAggregate,
+                    grantee,
+                    privilegeNames: result.revokeGrantOption,
+                    version: ctx.version,
+                }));
+            }
+        }
+    }
+    return changes;
+}