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

package/dist/core/catalog.snapshot.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { Catalog } from "./catalog.model.ts";
+import type { PgDepend } from "./depend.ts";
+/**
+ * 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[];
+}
+/**
+ * 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 declare function serializeCatalog(catalog: Catalog): CatalogSnapshot;
+/**
+ * Serialize a CatalogSnapshot to a JSON string.
+ *
+ * Handles BigInt values (Sequence min/max) by converting them to strings.
+ */
+export declare function stringifyCatalogSnapshot(snapshot: CatalogSnapshot): string;
+/**
+ * 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 declare function deserializeCatalog(data: unknown): Catalog;

package/dist/core/catalog.snapshot.js

@@ -0,0 +1,206 @@
+/**
+ * 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.js";
+import { Aggregate } from "./objects/aggregate/aggregate.model.js";
+import { Collation } from "./objects/collation/collation.model.js";
+import { Domain } from "./objects/domain/domain.model.js";
+import { EventTrigger } from "./objects/event-trigger/event-trigger.model.js";
+import { Extension } from "./objects/extension/extension.model.js";
+import { ForeignDataWrapper } from "./objects/foreign-data-wrapper/foreign-data-wrapper/foreign-data-wrapper.model.js";
+import { ForeignTable } from "./objects/foreign-data-wrapper/foreign-table/foreign-table.model.js";
+import { Server } from "./objects/foreign-data-wrapper/server/server.model.js";
+import { UserMapping } from "./objects/foreign-data-wrapper/user-mapping/user-mapping.model.js";
+import { Index } from "./objects/index/index.model.js";
+import { MaterializedView } from "./objects/materialized-view/materialized-view.model.js";
+import { Procedure } from "./objects/procedure/procedure.model.js";
+import { Publication } from "./objects/publication/publication.model.js";
+import { RlsPolicy } from "./objects/rls-policy/rls-policy.model.js";
+import { Role } from "./objects/role/role.model.js";
+import { Rule } from "./objects/rule/rule.model.js";
+import { Schema } from "./objects/schema/schema.model.js";
+import { Sequence } from "./objects/sequence/sequence.model.js";
+import { Subscription } from "./objects/subscription/subscription.model.js";
+import { Table } from "./objects/table/table.model.js";
+import { Trigger } from "./objects/trigger/trigger.model.js";
+import { CompositeType } from "./objects/type/composite-type/composite-type.model.js";
+import { Enum } from "./objects/type/enum/enum.model.js";
+import { Range } from "./objects/type/range/range.model.js";
+import { View } from "./objects/view/view.model.js";
+// ============================================================================
+// 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(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, instance]) => [
+        key,
+        { ...instance },
+    ]));
+}
+/**
+ * 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) {
+    return Object.fromEntries(Object.entries(record).map(([key, agg]) => {
+        const { identityArguments: _, ...rest } = agg;
+        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) {
+    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) {
+    return JSON.stringify(snapshot, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
+}
+// ============================================================================
+// Deserialization
+// ============================================================================
+function buildRecord(record, ctor) {
+    return Object.fromEntries(Object.entries(record).map(([key, props]) => [
+        key,
+        new ctor(props),
+    ]));
+}
+/**
+ * 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) {
+    return Object.fromEntries(Object.entries(record).map(([key, props]) => [
+        key,
+        {
+            ...props,
+            minimum_value: BigInt(props.minimum_value),
+            maximum_value: BigInt(props.maximum_value),
+        },
+    ]));
+}
+/**
+ * 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) {
+    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/dist/core/context.d.ts

@@ -1,4 +1,4 @@
-import type { Sql } from "postgres";
+import type { Pool } from "pg";
 import type { Catalog } from "./catalog.model.ts";
 /**
  * Context for diff operations, containing both source and target catalogs.
@@ -7,5 +7,5 @@ export interface DiffContext {
     mainCatalog: Catalog;
     branchCatalog: Catalog;
 }
-export declare function extractVersion(sql: Sql): Promise<number>;
-export declare function extractCurrentUser(sql: Sql): Promise<string>;
+export declare function extractVersion(pool: Pool): Promise<number>;
+export declare function extractCurrentUser(pool: Pool): Promise<string>;

package/dist/core/context.js

@@ -1,12 +1,9 @@
-export async function extractVersion(sql) {
-    const [{ version }] = await sql `
-    select current_setting('server_version_num')::int as version;
-  `;
-    return version;
+import { sql } from "@ts-safeql/sql-tag";
+export async function extractVersion(pool) {
+    const { rows } = await pool.query(sql `select current_setting('server_version_num')::int as version`);
+    return rows[0].version;
 }
-export async function extractCurrentUser(sql) {
-    const [{ current_user }] = await sql `
-    select quote_ident(current_user) as current_user;
-  `;
-    return current_user;
+export async function extractCurrentUser(pool) {
+    const { rows } = await pool.query(sql `select quote_ident(current_user) as current_user`);
+    return rows[0].current_user;
 }

package/dist/core/declarative-apply/discover-sql.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Discover and read .sql files under a schema path (file or directory).
+ * Matches pg-topo's discovery order for deterministic statement ordering.
+ */
+export interface SqlFileEntry {
+    /** Relative path from base (forward slashes, e.g. schemas/public/views/billing.sql) */
+    filePath: string;
+    /** File content */
+    sql: string;
+}
+/**
+ * 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 declare function loadDeclarativeSchema(schemaPath: string): Promise<SqlFileEntry[]>;

package/dist/core/declarative-apply/discover-sql.js

@@ -0,0 +1,86 @@
+/**
+ * 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";
+/**
+ * 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, outFiles) {
+    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, basePath) {
+    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) {
+    const resolvedRoot = path.resolve(schemaPath);
+    let rootStats;
+    try {
+        rootStats = await stat(resolvedRoot);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+            ? String(err.code)
+            : "UNKNOWN";
+        throw new Error(`Cannot access '${schemaPath}': ${code}`);
+    }
+    let files;
+    let basePath;
+    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();
+        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 = [];
+    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.code)
+                : "UNKNOWN";
+            const relative = toStablePath(filePath, basePath);
+            throw new Error(`Cannot read file '${relative}': ${code}`);
+        }
+    }
+    return entries;
+}

package/dist/core/declarative-apply/extract-catalog-providers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Extract functions, types, and other catalog objects from the target database
+ * so pg-topo can treat them as external providers and suppress false
+ * UNRESOLVED_DEPENDENCY diagnostics (e.g. now(), gen_random_uuid(), nextval(),
+ * auth.users, extensions.uuid_generate_v4, etc.).
+ */
+import type { ObjectRef } from "@supabase/pg-topo";
+import type { Pool } from "pg";
+/**
+ * Query the target database for all catalog objects that can be dependencies.
+ * Returns ObjectRefs that pg-topo can use as external providers so it does
+ * not flag false UNRESOLVED_DEPENDENCY diagnostics (e.g. now(), text, public).
+ *
+ * This is intentionally separate from {@link extractCatalog} in catalog.model.ts:
+ * - extractCatalog is for schema diffing and excludes system objects (filters
+ *   out pg_catalog, information_schema, extension-owned). It also does not
+ *   extract languages. We need the opposite here: all objects that might be
+ *   referenced by SQL, including built-in functions, types, and schemas.
+ * - Objects in pg_catalog/information_schema are registered under both their
+ *   real schema and "public" (via addProvider's alsoUnderPublic) so
+ *   unqualified references in SQL resolve the same way the parser does.
+ */
+export declare function extractCatalogProviders(pool: Pool): Promise<ObjectRef[]>;

