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

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

@@ -0,0 +1,84 @@
+/**
+ * Type definitions for declarative schema export.
+ */
+export declare const CATEGORY_PRIORITY: {
+    readonly cluster: 0;
+    readonly schema: 1;
+    readonly extensions: 2;
+    readonly types: 3;
+    readonly sequences: 4;
+    readonly tables: 5;
+    readonly foreign_tables: 6;
+    readonly views: 7;
+    readonly matviews: 8;
+    readonly functions: 9;
+    readonly procedures: 10;
+    readonly aggregates: 11;
+    readonly domains: 12;
+    readonly collations: 13;
+    readonly publications: 14;
+    readonly subscriptions: 15;
+    readonly event_triggers: 16;
+};
+export type FileCategory = keyof typeof CATEGORY_PRIORITY;
+export interface FileMetadata {
+    objectType: string;
+    schemaName?: string;
+    objectName?: string;
+}
+export interface FileEntry {
+    path: string;
+    order: number;
+    statements: number;
+    sql: string;
+    metadata: FileMetadata;
+}
+export interface DeclarativeSchemaOutput {
+    version: 1;
+    mode: "declarative";
+    generatedAt: string;
+    source: {
+        fingerprint: string;
+    };
+    target: {
+        fingerprint: string;
+    };
+    files: FileEntry[];
+}
+/** A regex pattern with a group name used as the directory or file name. */
+export interface GroupingPattern {
+    /** Regex to test against the object name. Strings are compiled to RegExp. */
+    pattern: string | RegExp;
+    /** Group name used as the directory or file name. */
+    name: string;
+}
+export interface Grouping {
+    /** How grouped entities are organized on disk. */
+    mode: "single-file" | "subdirectory";
+    /**
+     * Regex-based patterns to match object names.
+     * First matching pattern wins -- ordering controls priority.
+     *
+     * Examples:
+     * - `{ pattern: /^project/, name: "project" }`  – prefix
+     * - `{ pattern: /organization/, name: "organization" }` – contains
+     * - `{ pattern: /tokens$/, name: "tokens" }` – suffix
+     */
+    groupPatterns?: GroupingPattern[];
+    /**
+     * Automatically detect partitioned tables and group partitions with
+     * their parent table.  Defaults to `true`.
+     */
+    autoGroupPartitions?: boolean;
+    /**
+     * Schemas to flatten: all objects are merged into one file per category.
+     * e.g. `schemas/partman/tables.sql` instead of `schemas/partman/tables/foo.sql`.
+     * Useful for small or extension schemas that don't need per-object files.
+     */
+    flatSchemas?: string[];
+}
+export interface FilePath {
+    path: string;
+    category: FileCategory;
+    metadata: FileMetadata;
+}

package/dist/core/export/types.js

@@ -0,0 +1,25 @@
+/**
+ * Type definitions for declarative schema export.
+ */
+// ============================================================================
+// File Categories
+// ============================================================================
+export const CATEGORY_PRIORITY = {
+    cluster: 0,
+    schema: 1,
+    extensions: 2,
+    types: 3,
+    sequences: 4,
+    tables: 5,
+    foreign_tables: 6,
+    views: 7,
+    matviews: 8,
+    functions: 9,
+    procedures: 10,
+    aggregates: 11,
+    domains: 12,
+    collations: 13,
+    publications: 14,
+    subscriptions: 15,
+    event_triggers: 16,
+};

package/dist/core/fixtures/empty-catalogs/postgres-15-16-baseline.json

