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

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.types.ts

@@ -0,0 +1,44 @@
+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";
+
+export type Change =
+  | AggregateChange
+  | CollationChange
+  | DomainChange
+  | ExtensionChange
+  | IndexChange
+  | LanguageChange
+  | MaterializedViewChange
+  | SubscriptionChange
+  | PublicationChange
+  | ProcedureChange
+  | RlsPolicyChange
+  | RoleChange
+  | SchemaChange
+  | SequenceChange
+  | TableChange
+  | TriggerChange
+  | EventTriggerChange
+  | RuleChange
+  | TypeChange
+  | ViewChange
+  | ForeignDataWrapperChange;

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 });
+    }
+  });
+});

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

@@ -0,0 +1,107 @@
+/**
+ * Discover and read .sql files under a schema path (file or directory).
+ * Matches pg-topo's discovery order for deterministic statement ordering.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+export interface SqlFileEntry {
+  /** Relative path from base (forward slashes, e.g. schemas/public/views/billing.sql) */
+  filePath: string;
+  /** File content */
+  sql: string;
+}
+
+/**
+ * Recursively collect .sql files in a directory. Entries sorted by name,
+ * then full paths sorted for deterministic order (matches pg-topo discover).
+ */
+async function readSqlFilesInDirectory(
+  directoryPath: string,
+  outFiles: Set<string>,
+): Promise<void> {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    const fullPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      await readSqlFilesInDirectory(fullPath, outFiles);
+      continue;
+    }
+
+    if (entry.isFile() && fullPath.toLowerCase().endsWith(".sql")) {
+      outFiles.add(path.resolve(fullPath));
+    }
+  }
+}
+
+/**
+ * Stable relative path: path.relative(basePath, absolutePath) with forward slashes.
+ */
+function toStablePath(absolutePath: string, basePath: string): string {
+  return path.relative(basePath, absolutePath).split(path.sep).join("/");
+}
+
+/**
+ * Load all .sql files under schemaPath (a single .sql file or a directory).
+ * Returns entries in the same order as pg-topo's discover (sorted by full path).
+ *
+ * @throws If schemaPath does not exist, is not a file/directory, or any file cannot be read.
+ *         Error message includes path and code (e.g. ENOENT, EACCES) for CLI to display.
+ */
+export async function loadDeclarativeSchema(
+  schemaPath: string,
+): Promise<SqlFileEntry[]> {
+  const resolvedRoot = path.resolve(schemaPath);
+
+  let rootStats: Awaited<ReturnType<typeof stat>>;
+  try {
+    rootStats = await stat(resolvedRoot);
+  } catch (err) {
+    const code =
+      err && typeof err === "object" && "code" in err
+        ? String((err as NodeJS.ErrnoException).code)
+        : "UNKNOWN";
+    throw new Error(`Cannot access '${schemaPath}': ${code}`);
+  }
+
+  let files: string[];
+  let basePath: string;
+
+  if (rootStats.isFile()) {
+    if (!resolvedRoot.toLowerCase().endsWith(".sql")) {
+      throw new Error(`Path is not a .sql file: '${schemaPath}'`);
+    }
+    files = [resolvedRoot];
+    basePath = path.dirname(resolvedRoot);
+  } else if (rootStats.isDirectory()) {
+    const fileSet = new Set<string>();
+    await readSqlFilesInDirectory(resolvedRoot, fileSet);
+    files = [...fileSet].sort((a, b) => a.localeCompare(b));
+    basePath = resolvedRoot;
+  } else {
+    throw new Error(`Path is not a file or directory: '${schemaPath}'`);
+  }
+
+  const entries: SqlFileEntry[] = [];
+  for (const filePath of files) {
+    try {
+      const sql = await readFile(filePath, "utf-8");
+      entries.push({
+        filePath: toStablePath(filePath, basePath),
+        sql,
+      });
+    } catch (err) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? String((err as NodeJS.ErrnoException).code)
+          : "UNKNOWN";
+      const relative = toStablePath(filePath, basePath);
+      throw new Error(`Cannot read file '${relative}': ${code}`);
+    }
+  }
+
+  return entries;
+}