@supabase/pg-delta 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/core/catalog.snapshot.ts

@@ -0,0 +1,289 @@
+/**
+ * Catalog snapshot - full JSON-serializable representation of a Catalog.
+ *
+ * Enables catalog-export (snapshot a live DB) and catalog-import
+ * (use a snapshot as source/target for createPlan).
+ */
+
+import z from "zod";
+import { Catalog } from "./catalog.model.ts";
+import type { PgDepend } from "./depend.ts";
+import { Aggregate } from "./objects/aggregate/aggregate.model.ts";
+import { Collation } from "./objects/collation/collation.model.ts";
+import { Domain } from "./objects/domain/domain.model.ts";
+import { EventTrigger } from "./objects/event-trigger/event-trigger.model.ts";
+import { Extension } from "./objects/extension/extension.model.ts";
+import { ForeignDataWrapper } from "./objects/foreign-data-wrapper/foreign-data-wrapper/foreign-data-wrapper.model.ts";
+import { ForeignTable } from "./objects/foreign-data-wrapper/foreign-table/foreign-table.model.ts";
+import { Server } from "./objects/foreign-data-wrapper/server/server.model.ts";
+import { UserMapping } from "./objects/foreign-data-wrapper/user-mapping/user-mapping.model.ts";
+import { Index } from "./objects/index/index.model.ts";
+import { MaterializedView } from "./objects/materialized-view/materialized-view.model.ts";
+import { Procedure } from "./objects/procedure/procedure.model.ts";
+import { Publication } from "./objects/publication/publication.model.ts";
+import { RlsPolicy } from "./objects/rls-policy/rls-policy.model.ts";
+import { Role } from "./objects/role/role.model.ts";
+import { Rule } from "./objects/rule/rule.model.ts";
+import { Schema } from "./objects/schema/schema.model.ts";
+import { Sequence } from "./objects/sequence/sequence.model.ts";
+import { Subscription } from "./objects/subscription/subscription.model.ts";
+import { Table } from "./objects/table/table.model.ts";
+import { Trigger } from "./objects/trigger/trigger.model.ts";
+import { CompositeType } from "./objects/type/composite-type/composite-type.model.ts";
+import { Enum } from "./objects/type/enum/enum.model.ts";
+import { Range } from "./objects/type/range/range.model.ts";
+import { View } from "./objects/view/view.model.ts";
+
+// ============================================================================
+// CatalogSnapshot type
+// ============================================================================
+
+/**
+ * Full JSON-serializable representation of a Catalog.
+ *
+ * Every object record uses plain props objects (not class instances).
+ * `indexableObjects` is omitted -- it is reconstructed on deserialization.
+ */
+export interface CatalogSnapshot {
+  version: number;
+  currentUser: string;
+  aggregates: Record<string, Record<string, unknown>>;
+  collations: Record<string, Record<string, unknown>>;
+  compositeTypes: Record<string, Record<string, unknown>>;
+  domains: Record<string, Record<string, unknown>>;
+  enums: Record<string, Record<string, unknown>>;
+  extensions: Record<string, Record<string, unknown>>;
+  procedures: Record<string, Record<string, unknown>>;
+  indexes: Record<string, Record<string, unknown>>;
+  materializedViews: Record<string, Record<string, unknown>>;
+  subscriptions: Record<string, Record<string, unknown>>;
+  publications: Record<string, Record<string, unknown>>;
+  rlsPolicies: Record<string, Record<string, unknown>>;
+  roles: Record<string, Record<string, unknown>>;
+  schemas: Record<string, Record<string, unknown>>;
+  sequences: Record<string, Record<string, unknown>>;
+  tables: Record<string, Record<string, unknown>>;
+  triggers: Record<string, Record<string, unknown>>;
+  eventTriggers: Record<string, Record<string, unknown>>;
+  rules: Record<string, Record<string, unknown>>;
+  ranges: Record<string, Record<string, unknown>>;
+  views: Record<string, Record<string, unknown>>;
+  foreignDataWrappers: Record<string, Record<string, unknown>>;
+  servers: Record<string, Record<string, unknown>>;
+  userMappings: Record<string, Record<string, unknown>>;
+  foreignTables: Record<string, Record<string, unknown>>;
+  depends: PgDepend[];
+}
+
+// ============================================================================
+// Zod schema for validation on deserialization
+// ============================================================================
+
+const objectRecord = z.record(z.string(), z.any());
+
+const CatalogSnapshotSchema = z.object({
+  version: z.number(),
+  currentUser: z.string(),
+  aggregates: objectRecord,
+  collations: objectRecord,
+  compositeTypes: objectRecord,
+  domains: objectRecord,
+  enums: objectRecord,
+  extensions: objectRecord,
+  procedures: objectRecord,
+  indexes: objectRecord,
+  materializedViews: objectRecord,
+  subscriptions: objectRecord,
+  publications: objectRecord,
+  rlsPolicies: objectRecord,
+  roles: objectRecord,
+  schemas: objectRecord,
+  sequences: objectRecord,
+  tables: objectRecord,
+  triggers: objectRecord,
+  eventTriggers: objectRecord,
+  rules: objectRecord,
+  ranges: objectRecord,
+  views: objectRecord,
+  foreignDataWrappers: objectRecord,
+  servers: objectRecord,
+  userMappings: objectRecord,
+  foreignTables: objectRecord,
+  depends: z.array(
+    z.object({
+      dependent_stable_id: z.string(),
+      referenced_stable_id: z.string(),
+      deptype: z.enum(["n", "a", "i"]),
+    }),
+  ),
+});
+
+// ============================================================================
+// Serialization
+// ============================================================================
+
+function spreadRecord<T>(
+  record: Record<string, T>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, instance]) => [
+      key,
+      { ...(instance as Record<string, unknown>) },
+    ]),
+  );
+}
+
+/**
+ * Serialize Aggregate instances back to their Props shape.
+ *
+ * Aggregate renames `identity_arguments` -> `identityArguments` and trims it
+ * on construction. We must map it back to `identity_arguments` so
+ * deserialization through the constructor works.
+ */
+function serializeAggregates(
+  record: Record<string, Aggregate>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, agg]) => {
+      const { identityArguments: _, ...rest } = agg as unknown as Record<
+        string,
+        unknown
+      >;
+      return [key, { ...rest, identity_arguments: agg.identityArguments }];
+    }),
+  );
+}
+
+/**
+ * Serialize a Catalog to a JSON-serializable CatalogSnapshot.
+ *
+ * Expects a normalized catalog (as returned by `extractCatalog`).
+ * BigInt values (Sequence min/max) are converted to strings by the
+ * custom JSON replacer -- call `stringifyCatalogSnapshot` for JSON output.
+ */
+export function serializeCatalog(catalog: Catalog): CatalogSnapshot {
+  return {
+    version: catalog.version,
+    currentUser: catalog.currentUser,
+    aggregates: serializeAggregates(catalog.aggregates),
+    collations: spreadRecord(catalog.collations),
+    compositeTypes: spreadRecord(catalog.compositeTypes),
+    domains: spreadRecord(catalog.domains),
+    enums: spreadRecord(catalog.enums),
+    extensions: spreadRecord(catalog.extensions),
+    procedures: spreadRecord(catalog.procedures),
+    indexes: spreadRecord(catalog.indexes),
+    materializedViews: spreadRecord(catalog.materializedViews),
+    subscriptions: spreadRecord(catalog.subscriptions),
+    publications: spreadRecord(catalog.publications),
+    rlsPolicies: spreadRecord(catalog.rlsPolicies),
+    roles: spreadRecord(catalog.roles),
+    schemas: spreadRecord(catalog.schemas),
+    sequences: spreadRecord(catalog.sequences),
+    tables: spreadRecord(catalog.tables),
+    triggers: spreadRecord(catalog.triggers),
+    eventTriggers: spreadRecord(catalog.eventTriggers),
+    rules: spreadRecord(catalog.rules),
+    ranges: spreadRecord(catalog.ranges),
+    views: spreadRecord(catalog.views),
+    foreignDataWrappers: spreadRecord(catalog.foreignDataWrappers),
+    servers: spreadRecord(catalog.servers),
+    userMappings: spreadRecord(catalog.userMappings),
+    foreignTables: spreadRecord(catalog.foreignTables),
+    depends: catalog.depends,
+  };
+}
+
+/**
+ * Serialize a CatalogSnapshot to a JSON string.
+ *
+ * Handles BigInt values (Sequence min/max) by converting them to strings.
+ */
+export function stringifyCatalogSnapshot(snapshot: CatalogSnapshot): string {
+  return JSON.stringify(
+    snapshot,
+    (_key, value) => (typeof value === "bigint" ? value.toString() : value),
+    2,
+  );
+}
+
+// ============================================================================
+// Deserialization
+// ============================================================================
+
+function buildRecord<T>(
+  record: Record<string, Record<string, unknown>>,
+  ctor: new (props: never) => T,
+): Record<string, T> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, props]) => [
+      key,
+      new ctor(props as never),
+    ]),
+  );
+}
+
+/**
+ * Coerce BigInt fields in Sequence props from string back to BigInt.
+ * JSON has no BigInt type, so these are stored as strings.
+ */
+function coerceSequenceBigInts(
+  record: Record<string, Record<string, unknown>>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, props]) => [
+      key,
+      {
+        ...props,
+        minimum_value: BigInt(props.minimum_value as string | bigint),
+        maximum_value: BigInt(props.maximum_value as string | bigint),
+      },
+    ]),
+  );
+}
+
+/**
+ * Deserialize a CatalogSnapshot (plain JSON data) back into a Catalog.
+ *
+ * Validates the top-level structure with Zod, then constructs model
+ * class instances via their constructors. Rebuilds `indexableObjects`
+ * from tables + materializedViews.
+ */
+export function deserializeCatalog(data: unknown): Catalog {
+  const s = CatalogSnapshotSchema.parse(data);
+
+  const tables = buildRecord(s.tables, Table);
+  const materializedViews = buildRecord(s.materializedViews, MaterializedView);
+
+  return new Catalog({
+    version: s.version,
+    currentUser: s.currentUser,
+    aggregates: buildRecord(s.aggregates, Aggregate),
+    collations: buildRecord(s.collations, Collation),
+    compositeTypes: buildRecord(s.compositeTypes, CompositeType),
+    domains: buildRecord(s.domains, Domain),
+    enums: buildRecord(s.enums, Enum),
+    extensions: buildRecord(s.extensions, Extension),
+    procedures: buildRecord(s.procedures, Procedure),
+    indexes: buildRecord(s.indexes, Index),
+    materializedViews,
+    subscriptions: buildRecord(s.subscriptions, Subscription),
+    publications: buildRecord(s.publications, Publication),
+    rlsPolicies: buildRecord(s.rlsPolicies, RlsPolicy),
+    roles: buildRecord(s.roles, Role),
+    schemas: buildRecord(s.schemas, Schema),
+    sequences: buildRecord(coerceSequenceBigInts(s.sequences), Sequence),
+    tables,
+    triggers: buildRecord(s.triggers, Trigger),
+    eventTriggers: buildRecord(s.eventTriggers, EventTrigger),
+    rules: buildRecord(s.rules, Rule),
+    ranges: buildRecord(s.ranges, Range),
+    views: buildRecord(s.views, View),
+    foreignDataWrappers: buildRecord(s.foreignDataWrappers, ForeignDataWrapper),
+    servers: buildRecord(s.servers, Server),
+    userMappings: buildRecord(s.userMappings, UserMapping),
+    foreignTables: buildRecord(s.foreignTables, ForeignTable),
+    depends: s.depends,
+    indexableObjects: { ...tables, ...materializedViews },
+  });
+}