@@ -0,0 +1,287 @@
+{
+    "version": 150014,
+    "currentUser": "postgres",
+    "aggregates": {},
+    "collations": {},
+    "compositeTypes": {},
+    "domains": {},
+    "enums": {},
+    "extensions": {
+        "extension:plpgsql": {
+            "name": "plpgsql",
+            "schema": "pg_catalog",
+            "relocatable": false,
+            "version": "1.0",
+            "owner": "postgres",
+            "comment": "PL/pgSQL procedural language",
+            "members": [
+                "procedure:pg_catalog.plpgsql_call_handler()",
+                "procedure:pg_catalog.plpgsql_inline_handler(internal)",
+                "procedure:pg_catalog.plpgsql_validator(oid)"
+            ]
+        }
+    },
+    "procedures": {},
+    "indexes": {},
+    "materializedViews": {},
+    "subscriptions": {},
+    "publications": {},
+    "rlsPolicies": {},
+    "roles": {
+        "role:postgres": {
+            "name": "postgres",
+            "is_superuser": true,
+            "can_inherit": true,
+            "can_create_roles": true,
+            "can_create_databases": true,
+            "can_login": true,
+            "can_replicate": true,
+            "connection_limit": -1,
+            "can_bypass_rls": true,
+            "config": null,
+            "comment": null,
+            "members": [],
+            "default_privileges": [
+                {
+                    "in_schema": null,
+                    "objtype": "S",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "T",
+                    "grantee": "PUBLIC",
+                    "privileges": [
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "T",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "f",
+                    "grantee": "PUBLIC",
+                    "privileges": [
+                        {
+                            "privilege": "EXECUTE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "f",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "EXECUTE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "n",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "CREATE",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "r",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "DELETE",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "INSERT",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "REFERENCES",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "SELECT",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "TRIGGER",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "TRUNCATE",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "UPDATE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                }
+            ]
+        }
+    },
+    "schemas": {
+        "schema:public": {
+            "name": "public",
+            "owner": "pg_database_owner",
+            "comment": "standard public schema",
+            "privileges": [
+                {
+                    "grantee": "PUBLIC",
+                    "privilege": "USAGE",
+                    "grantable": false
+                },
+                {
+                    "grantee": "pg_database_owner",
+                    "privilege": "CREATE",
+                    "grantable": false
+                },
+                {
+                    "grantee": "pg_database_owner",
+                    "privilege": "USAGE",
+                    "grantable": false
+                }
+            ]
+        }
+    },
+    "sequences": {},
+    "tables": {},
+    "triggers": {},
+    "eventTriggers": {},
+    "rules": {},
+    "ranges": {},
+    "views": {},
+    "foreignDataWrappers": {},
+    "servers": {},
+    "userMappings": {},
+    "foreignTables": {},
+    "depends": [
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:pg_database_owner",
+            "referenced_stable_id": "role:pg_database_owner",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:pg_database_owner",
+            "referenced_stable_id": "schema:public",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:PUBLIC",
+            "referenced_stable_id": "role:PUBLIC",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:PUBLIC",
+            "referenced_stable_id": "schema:public",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "comment:extension:plpgsql",
+            "referenced_stable_id": "extension:plpgsql",
+            "deptype": "a"
+        },
+        {
+            "dependent_stable_id": "comment:language:plpgsql",
+            "referenced_stable_id": "language:plpgsql",
+            "deptype": "a"
+        },
+        {
+            "dependent_stable_id": "comment:language:sql",
+            "referenced_stable_id": "language:sql",
+            "deptype": "a"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "procedure:pg_catalog.plpgsql_call_handler()",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "procedure:pg_catalog.plpgsql_inline_handler(internal)",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "procedure:pg_catalog.plpgsql_validator(oid)",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "role:postgres",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_settings->pg_monitor",
+            "referenced_stable_id": "role:pg_monitor",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_settings->pg_monitor",
+            "referenced_stable_id": "role:pg_read_all_settings",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_stats->pg_monitor",
+            "referenced_stable_id": "role:pg_monitor",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_stats->pg_monitor",
+            "referenced_stable_id": "role:pg_read_all_stats",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_stat_scan_tables->pg_monitor",
+            "referenced_stable_id": "role:pg_monitor",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_stat_scan_tables->pg_monitor",
+            "referenced_stable_id": "role:pg_stat_scan_tables",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "schema:public",
+            "referenced_stable_id": "role:pg_database_owner",
+            "deptype": "n"
+        }
+    ]
+}

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

@@ -19,12 +19,40 @@ type ExtractedProperties = {
     schema?: string | string[];
     owner?: string | string[];
     member?: string | string[];
+    grantee?: string | string[];
+    publication?: string | string[];
+    extension?: string | string[];
+    procedureLanguage?: string | string[];
+    eventTriggerName?: string | string[];
+    procedureBinaryPath?: string | string[];
+    triggerFunctionSchema?: string | string[];
+};
+/**
+ * Special properties that use custom matching logic (not extractor-based).
+ */
+type SpecialProperties = {
+    /**
+     * Prefix match on `change.requires`.
+     * Matches when any element of `change.requires` starts with any of the given prefixes.
+     * Useful for excluding changes that depend on specific schemas/types.
+     *
+     * @example Filter out changes that require auth or extensions types:
+     * ```ts
+     * { not: { requiresMatching: ["type:auth.", "type:extensions."] } }
+     * ```
+     */
+    requiresMatching?: string[];
 };
 /**
  * Property pattern - matches against change properties.
  * Multiple properties are combined with AND (all must match).
  */
-type PropertyPattern = CoreProperties & ExtractedProperties & {
+type PropertyPattern = CoreProperties & ExtractedProperties & SpecialProperties & {
+    /**
+     * When true, exclusions from this filter cascade to dependents (requires/pg_depend).
+     * Default false for DSL filters (opt-in).
+     */
+    cascade?: boolean;
     and?: never;
     or?: never;
     not?: never;
@@ -35,28 +63,37 @@ type PropertyPattern = CoreProperties & ExtractedProperties & {
  */
 type CompositionPattern = ({
     and: FilterPattern[];
+    cascade?: boolean;
     or?: never;
     not?: never;
 } & {
     [K in keyof CoreProperties]?: never;
 } & {
     [K in keyof ExtractedProperties]?: never;
+} & {
+    [K in keyof SpecialProperties]?: never;
 }) | ({
     or: FilterPattern[];
+    cascade?: boolean;
     and?: never;
     not?: never;
 } & {
     [K in keyof CoreProperties]?: never;
 } & {
     [K in keyof ExtractedProperties]?: never;
+} & {
+    [K in keyof SpecialProperties]?: never;
 }) | ({
     not: FilterPattern;
+    cascade?: boolean;
     and?: never;
     or?: never;
 } & {
     [K in keyof CoreProperties]?: never;
 } & {
     [K in keyof ExtractedProperties]?: never;
+} & {
+    [K in keyof SpecialProperties]?: never;
 });
 /**
  * Filter pattern DSL.

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

@@ -43,10 +43,28 @@ export function evaluatePattern(pattern, change) {
             return false;
         }
     }
+    // Match requiresMatching (special property - prefix match on change.requires)
+    if (pattern.requiresMatching) {
+        const requires = change.requires ?? [];
+        const prefixes = pattern.requiresMatching;
+        const hasMatch = requires.some((r) => prefixes.some((p) => r.startsWith(p)));
+        if (!hasMatch) {
+            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)) {
+        // Skip composition operators, core properties, special properties, and cascade
+        if ([
+            "and",
+            "or",
+            "not",
+            "type",
+            "operation",
+            "scope",
+            "requiresMatching",
+            "cascade",
+        ].includes(key)) {
             continue;
         }
         // Check if this is a registered property extractor

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

@@ -11,6 +11,48 @@ export const PROPERTY_EXTRACTORS = {
         }
         return null;
     },
+    grantee: (change) => {
+        if (change.scope === "privilege" && "grantee" in change) {
+            return change.grantee;
+        }
+        return null;
+    },
+    publication: (change) => {
+        if (change.objectType === "publication") {
+            return change.publication.name;
+        }
+        return null;
+    },
+    extension: (change) => {
+        if (change.objectType === "extension") {
+            return change.extension.name;
+        }
+        return null;
+    },
+    procedureLanguage: (change) => {
+        if (change.objectType === "procedure") {
+            return change.procedure.language;
+        }
+        return null;
+    },
+    eventTriggerName: (change) => {
+        if (change.objectType === "event_trigger") {
+            return change.eventTrigger.name;
+        }
+        return null;
+    },
+    procedureBinaryPath: (change) => {
+        if (change.objectType === "procedure") {
+            return change.procedure.binary_path ?? null;
+        }
+        return null;
+    },
+    triggerFunctionSchema: (change) => {
+        if (change.objectType === "trigger") {
+            return change.trigger.function_schema;
+        }
+        return null;
+    },
 };
 export function getSchema(change) {
     switch (change.objectType) {

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

@@ -3,6 +3,7 @@
  *
  * Combines filter and serialization DSLs into a single serializable structure.
  */
+import type { CatalogSnapshot } from "../catalog.snapshot.ts";
 import type { FilterDSL } from "./filter/dsl.ts";
 import type { SerializeDSL } from "./serialize/dsl.ts";
 /**
@@ -19,4 +20,13 @@ export type IntegrationDSL = {
      * If not provided, changes are serialized with default options.
      */
     serialize?: SerializeDSL;
+    /**
+     * Baseline catalog snapshot for this integration.
+     *
+     * When `--source` is omitted, this snapshot is deserialized and used as the
+     * source catalog instead of `createEmptyCatalog`. This lets integrations
+     * define what "empty" means for their platform (e.g. Supabase ships with
+     * pre-existing schemas, extensions, and roles).
+     */
+    emptyCatalog?: CatalogSnapshot;
 };

package/dist/core/integrations/supabase.d.ts

@@ -7,4 +7,12 @@
  * - Skips authorization for schema creates owned by Supabase system roles
  */
 import type { IntegrationDSL } from "./integration-dsl.ts";
+/**
+ * To generate the emptyCatalog snapshot, run catalog-export against a fresh
+ * supabase/postgres container:
+ *
+ *   pgdelta catalog-export --target postgres://postgres:postgres@localhost:54322/postgres --output supabase-baseline.json
+ *
+ * Then import and assign the JSON content to the emptyCatalog field below.
+ */
 export declare const supabase: IntegrationDSL;

package/dist/core/integrations/supabase.js

@@ -53,7 +53,16 @@ const SUPABASE_SYSTEM_ROLES = [
     "supabase_storage_admin",
     "supabase_superuser",
 ];
+/**
+ * To generate the emptyCatalog snapshot, run catalog-export against a fresh
+ * supabase/postgres container:
+ *
+ *   pgdelta catalog-export --target postgres://postgres:postgres@localhost:54322/postgres --output supabase-baseline.json
+ *
+ * Then import and assign the JSON content to the emptyCatalog field below.
+ */
 export const supabase = {
+    // TODO: emptyCatalog: undefined -- populate by running catalog-export on a clean Supabase container
     filter: {
         or: [
             {

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

@@ -1,10 +1,4 @@
-import type { DefaultPrivilegeState } from "../base.default-privileges.ts";
-import type { Role } from "../role/role.model.ts";
+import type { ObjectDiffContext } from "../diff-context.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[];
+export declare function diffAggregates(ctx: Pick<ObjectDiffContext, "version" | "currentUser" | "defaultPrivilegeState">, main: Record<string, Aggregate>, branch: Record<string, Aggregate>): AggregateChange[];