package/dist/core/declarative-apply/extract-catalog-providers.js

@@ -0,0 +1,159 @@
+/**
+ * Extract functions, types, and other catalog objects from the target database
+ * so pg-topo can treat them as external providers and suppress false
+ * UNRESOLVED_DEPENDENCY diagnostics (e.g. now(), gen_random_uuid(), nextval(),
+ * auth.users, extensions.uuid_generate_v4, etc.).
+ */
+function addProvider(providers, ref, alsoUnderPublic = false) {
+    providers.push(ref);
+    if (alsoUnderPublic &&
+        (ref.schema === "pg_catalog" || ref.schema === "information_schema")) {
+        providers.push({ ...ref, schema: "public" });
+    }
+}
+/**
+ * Query the target database for all catalog objects that can be dependencies.
+ * Returns ObjectRefs that pg-topo can use as external providers so it does
+ * not flag false UNRESOLVED_DEPENDENCY diagnostics (e.g. now(), text, public).
+ *
+ * This is intentionally separate from {@link extractCatalog} in catalog.model.ts:
+ * - extractCatalog is for schema diffing and excludes system objects (filters
+ *   out pg_catalog, information_schema, extension-owned). It also does not
+ *   extract languages. We need the opposite here: all objects that might be
+ *   referenced by SQL, including built-in functions, types, and schemas.
+ * - Objects in pg_catalog/information_schema are registered under both their
+ *   real schema and "public" (via addProvider's alsoUnderPublic) so
+ *   unqualified references in SQL resolve the same way the parser does.
+ */
+export async function extractCatalogProviders(pool) {
+    const providers = [];
+    const [functionsResult, typesResult, schemasResult, relationsResult, extensionsResult, rolesResult, languagesResult, collationsResult, fdwsResult, serversResult, eventTriggersResult, publicationsResult, subscriptionsResult,] = await Promise.all([
+        pool.query(`
+      SELECT
+        p.proname AS name,
+        n.nspname AS schema,
+        p.prokind AS kind,
+        COALESCE((
+          SELECT string_agg(
+            CASE WHEN p.proargmodes IS NOT NULL AND p.proargmodes[ord] = 'v'
+                 THEN 'VARIADIC ' || format_type(t.oid, NULL)
+                 ELSE format_type(t.oid, NULL)
+            END, ',' ORDER BY ord)
+          FROM unnest(p.proargtypes) WITH ORDINALITY AS t(oid, ord)
+        ), '') AS signature
+      FROM pg_proc p
+      JOIN pg_namespace n ON n.oid = p.pronamespace
+    `),
+        pool.query(`
+      SELECT t.typname AS name, n.nspname AS schema, t.typtype AS typetype
+      FROM pg_type t
+      JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname NOT LIKE 'pg_toast%'
+        AND t.typtype IN ('b', 'c', 'd', 'e', 'r')
+    `),
+        pool.query(`
+      SELECT nspname AS name FROM pg_namespace
+      WHERE nspname NOT LIKE 'pg_toast%'
+    `),
+        pool.query(`
+      SELECT c.relname AS name, n.nspname AS schema, c.relkind AS relkind
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind IN ('r', 'p', 'v', 'm', 'S', 'i')
+        AND n.nspname NOT LIKE 'pg_toast%'
+    `),
+        pool.query(`
+      SELECT e.extname AS name, n.nspname AS schema
+      FROM pg_extension e
+      LEFT JOIN pg_namespace n ON n.oid = e.extnamespace
+    `),
+        pool.query(`SELECT rolname AS name FROM pg_roles`),
+        pool.query(`SELECT lanname AS name FROM pg_language`),
+        pool.query(`
+      SELECT c.collname AS name, n.nspname AS schema
+      FROM pg_collation c
+      JOIN pg_namespace n ON n.oid = c.collnamespace
+      WHERE n.nspname NOT LIKE 'pg_toast%'
+    `),
+        pool.query(`SELECT fdwname AS name FROM pg_foreign_data_wrapper`),
+        pool.query(`SELECT srvname AS name FROM pg_foreign_server`),
+        pool.query(`SELECT evtname AS name FROM pg_event_trigger`),
+        pool.query(`SELECT pubname AS name FROM pg_publication`),
+        pool.query(`SELECT subname AS name FROM pg_subscription`),
+    ]);
+    for (const fn of functionsResult.rows) {
+        const kind = fn.kind === "a"
+            ? "aggregate"
+            : fn.kind === "p"
+                ? "procedure"
+                : "function";
+        const sig = fn.signature.trim() ? `(${fn.signature})` : "()";
+        const ref = {
+            kind,
+            name: fn.name,
+            schema: fn.schema,
+            signature: sig,
+        };
+        addProvider(providers, ref, true);
+    }
+    for (const t of typesResult.rows) {
+        const kind = t.typetype === "d" ? "domain" : "type";
+        const ref = { kind, name: t.name, schema: t.schema };
+        addProvider(providers, ref, true);
+    }
+    for (const row of schemasResult.rows) {
+        providers.push({ kind: "schema", name: row.name });
+    }
+    const relkindToKind = {
+        r: "table",
+        p: "table",
+        v: "view",
+        m: "materialized_view",
+        S: "sequence",
+        i: "index",
+    };
+    for (const row of relationsResult.rows) {
+        const kind = relkindToKind[row.relkind];
+        if (!kind)
+            continue;
+        const ref = { kind, name: row.name, schema: row.schema };
+        addProvider(providers, ref, true);
+    }
+    for (const row of extensionsResult.rows) {
+        providers.push({
+            kind: "extension",
+            name: row.name,
+            schema: row.schema ?? undefined,
+        });
+    }
+    for (const row of rolesResult.rows) {
+        providers.push({ kind: "role", name: row.name });
+    }
+    for (const row of languagesResult.rows) {
+        providers.push({ kind: "language", name: row.name });
+    }
+    for (const row of collationsResult.rows) {
+        const ref = {
+            kind: "collation",
+            name: row.name,
+            schema: row.schema,
+        };
+        addProvider(providers, ref, true);
+    }
+    for (const row of fdwsResult.rows) {
+        providers.push({ kind: "foreign_data_wrapper", name: row.name });
+    }
+    for (const row of serversResult.rows) {
+        providers.push({ kind: "foreign_server", name: row.name });
+    }
+    for (const row of eventTriggersResult.rows) {
+        providers.push({ kind: "event_trigger", name: row.name });
+    }
+    for (const row of publicationsResult.rows) {
+        providers.push({ kind: "publication", name: row.name });
+    }
+    for (const row of subscriptionsResult.rows) {
+        providers.push({ kind: "subscription", name: row.name });
+    }
+    return providers;
+}