package/src/core/change-utils.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "./change.types.ts";
+import { getSchema } from "./change-utils.ts";
+
+describe("getSchema", () => {
+  test("returns schema for table", () => {
+    const change = {
+      objectType: "table",
+      table: { schema: "public" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("public");
+  });
+
+  test("returns schema for view", () => {
+    const change = {
+      objectType: "view",
+      view: { schema: "app" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("app");
+  });
+
+  test("returns schema for enum", () => {
+    const change = {
+      objectType: "enum",
+      enum: { schema: "types" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("types");
+  });
+
+  test("returns schema.name for schema type", () => {
+    const change = {
+      objectType: "schema",
+      schema: { name: "auth" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("auth");
+  });
+
+  test("returns null for role", () => {
+    const change = {
+      objectType: "role",
+      role: { name: "admin" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for publication", () => {
+    const change = {
+      objectType: "publication",
+      publication: { name: "pub1" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for language", () => {
+    const change = {
+      objectType: "language",
+      language: { name: "plpgsql" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+});

package/src/core/change-utils.ts

@@ -0,0 +1,73 @@
+import type { Change } from "./change.types.ts";
+
+/**
+ * Extract the schema name from a Change using the model sub-object.
+ *
+ * This is a convenience function used by the filter DSL (for schema
+ * normalization) and the sort module. It reads the `schema` (or `name`
+ * for schema objectType) from the model sub-object.
+ */
+export function getSchema(change: Change): string | null {
+  if (change.scope === "default_privilege") {
+    return change.inSchema;
+  }
+  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 change.eventTrigger.function_schema;
+    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: never = change;
+      return _exhaustive;
+    }
+  }
+}

package/src/core/change.types.ts

@@ -0,0 +1,94 @@
+import type { AggregateChange } from "./objects/aggregate/changes/aggregate.types.ts";
+import type { CollationChange } from "./objects/collation/changes/collation.types.ts";
+import type { DomainChange } from "./objects/domain/changes/domain.types.ts";
+import type { EventTriggerChange } from "./objects/event-trigger/changes/event-trigger.types.ts";
+import type { ExtensionChange } from "./objects/extension/changes/extension.types.ts";
+import type { ForeignDataWrapperChange } from "./objects/foreign-data-wrapper/foreign-data-wrapper.types.ts";
+import type { IndexChange } from "./objects/index/changes/index.types.ts";
+import type { LanguageChange } from "./objects/language/changes/language.types.ts";
+import type { MaterializedViewChange } from "./objects/materialized-view/changes/materialized-view.types.ts";
+import type { ProcedureChange } from "./objects/procedure/changes/procedure.types.ts";
+import type { PublicationChange } from "./objects/publication/changes/publication.types.ts";
+import type { RlsPolicyChange } from "./objects/rls-policy/changes/rls-policy.types.ts";
+import type { RoleChange } from "./objects/role/changes/role.types.ts";
+import type { RuleChange } from "./objects/rule/changes/rule.types.ts";
+import type { SchemaChange } from "./objects/schema/changes/schema.types.ts";
+import type { SequenceChange } from "./objects/sequence/changes/sequence.types.ts";
+import type { SubscriptionChange } from "./objects/subscription/changes/subscription.types.ts";
+import type { TableChange } from "./objects/table/changes/table.types.ts";
+import type { TriggerChange } from "./objects/trigger/changes/trigger.types.ts";
+import type { TypeChange } from "./objects/type/type.types.ts";
+import type { ViewChange } from "./objects/view/changes/view.types.ts";
+
+/**
+ * Discriminated union of all PostgreSQL object change types.
+ *
+ * Every member shares a common `objectType` discriminant (e.g. `"table"`,
+ * `"view"`, `"role"`) that the filter DSL pattern-matches against. Use
+ * {@link OBJECT_TYPE_TO_PROPERTY_KEY} to map an `objectType` value to the
+ * corresponding JS property key on the Change instance.
+ *
+ * @category Change Types
+ */
+export type Change =
+  | AggregateChange
+  | CollationChange
+  | DomainChange
+  | ExtensionChange
+  | IndexChange
+  | LanguageChange
+  | MaterializedViewChange
+  | SubscriptionChange
+  | PublicationChange
+  | ProcedureChange
+  | RlsPolicyChange
+  | RoleChange
+  | SchemaChange
+  | SequenceChange
+  | TableChange
+  | TriggerChange
+  | EventTriggerChange
+  | RuleChange
+  | TypeChange
+  | ViewChange
+  | ForeignDataWrapperChange;
+
+/**
+ * Exhaustive map from every `objectType` discriminant value to the JS property
+ * key that holds the model sub-object on the corresponding {@link Change}.
+ *
+ * Used internally by the filter DSL flattening logic to locate nested
+ * properties and expose them as `<objectType>/<field>` paths.
+ *
+ * @category Change Types
+ */
+export const OBJECT_TYPE_TO_PROPERTY_KEY: {
+  [K in Change["objectType"]]: string;
+} = {
+  aggregate: "aggregate",
+  collation: "collation",
+  composite_type: "compositeType",
+  domain: "domain",
+  enum: "enum",
+  event_trigger: "eventTrigger",
+  extension: "extension",
+  foreign_data_wrapper: "foreignDataWrapper",
+  foreign_table: "foreignTable",
+  index: "index",
+  language: "language",
+  materialized_view: "materializedView",
+  procedure: "procedure",
+  publication: "publication",
+  range: "range",
+  rls_policy: "policy",
+  role: "role",
+  rule: "rule",
+  schema: "schema",
+  sequence: "sequence",
+  server: "server",
+  subscription: "subscription",
+  table: "table",
+  trigger: "trigger",
+  user_mapping: "userMapping",
+  view: "view",
+};

package/src/core/context.ts

@@ -0,0 +1,26 @@
+import { sql } from "@ts-safeql/sql-tag";
+import type { Pool } from "pg";
+import type { Catalog } from "./catalog.model.ts";
+
+/**
+ * Context for diff operations, containing both source and target catalogs.
+ */
+export interface DiffContext {
+  mainCatalog: Catalog;
+  branchCatalog: Catalog;
+}
+
+export async function extractVersion(pool: Pool) {
+  const { rows } = await pool.query<{ version: number }>(
+    sql`select current_setting('server_version_num')::int as version`,
+  );
+
+  return rows[0].version;
+}
+
+export async function extractCurrentUser(pool: Pool) {
+  const { rows } = await pool.query<{ current_user: string }>(
+    sql`select quote_ident(current_user) as current_user`,
+  );
+  return rows[0].current_user;
+}

package/src/core/declarative-apply/discover-sql.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadDeclarativeSchema } from "./discover-sql.ts";
+
+describe("loadDeclarativeSchema", () => {
+  test("throws when path does not exist", async () => {
+    const nonExistent = path.join(
+      tmpdir(),
+      `pgdelta-nonexistent-${Date.now()}`,
+    );
+
+    await expect(loadDeclarativeSchema(nonExistent)).rejects.toThrow(
+      /Cannot access.*ENOENT/,
+    );
+  });
+
+  test("throws when path is a file but not .sql", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    const txtFile = path.join(dir, "foo.txt");
+    await writeFile(txtFile, "not sql");
+
+    try {
+      await expect(loadDeclarativeSchema(txtFile)).rejects.toThrow(
+        /Path is not a \.sql file/,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("loads a single .sql file and returns one entry with relative path", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    const sqlFile = path.join(dir, "schema.sql");
+    const content = "CREATE SCHEMA foo;";
+    await writeFile(sqlFile, content);
+
+    try {
+      const entries = await loadDeclarativeSchema(sqlFile);
+      expect(entries).toHaveLength(1);
+      expect(entries[0].filePath).toBe("schema.sql");
+      expect(entries[0].sql).toBe(content);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("loads directory of .sql files in deterministic order (match pg-topo)", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    const clusterDir = path.join(dir, "cluster");
+    const subDir = path.join(dir, "schemas", "public");
+    await mkdir(clusterDir, { recursive: true });
+    await mkdir(subDir, { recursive: true });
+    await writeFile(path.join(clusterDir, "roles.sql"), "SELECT 1;");
+    await writeFile(path.join(subDir, "schema.sql"), "CREATE SCHEMA public;");
+    await writeFile(
+      path.join(subDir, "tables.sql"),
+      "CREATE TABLE t (id int);",
+    );
+
+    try {
+      const entries = await loadDeclarativeSchema(dir);
+      expect(entries.length).toBeGreaterThanOrEqual(3);
+      const paths = entries.map((e) => e.filePath);
+      const sorted = [...paths].sort((a, b) => a.localeCompare(b));
+      expect(paths).toEqual(sorted);
+      expect(paths).toContain("schemas/public/schema.sql");
+      expect(paths).toContain("schemas/public/tables.sql");
+      expect(paths).toContain("cluster/roles.sql");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns empty array when directory has no .sql files", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, "readme.txt"), "no sql here");
+
+    try {
+      const entries = await loadDeclarativeSchema(dir);
+      expect(entries).toHaveLength(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});