@supabase/pg-delta 1.0.0-alpha.4 → 1.0.0-alpha.6

package/src/core/export/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Declarative schema export.
+ */
+
+import type { Change } from "../change.types.ts";
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.ts";
+import type { Integration } from "../integrations/integration.types.ts";
+import type { createPlan } from "../plan/create.ts";
+import { DEFAULT_OPTIONS } from "../plan/sql-format/constants.ts";
+import type { SqlFormatOptions } from "../plan/sql-format/types.ts";
+import { formatSqlScript } from "../plan/statements.ts";
+import { createFileMapper } from "./file-mapper.ts";
+import { groupChangesByFile } from "./grouper.ts";
+import type { DeclarativeSchemaOutput, FileEntry, Grouping } from "./types.ts";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * The result of createPlan, containing the plan, sorted changes, and context.
+ * Use this type when you have already confirmed createPlan returned non-null.
+ */
+type PlanResult = NonNullable<Awaited<ReturnType<typeof createPlan>>>;
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export interface ExportOptions {
+  /** Integration for custom serialization */
+  integration?: Integration;
+  /**
+   * SQL formatter options to control the output style.
+   * Merged on top of the default export options (maxWidth: 180, keywordCase: "upper").
+   * See `SqlFormatOptions` for available keys.
+   */
+  formatOptions?: SqlFormatOptions | null;
+  /**
+   * Group entities by name prefix into consolidated files or subdirectories.
+   * Supports automatic partition detection and/or explicit prefix lists.
+   */
+  grouping?: Grouping;
+  /** Callback for non-fatal warnings (e.g. invalid grouping regex patterns). */
+  onWarning?: (message: string) => void;
+}
+
+/**
+ * Export a declarative schema from a plan result.
+ *
+ * Takes the output of `createPlan()` and generates a declarative schema output
+ * with files grouped by object type. Drop operations are excluded since
+ * declarative mode targets the final desired state.
+ *
+ * Dependency-based filtering (cascading exclusions) is handled by `createPlan`,
+ * so this function only needs to filter out drop operations.
+ *
+ * @param planResult - The result from createPlan() containing plan, sortedChanges, and ctx
+ * @param options - Optional integration for custom serialization
+ * @returns Declarative schema output with grouped files
+ */
+export function exportDeclarativeSchema(
+  planResult: PlanResult,
+  options?: ExportOptions,
+): DeclarativeSchemaOutput {
+  const { ctx, sortedChanges } = planResult;
+  const integration = options?.integration;
+  const formatOptions: SqlFormatOptions | undefined =
+    options?.formatOptions === null
+      ? undefined
+      : {
+          ...DEFAULT_OPTIONS,
+          maxWidth: 180,
+          keywordCase: "upper",
+          ...options?.formatOptions,
+        };
+
+  // Drop filtering and dependency cascading are handled upstream by createPlan.
+
+  const { hash: sourceFingerprint, stableIds } = buildPlanScopeFingerprint(
+    ctx.mainCatalog,
+    sortedChanges,
+  );
+  const targetFingerprint = hashStableIds(ctx.branchCatalog, stableIds);
+
+  const mapper = createFileMapper(options?.grouping, options?.onWarning);
+  const groups = groupChangesByFile(sortedChanges, mapper);
+  const files = groups.map((group, index) => {
+    const statements = group.changes.map((change) =>
+      serializeChange(change, integration),
+    );
+    return buildFileEntry(
+      group.path,
+      group.metadata,
+      statements,
+      index,
+      formatOptions,
+    );
+  });
+
+  return {
+    version: 1,
+    mode: "declarative",
+    generatedAt: new Date().toISOString(),
+    source: { fingerprint: sourceFingerprint },
+    target: { fingerprint: targetFingerprint },
+    files,
+  };
+}
+
+function serializeChange(change: Change, integration?: Integration): string {
+  return integration?.serialize?.(change) ?? change.serialize();
+}
+
+function buildFileEntry(
+  path: string,
+  metadata: FileEntry["metadata"],
+  statements: string[],
+  order: number,
+  formatOptions?: SqlFormatOptions,
+): FileEntry {
+  return {
+    path,
+    order,
+    statements: statements.length,
+    sql: formatSqlScript(statements, formatOptions),
+    metadata,
+  };
+}

package/src/core/export/types.ts

@@ -0,0 +1,104 @@
+/**
+ * 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,
+} as const;
+
+export type FileCategory = keyof typeof CATEGORY_PRIORITY;
+
+// ============================================================================
+// Output Types
+// ============================================================================
+
+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[];
+}
+
+// ============================================================================
+// Entity Grouping
+// ============================================================================
+
+/** 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[];
+}
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+export interface FilePath {
+  path: string;
+  category: FileCategory;
+  metadata: FileMetadata;
+}

package/src/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"
+    }
+  ]
+}