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

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/change-utils.d.ts

@@ -0,0 +1,9 @@
+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 declare function getSchema(change: Change): string | null;

package/dist/core/change-utils.js

@@ -0,0 +1,71 @@
+/**
+ * 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) {
+    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 = change;
+            return _exhaustive;
+        }
+    }
+}

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

@@ -19,4 +19,26 @@ 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 declare const OBJECT_TYPE_TO_PROPERTY_KEY: {
+    [K in Change["objectType"]]: string;
+};

package/dist/core/change.types.js

@@ -1 +1,37 @@
-export {};
+/**
+ * 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 = {
+    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/dist/core/connection-url.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Connection URL normalization for pg-delta.
+ *
+ * Auto-normalizes percent-encoded IPv6 hosts in PostgreSQL connection URLs.
+ * A URL like `postgresql://user:pass@2406%3Ada18%3A...%3Ab3c9:5432/db`
+ * becomes `postgresql://user:pass@[2406:da18:...:b3c9]:5432/db` before it
+ * reaches `pg-connection-string` / `pg.Pool`, so DNS resolution sees the
+ * address in its canonical bracketed form.
+ *
+ * Non-IPv6 hosts (IPv4, DNS names, already-bracketed IPv6, partial fragments
+ * that just happen to contain `%3A`) are returned verbatim.
+ */
+/**
+ * Return true if `value` is a valid IPv6 literal in any canonical form:
+ * full 8-group, `::` compression, or IPv4-mapped (`::ffff:1.2.3.4`).
+ * RFC 4007 zone identifiers (`fe80::1%eth0`) are accepted.
+ */
+export declare function isIPv6(value: string): boolean;
+/**
+ * Normalize a PostgreSQL connection URL so IPv6 hosts reach pg in the
+ * canonical bracketed form.
+ *
+ * If the URL's hostname contains a percent-encoded colon AND the decoded
+ * hostname is a valid IPv6 literal, the hostname is decoded and wrapped in
+ * `[...]`. All other fields (scheme, userinfo, port, path, query, fragment)
+ * are preserved byte-for-byte from the input.
+ *
+ * Any URL whose decoded hostname does not validate as IPv6 is returned
+ * verbatim, so a malformed input will surface its usual downstream error
+ * instead of being silently rewritten.
+ */
+export declare function normalizeConnectionUrl(url: string): string;

package/dist/core/connection-url.js

@@ -0,0 +1,77 @@
+/**
+ * Connection URL normalization for pg-delta.
+ *
+ * Auto-normalizes percent-encoded IPv6 hosts in PostgreSQL connection URLs.
+ * A URL like `postgresql://user:pass@2406%3Ada18%3A...%3Ab3c9:5432/db`
+ * becomes `postgresql://user:pass@[2406:da18:...:b3c9]:5432/db` before it
+ * reaches `pg-connection-string` / `pg.Pool`, so DNS resolution sees the
+ * address in its canonical bracketed form.
+ *
+ * Non-IPv6 hosts (IPv4, DNS names, already-bracketed IPv6, partial fragments
+ * that just happen to contain `%3A`) are returned verbatim.
+ */
+// IPv6 detection regex vendored from ip-regex (Sindre Sorhus, MIT).
+// https://github.com/sindresorhus/ip-regex
+const v4 = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)){3}";
+const v6seg = "[a-fA-F\\d]{1,4}";
+const v6 = `
+(?:
+(?:${v6seg}:){7}(?:${v6seg}|:)|
+(?:${v6seg}:){6}(?:${v4}|:${v6seg}|:)|
+(?:${v6seg}:){5}(?::${v4}|(?::${v6seg}){1,2}|:)|
+(?:${v6seg}:){4}(?:(?::${v6seg}){0,1}:${v4}|(?::${v6seg}){1,3}|:)|
+(?:${v6seg}:){3}(?:(?::${v6seg}){0,2}:${v4}|(?::${v6seg}){1,4}|:)|
+(?:${v6seg}:){2}(?:(?::${v6seg}){0,3}:${v4}|(?::${v6seg}){1,5}|:)|
+(?:${v6seg}:){1}(?:(?::${v6seg}){0,4}:${v4}|(?::${v6seg}){1,6}|:)|
+(?::(?:(?::${v6seg}){0,5}:${v4}|(?::${v6seg}){1,7}|:))
+)(?:%[0-9a-zA-Z]{1,})?
+`
+    .replace(/\s*\/\/.*$/gm, "")
+    .replace(/\n/g, "")
+    .trim();
+const V6_EXACT = new RegExp(`^${v6}$`);
+/**
+ * Return true if `value` is a valid IPv6 literal in any canonical form:
+ * full 8-group, `::` compression, or IPv4-mapped (`::ffff:1.2.3.4`).
+ * RFC 4007 zone identifiers (`fe80::1%eth0`) are accepted.
+ */
+export function isIPv6(value) {
+    return typeof value === "string" && V6_EXACT.test(value);
+}
+/**
+ * Normalize a PostgreSQL connection URL so IPv6 hosts reach pg in the
+ * canonical bracketed form.
+ *
+ * If the URL's hostname contains a percent-encoded colon AND the decoded
+ * hostname is a valid IPv6 literal, the hostname is decoded and wrapped in
+ * `[...]`. All other fields (scheme, userinfo, port, path, query, fragment)
+ * are preserved byte-for-byte from the input.
+ *
+ * Any URL whose decoded hostname does not validate as IPv6 is returned
+ * verbatim, so a malformed input will surface its usual downstream error
+ * instead of being silently rewritten.
+ */
+export function normalizeConnectionUrl(url) {
+    const urlObj = new URL(url);
+    // Cheap pre-filter: only look closer if the hostname contains a
+    // percent-encoded colon. Anything else is left entirely untouched.
+    if (!/%3[aA]/.test(urlObj.hostname))
+        return url;
+    const decodedHost = decodeURIComponent(urlObj.hostname);
+    // Authoritative validation: only normalize when the decoded string is a
+    // real IPv6 literal. Rejects partial fragments, random hostnames that
+    // happen to contain `%3A`, and any malformed input.
+    if (!isIPv6(decodedHost))
+        return url;
+    // Preserve username/password/port/path/search/hash exactly as they appear
+    // in the WHATWG URL model (these are returned already percent-encoded).
+    const scheme = `${urlObj.protocol}//`;
+    const auth = urlObj.username
+        ? urlObj.password
+            ? `${urlObj.username}:${urlObj.password}@`
+            : `${urlObj.username}@`
+        : "";
+    const port = urlObj.port ? `:${urlObj.port}` : "";
+    const tail = `${urlObj.pathname}${urlObj.search}${urlObj.hash}`;
+    return `${scheme}${auth}[${decodedHost}]${port}${tail}`;
+}

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[]>;