package/dist/core/declarative-apply/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Declarative schema apply – orchestrator.
+ *
+ * Accepts pre-read SQL content (file path + sql string per file), uses pg-topo
+ * for static dependency analysis and topological ordering, then applies
+ * statements to a target database using iterative rounds to handle any
+ * remaining dependency gaps. File discovery and reading are done by the caller
+ * (e.g. CLI) so I/O errors can be handled there.
+ */
+import type { Diagnostic } from "@supabase/pg-topo";
+import type { Pool } from "pg";
+import { type ApplyResult, type RoundResult } from "./round-apply.ts";
+import type { SqlFileEntry } from "./discover-sql.ts";
+interface DeclarativeApplyOptions {
+    /** Pre-read SQL files: filePath (relative) and sql content. Caller does discovery and read. */
+    content: SqlFileEntry[];
+    /** Target database connection URL (required if pool is not provided) */
+    targetUrl?: string;
+    /** Existing pool to use (caller owns it; not closed). If provided, targetUrl is ignored. */
+    pool?: Pool;
+    /** Max rounds before giving up (default: 100) */
+    maxRounds?: number;
+    /** Run final function body validation (default: true) */
+    validateFunctionBodies?: boolean;
+    /** Disable function body checks during rounds (default: true) */
+    disableCheckFunctionBodies?: boolean;
+    /** Progress callback fired after each round */
+    onRoundComplete?: (round: RoundResult) => void;
+}
+export interface DeclarativeApplyResult {
+    /** Result from the round-based apply engine */
+    apply: ApplyResult;
+    /** Diagnostics from pg-topo's static analysis (warnings, not fatal) */
+    diagnostics: Diagnostic[];
+    /** Total number of statements discovered */
+    totalStatements: number;
+}
+/**
+ * Apply a declarative SQL schema to a target database.
+ *
+ * 1. Call pg-topo analyzeAndSort on the provided SQL strings
+ * 2. Remap synthetic statement IDs to caller-provided file paths
+ * 3. Apply statements round-by-round to the target database
+ * 4. Optionally validate function bodies in a final pass
+ */
+export declare function applyDeclarativeSchema(options: DeclarativeApplyOptions): Promise<DeclarativeApplyResult>;
+export type { SqlFileEntry } from "./discover-sql.ts";
+export { loadDeclarativeSchema } from "./discover-sql.ts";
+export type { ApplyResult, RoundResult } from "./round-apply.ts";