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

package/dist/core/plan/serialize.js

@@ -0,0 +1,176 @@
+/**
+ * Helpers for extracting object info from Change objects.
+ */
+/**
+ * Get the object name from a change (exhaustive).
+ */
+export function getObjectName(change) {
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.name;
+        case "collation":
+            return change.collation.name;
+        case "composite_type":
+            return change.compositeType.name;
+        case "domain":
+            return change.domain.name;
+        case "enum":
+            return change.enum.name;
+        case "event_trigger":
+            return change.eventTrigger.name;
+        case "extension":
+            return change.extension.name;
+        case "foreign_data_wrapper":
+            return change.foreignDataWrapper.name;
+        case "foreign_table":
+            return change.foreignTable.name;
+        case "index":
+            return change.index.name;
+        case "language":
+            return change.language.name;
+        case "materialized_view":
+            return change.materializedView.name;
+        case "procedure":
+            return change.procedure.name;
+        case "publication":
+            return change.publication.name;
+        case "range":
+            return change.range.name;
+        case "rls_policy":
+            return change.policy.name;
+        case "role":
+            return change.role.name;
+        case "rule":
+            return change.rule.name;
+        case "schema":
+            return change.schema.name;
+        case "sequence":
+            return change.sequence.name;
+        case "server":
+            return change.server.name;
+        case "subscription":
+            return change.subscription.name;
+        case "table":
+            return change.table.name;
+        case "trigger":
+            return change.trigger.name;
+        case "user_mapping":
+            return `${change.userMapping.user}@${change.userMapping.server}`;
+        case "view":
+            return change.view.name;
+        default: {
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Get the schema from a change, or null for cluster-wide objects (exhaustive).
+ */
+export function getObjectSchema(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 "foreign_data_wrapper":
+            return null;
+        case "foreign_table":
+            return change.foreignTable.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 "server":
+            return null;
+        case "subscription":
+            return null;
+        case "table":
+            return change.table.schema;
+        case "trigger":
+            return change.trigger.schema;
+        case "user_mapping":
+            return null;
+        case "view":
+            return change.view.schema;
+        default: {
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Get parent info for child objects (indexes, triggers, policies, rules).
+ * Returns null for top-level objects (exhaustive).
+ */
+export function getParentInfo(change) {
+    switch (change.objectType) {
+        case "index": {
+            // Indexes can belong to tables or materialized views
+            // Use table_relkind to determine the parent type: 'r' = table, 'm' = materialized view
+            const parentType = change.index.table_relkind === "m" ? "materialized_view" : "table";
+            return { type: parentType, name: change.index.table_name };
+        }
+        case "trigger":
+            return { type: "table", name: change.trigger.table_name };
+        case "rule":
+            return { type: "table", name: change.rule.table_name };
+        case "rls_policy":
+            return { type: "table", name: change.policy.table_name };
+        case "aggregate":
+        case "collation":
+        case "composite_type":
+        case "domain":
+        case "enum":
+        case "event_trigger":
+        case "extension":
+        case "foreign_data_wrapper":
+        case "foreign_table":
+        case "language":
+        case "materialized_view":
+        case "procedure":
+        case "publication":
+        case "range":
+        case "role":
+        case "schema":
+        case "sequence":
+        case "server":
+        case "subscription":
+        case "table":
+        case "user_mapping":
+        case "view":
+            return null;
+        default: {
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}

package/dist/core/plan/statements.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SQL script formatting utilities.
+ */
+/**
+ * Format an array of SQL statements into a single script string.
+ * Statements are joined with double newlines and the script ends with a semicolon.
+ */
+export declare function formatSqlScript(statements: string[]): string;

package/dist/core/plan/statements.js

@@ -0,0 +1,13 @@
+/**
+ * SQL script formatting utilities.
+ */
+const STATEMENT_DELIMITER = ";\n\n";
+/**
+ * Format an array of SQL statements into a single script string.
+ * Statements are joined with double newlines and the script ends with a semicolon.
+ */
+export function formatSqlScript(statements) {
+    if (statements.length === 0)
+        return "";
+    return `${statements.join(STATEMENT_DELIMITER)};`;
+}

package/dist/core/plan/types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Type definitions for the Plan module.
+ */
+import z from "zod";
+import type { Change } from "../change.types.ts";
+import type { FilterDSL } from "../integrations/filter/dsl.ts";
+import type { SerializeDSL } from "../integrations/serialize/dsl.ts";
+import type { ChangeFilter, ChangeSerializer } from "../main.ts";
+export type PlanRisk = {
+    level: "safe";
+} | {
+    level: "data_loss";
+    statements: string[];
+};
+/**
+ * All supported object types in the system.
+ * Derived from the Change union type's objectType discriminant.
+ */
+export type ObjectType = Change["objectType"];
+/**
+ * Cluster-wide object types (no schema).
+ */
+export type ClusterObjectType = Extract<ObjectType, "event_trigger" | "foreign_data_wrapper" | "language" | "publication" | "role" | "server" | "subscription" | "user_mapping">;
+/**
+ * Object types that are children of tables/views.
+ */
+export type ChildObjectType = Extract<ObjectType, "index" | "trigger" | "rule" | "rls_policy">;
+/**
+ * Parent types for child objects.
+ */
+export type ParentType = Extract<ObjectType, "table" | "view" | "materialized_view" | "foreign_table">;
+/**
+ * Change scopes - what aspect of an object is being changed.
+ * Derived from the Change union type's scope property.
+ */
+export type ChangeScope = Change["scope"];
+/**
+ * A change entry storing both serialized and original change for instanceof checks.
+ */
+export interface ChangeEntry {
+    original: Change;
+}
+/**
+ * A group of changes organized by operation.
+ */
+export interface ChangeGroup {
+    create: ChangeEntry[];
+    alter: ChangeEntry[];
+    drop: ChangeEntry[];
+}
+/**
+ * Children objects of a table/view (indexes, triggers, policies, etc.)
+ */
+export interface TableChildren {
+    changes: ChangeGroup;
+    columns: ChangeGroup;
+    indexes: ChangeGroup;
+    triggers: ChangeGroup;
+    rules: ChangeGroup;
+    policies: ChangeGroup;
+    /** Partition tables (only for partitioned tables) */
+    partitions: Record<string, TableChildren>;
+}
+/**
+ * Children objects of a materialized view
+ */
+export interface MaterializedViewChildren {
+    changes: ChangeGroup;
+    indexes: ChangeGroup;
+}
+/**
+ * Type grouping within a schema
+ */
+export interface TypeGroup {
+    enums: ChangeGroup;
+    composites: ChangeGroup;
+    ranges: ChangeGroup;
+    domains: ChangeGroup;
+}
+/**
+ * Schema-level grouping of objects
+ */
+export interface SchemaGroup {
+    changes: ChangeGroup;
+    tables: Record<string, TableChildren>;
+    views: Record<string, TableChildren>;
+    materializedViews: Record<string, MaterializedViewChildren>;
+    functions: ChangeGroup;
+    procedures: ChangeGroup;
+    aggregates: ChangeGroup;
+    sequences: ChangeGroup;
+    types: TypeGroup;
+    collations: ChangeGroup;
+    foreignTables: Record<string, TableChildren>;
+}
+/**
+ * Cluster-wide objects (no schema)
+ */
+export interface ClusterGroup {
+    roles: ChangeGroup;
+    extensions: ChangeGroup;
+    eventTriggers: ChangeGroup;
+    publications: ChangeGroup;
+    subscriptions: ChangeGroup;
+    foreignDataWrappers: ChangeGroup;
+    servers: ChangeGroup;
+    userMappings: ChangeGroup;
+}
+/**
+ * Fully hierarchical plan structure for tree display.
+ */
+export interface HierarchicalPlan {
+    cluster: ClusterGroup;
+    schemas: Record<string, SchemaGroup>;
+}
+/**
+ * Plan schema for serialization/deserialization.
+ */
+export declare const PlanSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    toolVersion: z.ZodOptional<z.ZodString>;
+    source: z.ZodObject<{
+        fingerprint: z.ZodString;
+    }, z.z.core.$strip>;
+    target: z.ZodObject<{
+        fingerprint: z.ZodString;
+    }, z.z.core.$strip>;
+    statements: z.ZodArray<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodAny>;
+    serialize: z.ZodOptional<z.ZodAny>;
+    risk: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        level: z.ZodLiteral<"safe">;
+    }, z.z.core.$strip>, z.ZodObject<{
+        level: z.ZodLiteral<"data_loss">;
+        statements: z.ZodArray<z.ZodString>;
+    }, z.z.core.$strip>], "level">>;
+}, z.z.core.$strip>;
+/**
+ * A migration plan containing all changes to transform one database schema into another.
+ */
+export type Plan = z.infer<typeof PlanSchema>;
+/**
+ * Options for creating a plan.
+ */
+export interface CreatePlanOptions {
+    /** Filter - either FilterDSL (stored in plan) or ChangeFilter function (not stored) */
+    filter?: FilterDSL | ChangeFilter;
+    /** Serialize - either SerializeDSL (stored in plan) or ChangeSerializer function (not stored) */
+    serialize?: SerializeDSL | ChangeSerializer;
+    /** Role to use when executing the migration (SET ROLE will be added to statements) */
+    role?: string;
+}

package/dist/core/plan/types.js

@@ -0,0 +1,32 @@
+/**
+ * Type definitions for the Plan module.
+ */
+import z from "zod";
+/**
+ * Plan schema for serialization/deserialization.
+ */
+export const PlanSchema = z.object({
+    version: z.number(),
+    toolVersion: z.string().optional(),
+    source: z.object({
+        fingerprint: z.string(),
+    }),
+    target: z.object({
+        fingerprint: z.string(),
+    }),
+    statements: z.array(z.string()),
+    role: z.string().optional(),
+    filter: z.any().optional(), // FilterDSL - complex recursive type, validated at compile time
+    serialize: z.any().optional(), // SerializeDSL - complex recursive type, validated at compile time
+    risk: z
+        .discriminatedUnion("level", [
+        z.object({
+            level: z.literal("safe"),
+        }),
+        z.object({
+            level: z.literal("data_loss"),
+            statements: z.array(z.string()),
+        }),
+    ])
+        .optional(),
+});

package/dist/core/postgres-config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PostgreSQL connection configuration with custom type handlers.
+ */
+import type postgres from "postgres";
+/**
+ * Custom type handler for specific corner cases.
+ */
+export declare const postgresConfig: postgres.Options<Record<string, postgres.PostgresType>>;

package/dist/core/postgres-config.js

@@ -0,0 +1,46 @@
+/**
+ * PostgreSQL connection configuration with custom type handlers.
+ */
+/**
+ * Custom type handler for specific corner cases.
+ */
+export const postgresConfig = {
+    types: {
+        int2vector: {
+            // The pg_types oid for int2vector (22 is the OID for int2vector)
+            to: 22,
+            // Array of pg_types oids to handle when parsing values coming from the db
+            from: [22],
+            // Parse int2vector from string format "1 2 3" to array [1, 2, 3]
+            parse: (value) => {
+                if (!value || value === "")
+                    return [];
+                return value
+                    .split(" ")
+                    .map(Number)
+                    .filter((n) => !Number.isNaN(n));
+            },
+            // Serialize array back to int2vector format if needed
+            serialize: (value) => {
+                if (!Array.isArray(value))
+                    return "";
+                return value.join(" ");
+            },
+        },
+        // Handle bigint values from PostgreSQL
+        bigint: {
+            // The pg_types oid for bigint (20 is the OID for int8/bigint)
+            to: 20,
+            // Array of pg_types oids to handle when parsing values coming from the db
+            from: [20],
+            // Parse bigint string to JavaScript BigInt
+            parse: (value) => {
+                return BigInt(value);
+            },
+            // Serialize BigInt back to string for PostgreSQL
+            serialize: (value) => {
+                return value.toString();
+            },
+        },
+    },
+};

package/dist/core/sort/custom-constraints.d.ts

@@ -0,0 +1,9 @@
+import type { Change } from "../change.types.ts";
+import type { Constraint } from "./types.ts";
+/**
+ * Generate Constraints from custom constraint generators.
+ *
+ * Iterates through registered generators to produce constraints.
+ * Generators should be optimized (e.g. using indexing) to avoid O(N²) complexity.
+ */
+export declare function generateCustomConstraints(changes: Change[]): Constraint[];

package/dist/core/sort/custom-constraints.js

@@ -0,0 +1,133 @@
+import { getSchema } from "../integrations/filter/extractors.js";
+import { GrantRoleDefaultPrivileges, RevokeRoleDefaultPrivileges, } from "../objects/role/changes/role.privilege.js";
+/**
+ * Maps object type names to PostgreSQL default privilege objtype codes.
+ * This mirrors the mapping in base.default-privileges.ts.
+ */
+function objectTypeToObjtype(objectType) {
+    switch (objectType) {
+        case "table":
+        case "view":
+        case "materialized_view":
+            return "r"; // 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;
+    }
+}
+/**
+ * Generate constraints to ensure ALTER DEFAULT PRIVILEGES comes before CREATE statements.
+ *
+ * Rules:
+ * - Only applies when the default privilege's schema matches the CREATE statement's schema
+ *   (or if the default privilege is global, applies to all schemas)
+ * - Only applies when the default privilege's objtype matches the CREATE statement's object type
+ * - Excludes CREATE ROLE and CREATE SCHEMA since they are dependencies
+ *   of ALTER DEFAULT PRIVILEGES and must come before it
+ *
+ * implementation: O(N) using schema/objtype indexing.
+ */
+function generateDefaultPrivilegeConstraints(changes) {
+    const constraints = [];
+    const defaultPrivilegeIndices = [];
+    // Map<objtype_code, Map<schema_name, index[]>>
+    const createsByObjTypeAndSchema = new Map();
+    // Pass 1: Index changes
+    for (let i = 0; i < changes.length; i++) {
+        const change = changes[i];
+        // Identify default privilege changes
+        if (change instanceof GrantRoleDefaultPrivileges ||
+            change instanceof RevokeRoleDefaultPrivileges) {
+            defaultPrivilegeIndices.push(i);
+            continue;
+        }
+        // Identify CREATE object changes (excluding role/schema)
+        if (change.operation === "create" &&
+            change.scope === "object" &&
+            change.objectType !== "role" &&
+            change.objectType !== "schema") {
+            const objTypeCode = objectTypeToObjtype(change.objectType);
+            if (!objTypeCode)
+                continue;
+            const schema = getSchema(change);
+            // Default privileges only apply to schema-contained objects.
+            if (schema) {
+                let schemaMap = createsByObjTypeAndSchema.get(objTypeCode);
+                if (!schemaMap) {
+                    schemaMap = new Map();
+                    createsByObjTypeAndSchema.set(objTypeCode, schemaMap);
+                }
+                let indices = schemaMap.get(schema);
+                if (!indices) {
+                    indices = [];
+                    schemaMap.set(schema, indices);
+                }
+                indices.push(i);
+            }
+        }
+    }
+    // Pass 2: Generate constraints
+    for (const privIndex of defaultPrivilegeIndices) {
+        const privChange = changes[privIndex];
+        const privSchema = privChange.inSchema;
+        const privObjType = privChange.objtype;
+        const schemaMap = createsByObjTypeAndSchema.get(privObjType);
+        if (!schemaMap)
+            continue;
+        if (privSchema === null) {
+            // Global default privilege: applies to ALL schemas
+            for (const indices of schemaMap.values()) {
+                for (const createIndex of indices) {
+                    // (No self-check needed as types differ)
+                    constraints.push({
+                        sourceChangeIndex: privIndex,
+                        targetChangeIndex: createIndex,
+                        source: "custom",
+                    });
+                }
+            }
+        }
+        else {
+            // Specific schema: applies only to that schema
+            const indices = schemaMap.get(privSchema);
+            if (indices) {
+                for (const createIndex of indices) {
+                    constraints.push({
+                        sourceChangeIndex: privIndex,
+                        targetChangeIndex: createIndex,
+                        source: "custom",
+                    });
+                }
+            }
+        }
+    }
+    return constraints;
+}
+/**
+ * All custom constraint generators.
+ */
+const customConstraintGenerators = [
+    generateDefaultPrivilegeConstraints,
+];
+/**
+ * Generate Constraints from custom constraint generators.
+ *
+ * Iterates through registered generators to produce constraints.
+ * Generators should be optimized (e.g. using indexing) to avoid O(N²) complexity.
+ */
+export function generateCustomConstraints(changes) {
+    return customConstraintGenerators.flatMap((generate) => generate(changes));
+}

package/dist/core/sort/debug-visualization.d.ts

@@ -0,0 +1,8 @@
+import type { Change } from "../change.types.ts";
+import type { Constraint, GraphData, PgDependRow } from "./types.ts";
+/**
+ * Print debug information about the dependency graph.
+ *
+ * Builds debug-only data structures (requirementSets, dependenciesByReferencedId) just-in-time.
+ */
+export declare function printDebugGraph(phaseChanges: Change[], graphData: GraphData, edges: Array<[number, number]>, dependencyRows: PgDependRow[], constraints: Constraint[]): void;