@supabase/pg-delta 1.0.0-alpha.18 → 1.0.0-alpha.19

package/dist/core/expand-replace-dependencies.js

@@ -1,5 +1,7 @@
 import { CreateDomain } from "./objects/domain/changes/domain.create.js";
 import { DropDomain } from "./objects/domain/changes/domain.drop.js";
+import { CreateIndex } from "./objects/index/changes/index.create.js";
+import { DropIndex } from "./objects/index/changes/index.drop.js";
 import { CreateMaterializedView } from "./objects/materialized-view/changes/materialized-view.create.js";
 import { DropMaterializedView } from "./objects/materialized-view/changes/materialized-view.drop.js";
 import { CreateProcedure } from "./objects/procedure/changes/procedure.create.js";
@@ -222,6 +224,18 @@ function resolveObjectForStableId(stableId, mainCatalog, branchCatalog) {
         const branch = branchCatalog.materializedViews[stableId];
         return main && branch ? { kind: "materialized_view", main, branch } : null;
     }
+    if (stableId.startsWith("index:")) {
+        const main = mainCatalog.indexes[stableId];
+        const branch = branchCatalog.indexes[stableId];
+        return main && branch
+            ? {
+                kind: "index",
+                main,
+                branch,
+                branchIndexableObject: branchCatalog.indexableObjects[branch.tableStableId],
+            }
+            : null;
+    }
     if (stableId.startsWith("procedure:")) {
         const main = mainCatalog.procedures[stableId];
         const branch = branchCatalog.procedures[stableId];
@@ -307,6 +321,34 @@ function buildReplaceChanges(resolved, options) {
                     ? [new CreateMaterializedView({ materializedView: resolved.branch })]
                     : []),
             ];
+        case "index":
+            // Constraint-owned, primary, and partition-attached indexes are managed
+            // by the owning constraint or parent-index DDL, not standalone
+            // CREATE INDEX / DROP INDEX. The `case "table":` branch above already
+            // recreates constraints via AlterTableAddConstraint; emitting a
+            // standalone drop/create here would fail in PostgreSQL
+            // ("cannot drop index ... because constraint ... requires it") or
+            // duplicate the index the constraint recreates. Skip matches
+            // diffIndexes (packages/pg-delta/src/core/objects/index/index.diff.ts).
+            if (resolved.main.is_owned_by_constraint ||
+                resolved.main.is_primary ||
+                resolved.main.is_index_partition ||
+                resolved.branch.is_owned_by_constraint ||
+                resolved.branch.is_primary ||
+                resolved.branch.is_index_partition) {
+                return null;
+            }
+            return [
+                ...(addDrop ? [new DropIndex({ index: resolved.main })] : []),
+                ...(addCreate
+                    ? [
+                        new CreateIndex({
+                            index: resolved.branch,
+                            indexableObject: resolved.branchIndexableObject,
+                        }),
+                    ]
+                    : []),
+            ];
         case "procedure":
             return [
                 ...(addDrop ? [new DropProcedure({ procedure: resolved.main })] : []),

package/dist/core/objects/index/index.model.js

@@ -36,6 +36,15 @@ const indexPropsSchema = z.object({
     comment: z.string().nullable(),
     owner: z.string(),
 });
+// pg_get_indexdef(oid, colno, pretty) invokes pg_get_indexdef_worker with
+// missing_ok = true, so it can return NULL when any internal system-cache lookup
+// fails (race with concurrent DROP, role visibility edge cases, orphaned index
+// metadata, recovery transients). An unreadable index cannot be diffed, so we
+// accept NULL here and filter the row out with a debug log instead of crashing
+// the whole catalog extraction.
+const indexRowSchema = indexPropsSchema.extend({
+    definition: z.string().nullable(),
+});
 export class Index extends BasePgModel {
     schema;
     table_name;
@@ -332,7 +341,8 @@ export async function extractIndexes(pool) {
 
       order by 1, 2
   `);
-    // Validate and parse each row using the Zod schema
-    const validatedRows = indexRows.map((row) => indexPropsSchema.parse(row));
+    const validatedRows = indexRows
+        .map((row) => indexRowSchema.parse(row))
+        .filter((row) => row.definition !== null);
     return validatedRows.map((row) => new Index(row));
 }

package/dist/core/objects/rls-policy/changes/rls-policy.create.js

@@ -33,6 +33,29 @@ export class CreateRlsPolicy extends CreateRlsPolicyChange {
         dependencies.add(stableId.table(this.policy.schema, this.policy.table_name));
         // Owner dependency
         dependencies.add(stableId.role(this.policy.owner));
+        // Relations and functions referenced inside USING / WITH CHECK
+        // expressions must exist before the policy is created. These come from
+        // pg_depend (populated by PostgreSQL's recordDependencyOnExpr at policy
+        // creation), not from re-parsing the expression text.
+        for (const ref of this.policy.referenced_relations) {
+            switch (ref.kind) {
+                case "table":
+                    dependencies.add(stableId.table(ref.schema, ref.name));
+                    break;
+                case "view":
+                    dependencies.add(stableId.view(ref.schema, ref.name));
+                    break;
+                case "materialized_view":
+                    dependencies.add(stableId.materializedView(ref.schema, ref.name));
+                    break;
+                case "foreign_table":
+                    dependencies.add(stableId.foreignTable(ref.schema, ref.name));
+                    break;
+            }
+        }
+        for (const ref of this.policy.referenced_procedures) {
+            dependencies.add(stableId.procedure(ref.schema, ref.name, ref.argument_types.join(",")));
+        }
         return Array.from(dependencies);
     }
     serialize(_options) {

package/dist/core/objects/rls-policy/rls-policy.model.d.ts

@@ -1,6 +1,23 @@
 import type { Pool } from "pg";
 import z from "zod";
 import { BasePgModel } from "../base.model.ts";
+declare const rlsPolicyReferencedRelationSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        foreign_table: "foreign_table";
+        materialized_view: "materialized_view";
+        table: "table";
+        view: "view";
+    }>;
+    schema: z.ZodString;
+    name: z.ZodString;
+}, z.z.core.$strip>;
+export type RlsPolicyReferencedRelation = z.infer<typeof rlsPolicyReferencedRelationSchema>;
+declare const rlsPolicyReferencedProcedureSchema: z.ZodObject<{
+    schema: z.ZodString;
+    name: z.ZodString;
+    argument_types: z.ZodArray<z.ZodString>;
+}, z.z.core.$strip>;
+export type RlsPolicyReferencedProcedure = z.infer<typeof rlsPolicyReferencedProcedureSchema>;
 declare const rlsPolicyPropsSchema: z.ZodObject<{
     schema: z.ZodString;
     name: z.ZodString;
@@ -18,6 +35,21 @@ declare const rlsPolicyPropsSchema: z.ZodObject<{
     with_check_expression: z.ZodNullable<z.ZodString>;
     owner: z.ZodString;
     comment: z.ZodNullable<z.ZodString>;
+    referenced_relations: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            foreign_table: "foreign_table";
+            materialized_view: "materialized_view";
+            table: "table";
+            view: "view";
+        }>;
+        schema: z.ZodString;
+        name: z.ZodString;
+    }, z.z.core.$strip>>;
+    referenced_procedures: z.ZodArray<z.ZodObject<{
+        schema: z.ZodString;
+        name: z.ZodString;
+        argument_types: z.ZodArray<z.ZodString>;
+    }, z.z.core.$strip>>;
 }, z.z.core.$strip>;
 export type RlsPolicyProps = z.infer<typeof rlsPolicyPropsSchema>;
 export declare class RlsPolicy extends BasePgModel {
@@ -31,6 +63,23 @@ export declare class RlsPolicy extends BasePgModel {
     readonly with_check_expression: RlsPolicyProps["with_check_expression"];
     readonly owner: RlsPolicyProps["owner"];
     readonly comment: RlsPolicyProps["comment"];
+    /**
+     * Tables / views / materialized views / foreign tables that
+     * `using_expression` / `with_check_expression` reference, sourced from
+     * `pg_depend` (`recordDependencyOnExpr` at policy creation). Drives
+     * ordering dependencies in `CreateRlsPolicy.requires`. Intentionally
+     * excluded from `dataFields` — it's derived from the expression text
+     * and changes lockstep with it.
+     */
+    readonly referenced_relations: RlsPolicyProps["referenced_relations"];
+    /**
+     * Functions / procedures that `using_expression` / `with_check_expression`
+     * reference, sourced from `pg_depend` (refclassid = `pg_proc`). The
+     * argument-type signature comes straight from `pg_proc.proargtypes` via
+     * `format_type`, so it matches the signature the procedure extractor
+     * embeds in `stableId.procedure(...)`. Not part of `dataFields`.
+     */
+    readonly referenced_procedures: RlsPolicyProps["referenced_procedures"];
     constructor(props: RlsPolicyProps);
     get stableId(): `rlsPolicy:${string}`;
     get identityFields(): {

package/dist/core/objects/rls-policy/rls-policy.model.js

@@ -8,6 +8,22 @@ const RlsPolicyCommandSchema = z.enum([
     "d", // DELETE command
     "*", // ALL commands
 ]);
+const RlsPolicyReferencedRelationKindSchema = z.enum([
+    "table",
+    "view",
+    "materialized_view",
+    "foreign_table",
+]);
+const rlsPolicyReferencedRelationSchema = z.object({
+    kind: RlsPolicyReferencedRelationKindSchema,
+    schema: z.string(),
+    name: z.string(),
+});
+const rlsPolicyReferencedProcedureSchema = z.object({
+    schema: z.string(),
+    name: z.string(),
+    argument_types: z.array(z.string()),
+});
 const rlsPolicyPropsSchema = z.object({
     schema: z.string(),
     name: z.string(),
@@ -19,6 +35,8 @@ const rlsPolicyPropsSchema = z.object({
     with_check_expression: z.string().nullable(),
     owner: z.string(),
     comment: z.string().nullable(),
+    referenced_relations: z.array(rlsPolicyReferencedRelationSchema),
+    referenced_procedures: z.array(rlsPolicyReferencedProcedureSchema),
 });
 export class RlsPolicy extends BasePgModel {
     schema;
@@ -31,6 +49,23 @@ export class RlsPolicy extends BasePgModel {
     with_check_expression;
     owner;
     comment;
+    /**
+     * Tables / views / materialized views / foreign tables that
+     * `using_expression` / `with_check_expression` reference, sourced from
+     * `pg_depend` (`recordDependencyOnExpr` at policy creation). Drives
+     * ordering dependencies in `CreateRlsPolicy.requires`. Intentionally
+     * excluded from `dataFields` — it's derived from the expression text
+     * and changes lockstep with it.
+     */
+    referenced_relations;
+    /**
+     * Functions / procedures that `using_expression` / `with_check_expression`
+     * reference, sourced from `pg_depend` (refclassid = `pg_proc`). The
+     * argument-type signature comes straight from `pg_proc.proargtypes` via
+     * `format_type`, so it matches the signature the procedure extractor
+     * embeds in `stableId.procedure(...)`. Not part of `dataFields`.
+     */
+    referenced_procedures;
     constructor(props) {
         super();
         // Identity fields
@@ -45,6 +80,9 @@ export class RlsPolicy extends BasePgModel {
         this.with_check_expression = props.with_check_expression;
         this.owner = props.owner;
         this.comment = props.comment;
+        // Derived metadata (not part of equality)
+        this.referenced_relations = props.referenced_relations;
+        this.referenced_procedures = props.referenced_procedures;
     }
     get stableId() {
         return `rlsPolicy:${this.schema}.${this.table_name}.${this.name}`;
@@ -88,6 +126,59 @@ extension_table_oids as (
     d.refclassid = 'pg_extension'::regclass
     and d.classid = 'pg_class'::regclass
     and d.deptype = 'e'
+),
+policy_relation_deps as (
+  -- Relations referenced inside polqual / polwithcheck. PostgreSQL records
+  -- these via recordDependencyOnExpr(..., DEPENDENCY_NORMAL = 'n') at
+  -- CREATE POLICY time, so pg_depend is authoritative and we don't need to
+  -- re-parse the expression text. Covers regular tables, partitioned
+  -- tables, views, materialized views, and foreign tables — any relation
+  -- kind the policy can reference in a subquery.
+  select distinct
+    d.objid                 as policy_oid,
+    case ref_c.relkind
+      when 'r' then 'table'
+      when 'p' then 'table'
+      when 'v' then 'view'
+      when 'm' then 'materialized_view'
+      when 'f' then 'foreign_table'
+    end                     as ref_kind,
+    ref_ns.nspname          as ref_schema,
+    ref_c.relname           as ref_name
+  from
+    pg_depend d
+    join pg_policy p on p.oid = d.objid
+    join pg_class ref_c on ref_c.oid = d.refobjid
+    join pg_namespace ref_ns on ref_ns.oid = ref_c.relnamespace
+  where
+    d.classid = 'pg_policy'::regclass
+    and d.refclassid = 'pg_class'::regclass
+    and d.deptype = 'n'
+    and ref_c.relkind in ('r', 'p', 'v', 'm', 'f')
+    and d.refobjid <> p.polrelid
+),
+policy_procedure_deps as (
+  -- Functions / procedures referenced inside polqual / polwithcheck. Same
+  -- pg_depend mechanism as above, just refclassid = pg_proc. proargtypes
+  -- formatted via format_type(oid, null) matches the signature produced by
+  -- the procedure extractor (see procedure.model.ts), so stableId.procedure
+  -- on both sides of the diff lines up exactly.
+  select distinct
+    d.objid            as policy_oid,
+    ref_ns.nspname     as ref_schema,
+    ref_p.proname      as ref_name,
+    array(
+      select format_type(oid, null)
+      from unnest(ref_p.proargtypes) as oid
+    )                  as ref_argument_types
+  from
+    pg_depend d
+    join pg_proc ref_p on ref_p.oid = d.refobjid
+    join pg_namespace ref_ns on ref_ns.oid = ref_p.pronamespace
+  where
+    d.classid = 'pg_policy'::regclass
+    and d.refclassid = 'pg_proc'::regclass
+    and d.deptype = 'n'
 )
 select
   tc.relnamespace::regnamespace::text as schema,
@@ -107,7 +198,37 @@ select
   pg_get_expr(p.polqual, p.polrelid) as using_expression,
   pg_get_expr(p.polwithcheck, p.polrelid) as with_check_expression,
   tc.relowner::regrole::text as owner,
-  obj_description(p.oid, 'pg_policy') as comment
+  obj_description(p.oid, 'pg_policy') as comment,
+  coalesce(
+    (
+      select json_agg(
+        json_build_object(
+          'kind', prd.ref_kind,
+          'schema', prd.ref_schema,
+          'name', prd.ref_name
+        )
+        order by prd.ref_schema, prd.ref_name
+      )
+      from policy_relation_deps prd
+      where prd.policy_oid = p.oid
+    ),
+    '[]'
+  ) as referenced_relations,
+  coalesce(
+    (
+      select json_agg(
+        json_build_object(
+          'schema', ppd.ref_schema,
+          'name', ppd.ref_name,
+          'argument_types', ppd.ref_argument_types
+        )
+        order by ppd.ref_schema, ppd.ref_name, ppd.ref_argument_types
+      )
+      from policy_procedure_deps ppd
+      where ppd.policy_oid = p.oid
+    ),
+    '[]'
+  ) as referenced_procedures
 from
   pg_catalog.pg_policy p
   inner join pg_catalog.pg_class tc on tc.oid = p.polrelid

package/dist/core/plan/sql-format/fixtures.js

@@ -696,6 +696,8 @@ const rlsPolicy = new RlsPolicy({
     with_check_expression: null,
     owner: "owner1",
     comment: "rls policy comment",
+    referenced_relations: [],
+    referenced_procedures: [],
 });
 const rlsPolicyRestrictive = new RlsPolicy({
     schema: "public",
@@ -708,6 +710,8 @@ const rlsPolicyRestrictive = new RlsPolicy({
     with_check_expression: "status <> 'locked'",
     owner: "owner1",
     comment: null,
+    referenced_relations: [],
+    referenced_procedures: [],
 });
 const index = new Index({
     schema: "public",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.18",
+  "version": "1.0.0-alpha.19",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,

package/src/core/catalog.snapshot.test.ts

@@ -428,6 +428,8 @@ describe("catalog snapshot serde", () => {
       with_check_expression: null,
       owner: "postgres",
       comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
     });
 
     const target = new Catalog({

package/src/core/expand-replace-dependencies.ts

@@ -2,6 +2,8 @@ import type { Catalog } from "./catalog.model.ts";
 import type { Change } from "./change.types.ts";
 import { CreateDomain } from "./objects/domain/changes/domain.create.ts";
 import { DropDomain } from "./objects/domain/changes/domain.drop.ts";
+import { CreateIndex } from "./objects/index/changes/index.create.ts";
+import { DropIndex } from "./objects/index/changes/index.drop.ts";
 import { CreateMaterializedView } from "./objects/materialized-view/changes/materialized-view.create.ts";
 import { DropMaterializedView } from "./objects/materialized-view/changes/materialized-view.drop.ts";
 import { CreateProcedure } from "./objects/procedure/changes/procedure.create.ts";
@@ -34,6 +36,12 @@ type ResolvedObject =
       main: Catalog["views"][string];
       branch: Catalog["views"][string];
     }
+  | {
+      kind: "index";
+      main: Catalog["indexes"][string];
+      branch: Catalog["indexes"][string];
+      branchIndexableObject: Catalog["indexableObjects"][string] | undefined;
+    }
   | {
       kind: "materialized_view";
       main: Catalog["materializedViews"][string];
@@ -346,6 +354,20 @@ function resolveObjectForStableId(
     return main && branch ? { kind: "materialized_view", main, branch } : null;
   }
 
+  if (stableId.startsWith("index:")) {
+    const main = mainCatalog.indexes[stableId];
+    const branch = branchCatalog.indexes[stableId];
+    return main && branch
+      ? {
+          kind: "index",
+          main,
+          branch,
+          branchIndexableObject:
+            branchCatalog.indexableObjects[branch.tableStableId],
+        }
+      : null;
+  }
+
   if (stableId.startsWith("procedure:")) {
     const main = mainCatalog.procedures[stableId];
     const branch = branchCatalog.procedures[stableId];
@@ -447,6 +469,36 @@ function buildReplaceChanges(
           ? [new CreateMaterializedView({ materializedView: resolved.branch })]
           : []),
       ];
+    case "index":
+      // Constraint-owned, primary, and partition-attached indexes are managed
+      // by the owning constraint or parent-index DDL, not standalone
+      // CREATE INDEX / DROP INDEX. The `case "table":` branch above already
+      // recreates constraints via AlterTableAddConstraint; emitting a
+      // standalone drop/create here would fail in PostgreSQL
+      // ("cannot drop index ... because constraint ... requires it") or
+      // duplicate the index the constraint recreates. Skip matches
+      // diffIndexes (packages/pg-delta/src/core/objects/index/index.diff.ts).
+      if (
+        resolved.main.is_owned_by_constraint ||
+        resolved.main.is_primary ||
+        resolved.main.is_index_partition ||
+        resolved.branch.is_owned_by_constraint ||
+        resolved.branch.is_primary ||
+        resolved.branch.is_index_partition
+      ) {
+        return null;
+      }
+      return [
+        ...(addDrop ? [new DropIndex({ index: resolved.main })] : []),
+        ...(addCreate
+          ? [
+              new CreateIndex({
+                index: resolved.branch,
+                indexableObject: resolved.branchIndexableObject,
+              }),
+            ]
+          : []),
+      ];
     case "procedure":
       return [
         ...(addDrop ? [new DropProcedure({ procedure: resolved.main })] : []),

package/src/core/objects/index/index.model.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import type { Pool } from "pg";
+import { extractIndexes, Index } from "./index.model.ts";
+
+// Minimal fields required by indexPropsSchema; individual tests override the
+// fields relevant to each scenario.
+const baseRow = {
+  schema: "public",
+  table_name: '"users"',
+  storage_params: [] as string[],
+  statistics_target: [] as number[],
+  index_type: "btree",
+  tablespace: null,
+  is_unique: false,
+  is_primary: false,
+  is_exclusion: false,
+  nulls_not_distinct: false,
+  immediate: true,
+  is_clustered: false,
+  is_replica_identity: false,
+  key_columns: [1],
+  column_collations: [null],
+  operator_classes: ["default"],
+  column_options: [0],
+  index_expressions: null,
+  partial_predicate: null,
+  is_owned_by_constraint: false,
+  table_relkind: "r" as const,
+  is_partitioned_index: false,
+  is_index_partition: false,
+  parent_index_name: null,
+  comment: null,
+  owner: "postgres",
+};
+
+const mockPool = (rows: unknown[]): Pool =>
+  ({ query: async () => ({ rows }) }) as unknown as Pool;
+
+describe("extractIndexes", () => {
+  test("skips rows where pg_get_indexdef returned NULL", async () => {
+    const indexes = await extractIndexes(
+      mockPool([
+        {
+          ...baseRow,
+          name: '"good_idx"',
+          definition: "CREATE INDEX good_idx ON users (id)",
+        },
+        { ...baseRow, name: '"orphan_idx"', definition: null },
+      ]),
+    );
+
+    expect(indexes).toHaveLength(1);
+    expect(indexes[0]).toBeInstanceOf(Index);
+    expect(indexes[0]?.name).toBe('"good_idx"');
+    expect(indexes[0]?.definition).toBe("CREATE INDEX good_idx ON users (id)");
+  });
+
+  test("does not throw ZodError when the only row has a null definition", async () => {
+    await expect(
+      extractIndexes(
+        mockPool([{ ...baseRow, name: '"orphan"', definition: null }]),
+      ),
+    ).resolves.toEqual([]);
+  });
+
+  test("returns all indexes when every row has a valid definition", async () => {
+    const indexes = await extractIndexes(
+      mockPool([
+        {
+          ...baseRow,
+          name: '"a"',
+          definition: "CREATE INDEX a ON users (id)",
+        },
+        {
+          ...baseRow,
+          name: '"b"',
+          definition: "CREATE INDEX b ON users (id)",
+        },
+      ]),
+    );
+    expect(indexes.map((i) => i.name)).toEqual(['"a"', '"b"']);
+  });
+});

package/src/core/objects/index/index.model.ts

@@ -40,6 +40,16 @@ const indexPropsSchema = z.object({
   owner: z.string(),
 });
 
+// pg_get_indexdef(oid, colno, pretty) invokes pg_get_indexdef_worker with
+// missing_ok = true, so it can return NULL when any internal system-cache lookup
+// fails (race with concurrent DROP, role visibility edge cases, orphaned index
+// metadata, recovery transients). An unreadable index cannot be diffed, so we
+// accept NULL here and filter the row out with a debug log instead of crashing
+// the whole catalog extraction.
+const indexRowSchema = indexPropsSchema.extend({
+  definition: z.string().nullable(),
+});
+
 /**
  * All properties exposed by CREATE INDEX statement are included in diff output.
  * https://www.postgresql.org/docs/current/sql-createindex.html
@@ -362,9 +372,8 @@ export async function extractIndexes(pool: Pool): Promise<Index[]> {
 
       order by 1, 2
   `);
-  // Validate and parse each row using the Zod schema
-  const validatedRows = indexRows.map((row: unknown) =>
-    indexPropsSchema.parse(row),
-  );
+  const validatedRows = indexRows
+    .map((row: unknown) => indexRowSchema.parse(row))
+    .filter((row): row is IndexProps => row.definition !== null);
   return validatedRows.map((row: IndexProps) => new Index(row));
 }

package/src/core/objects/rls-policy/changes/rls-policy.alter.test.ts

@@ -23,6 +23,8 @@ describe.concurrent("rls-policy", () => {
         with_check_expression: null,
         owner: "owner",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const policy = new RlsPolicy({
         ...props,
@@ -52,6 +54,8 @@ describe.concurrent("rls-policy", () => {
         with_check_expression: null,
         owner: "owner",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const policy = new RlsPolicy({
         ...props,
@@ -81,6 +85,8 @@ describe.concurrent("rls-policy", () => {
         with_check_expression: null,
         owner: "owner",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const main = new RlsPolicy({
         ...props,
@@ -120,6 +126,8 @@ describe.concurrent("rls-policy", () => {
         with_check_expression: null,
         owner: "owner",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const main = new RlsPolicy({
         ...props,
@@ -159,6 +167,8 @@ describe.concurrent("rls-policy", () => {
         with_check_expression: null,
         owner: "test",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const policy = new RlsPolicy({
         ...props,
@@ -188,6 +198,8 @@ describe.concurrent("rls-policy", () => {
         with_check_expression: null,
         owner: "test",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const policy = new RlsPolicy({
         ...props,
@@ -217,6 +229,8 @@ describe.concurrent("rls-policy", () => {
         using_expression: "expr",
         owner: "test",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const policy = new RlsPolicy({
         ...props,
@@ -246,6 +260,8 @@ describe.concurrent("rls-policy", () => {
         using_expression: "expr",
         owner: "test",
         comment: null,
+        referenced_relations: [],
+        referenced_procedures: [],
       };
       const policy = new RlsPolicy({
         ...props,

package/src/core/objects/rls-policy/changes/rls-policy.create.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { assertValidSql } from "../../../test-utils/assert-valid-sql.ts";
+import { stableId } from "../../utils.ts";
 import { RlsPolicy } from "../rls-policy.model.ts";
 import { CreateRlsPolicy } from "./rls-policy.create.ts";
 
@@ -16,6 +17,8 @@ describe("rls-policy", () => {
       with_check_expression: null,
       owner: "test",
       comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
     });
 
     const change = new CreateRlsPolicy({
@@ -41,6 +44,8 @@ describe("rls-policy", () => {
       with_check_expression: null,
       owner: "test",
       comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
     });
 
     const change = new CreateRlsPolicy({
@@ -66,6 +71,8 @@ describe("rls-policy", () => {
       with_check_expression: "expr2",
       owner: "test",
       comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
     });
 
     const change = new CreateRlsPolicy({
@@ -78,4 +85,125 @@ describe("rls-policy", () => {
       "CREATE POLICY test_policy_all ON public.test_table AS RESTRICTIVE FOR UPDATE TO role1, role2 USING (expr1) WITH CHECK (expr2)",
     );
   });
+
+  test("requires referenced relations reported by pg_depend", () => {
+    const policy = new RlsPolicy({
+      schema: "app",
+      name: "cross_relation_policy",
+      table_name: "accounts",
+      command: "r",
+      permissive: true,
+      roles: ["public"],
+      using_expression:
+        "(EXISTS (SELECT 1 FROM app.users) AND EXISTS (SELECT 1 FROM app.active_accounts))",
+      with_check_expression:
+        "(id IN (SELECT account_id FROM app.memberships WHERE active))",
+      owner: "test",
+      comment: null,
+      referenced_relations: [
+        { kind: "table", schema: "app", name: "users" },
+        { kind: "table", schema: "app", name: "memberships" },
+        { kind: "view", schema: "app", name: "active_accounts" },
+        { kind: "materialized_view", schema: "app", name: "account_stats" },
+        { kind: "foreign_table", schema: "app", name: "remote_profiles" },
+      ],
+      referenced_procedures: [],
+    });
+
+    const change = new CreateRlsPolicy({ policy });
+
+    expect(change.requires).toContain(stableId.table("app", "users"));
+    expect(change.requires).toContain(stableId.table("app", "memberships"));
+    expect(change.requires).toContain(stableId.view("app", "active_accounts"));
+    expect(change.requires).toContain(
+      stableId.materializedView("app", "account_stats"),
+    );
+    expect(change.requires).toContain(
+      stableId.foreignTable("app", "remote_profiles"),
+    );
+  });
+
+  test("requires referenced procedures reported by pg_depend", () => {
+    const policy = new RlsPolicy({
+      schema: "app",
+      name: "function_guarded_policy",
+      table_name: "accounts",
+      command: "r",
+      permissive: true,
+      roles: ["public"],
+      using_expression: "public.is_admin()",
+      with_check_expression: null,
+      owner: "test",
+      comment: null,
+      referenced_relations: [],
+      referenced_procedures: [
+        { schema: "public", name: "is_admin", argument_types: [] },
+        {
+          schema: "public",
+          name: "has_role",
+          argument_types: ["text", "integer"],
+        },
+      ],
+    });
+
+    const change = new CreateRlsPolicy({ policy });
+
+    expect(change.requires).toContain(stableId.procedure("public", "is_admin"));
+    expect(change.requires).toContain(
+      stableId.procedure("public", "has_role", "text,integer"),
+    );
+  });
+
+  test("does not require additional objects when referenced lists are empty", () => {
+    const policy = new RlsPolicy({
+      schema: "app",
+      name: "simple_policy",
+      table_name: "accounts",
+      command: "*",
+      permissive: true,
+      roles: [],
+      using_expression: null,
+      with_check_expression: null,
+      owner: "test",
+      comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
+    });
+
+    const change = new CreateRlsPolicy({ policy });
+
+    expect(change.requires).toEqual([
+      stableId.schema("app"),
+      stableId.table("app", "accounts"),
+      stableId.role("test"),
+    ]);
+  });
+
+  // Sequences referenced via nextval() are a known gap. pg_depend only
+  // records the sequence edge when the argument is written as a regclass
+  // literal (e.g. `nextval('app.seq'::regclass)`); bare string literals
+  // produce no pg_depend row. Tracked in
+  // https://github.com/supabase/pg-toolbelt/issues/220.
+  test.skip("requires referenced sequences (follow-up)", () => {
+    const policy = new RlsPolicy({
+      schema: "app",
+      name: "sequence_policy",
+      table_name: "accounts",
+      command: "r",
+      permissive: true,
+      roles: ["public"],
+      using_expression: "id < nextval('app.next_id'::regclass)",
+      with_check_expression: null,
+      owner: "test",
+      comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
+    });
+
+    const change = new CreateRlsPolicy({ policy });
+
+    // Expected once the gap is closed:
+    //   expect(change.requires).toContain(stableId.sequence("app", "next_id"));
+    expect(change.requires.length).toBeGreaterThan(0);
+  });
 });

package/src/core/objects/rls-policy/changes/rls-policy.create.ts

@@ -45,6 +45,33 @@ export class CreateRlsPolicy extends CreateRlsPolicyChange {
     // Owner dependency
     dependencies.add(stableId.role(this.policy.owner));
 
+    // Relations and functions referenced inside USING / WITH CHECK
+    // expressions must exist before the policy is created. These come from
+    // pg_depend (populated by PostgreSQL's recordDependencyOnExpr at policy
+    // creation), not from re-parsing the expression text.
+    for (const ref of this.policy.referenced_relations) {
+      switch (ref.kind) {
+        case "table":
+          dependencies.add(stableId.table(ref.schema, ref.name));
+          break;
+        case "view":
+          dependencies.add(stableId.view(ref.schema, ref.name));
+          break;
+        case "materialized_view":
+          dependencies.add(stableId.materializedView(ref.schema, ref.name));
+          break;
+        case "foreign_table":
+          dependencies.add(stableId.foreignTable(ref.schema, ref.name));
+          break;
+      }
+    }
+
+    for (const ref of this.policy.referenced_procedures) {
+      dependencies.add(
+        stableId.procedure(ref.schema, ref.name, ref.argument_types.join(",")),
+      );
+    }
+
     return Array.from(dependencies);
   }
 

package/src/core/objects/rls-policy/changes/rls-policy.drop.test.ts

@@ -16,6 +16,8 @@ describe("rls-policy", () => {
       with_check_expression: null,
       owner: "test",
       comment: null,
+      referenced_relations: [],
+      referenced_procedures: [],
     });
 
     const change = new DropRlsPolicy({

package/src/core/objects/rls-policy/rls-policy.diff.test.ts

@@ -20,6 +20,8 @@ const base: RlsPolicyProps = {
   with_check_expression: null,
   owner: "o1",
   comment: null,
+  referenced_relations: [],
+  referenced_procedures: [],
 };
 
 describe.concurrent("rls-policy.diff", () => {

package/src/core/objects/rls-policy/rls-policy.model.ts

@@ -11,6 +11,33 @@ const RlsPolicyCommandSchema = z.enum([
   "*", // ALL commands
 ]);
 
+const RlsPolicyReferencedRelationKindSchema = z.enum([
+  "table",
+  "view",
+  "materialized_view",
+  "foreign_table",
+]);
+
+const rlsPolicyReferencedRelationSchema = z.object({
+  kind: RlsPolicyReferencedRelationKindSchema,
+  schema: z.string(),
+  name: z.string(),
+});
+
+export type RlsPolicyReferencedRelation = z.infer<
+  typeof rlsPolicyReferencedRelationSchema
+>;
+
+const rlsPolicyReferencedProcedureSchema = z.object({
+  schema: z.string(),
+  name: z.string(),
+  argument_types: z.array(z.string()),
+});
+
+export type RlsPolicyReferencedProcedure = z.infer<
+  typeof rlsPolicyReferencedProcedureSchema
+>;
+
 const rlsPolicyPropsSchema = z.object({
   schema: z.string(),
   name: z.string(),
@@ -22,6 +49,8 @@ const rlsPolicyPropsSchema = z.object({
   with_check_expression: z.string().nullable(),
   owner: z.string(),
   comment: z.string().nullable(),
+  referenced_relations: z.array(rlsPolicyReferencedRelationSchema),
+  referenced_procedures: z.array(rlsPolicyReferencedProcedureSchema),
 });
 
 export type RlsPolicyProps = z.infer<typeof rlsPolicyPropsSchema>;
@@ -37,6 +66,23 @@ export class RlsPolicy extends BasePgModel {
   public readonly with_check_expression: RlsPolicyProps["with_check_expression"];
   public readonly owner: RlsPolicyProps["owner"];
   public readonly comment: RlsPolicyProps["comment"];
+  /**
+   * Tables / views / materialized views / foreign tables that
+   * `using_expression` / `with_check_expression` reference, sourced from
+   * `pg_depend` (`recordDependencyOnExpr` at policy creation). Drives
+   * ordering dependencies in `CreateRlsPolicy.requires`. Intentionally
+   * excluded from `dataFields` — it's derived from the expression text
+   * and changes lockstep with it.
+   */
+  public readonly referenced_relations: RlsPolicyProps["referenced_relations"];
+  /**
+   * Functions / procedures that `using_expression` / `with_check_expression`
+   * reference, sourced from `pg_depend` (refclassid = `pg_proc`). The
+   * argument-type signature comes straight from `pg_proc.proargtypes` via
+   * `format_type`, so it matches the signature the procedure extractor
+   * embeds in `stableId.procedure(...)`. Not part of `dataFields`.
+   */
+  public readonly referenced_procedures: RlsPolicyProps["referenced_procedures"];
 
   constructor(props: RlsPolicyProps) {
     super();
@@ -54,6 +100,10 @@ export class RlsPolicy extends BasePgModel {
     this.with_check_expression = props.with_check_expression;
     this.owner = props.owner;
     this.comment = props.comment;
+
+    // Derived metadata (not part of equality)
+    this.referenced_relations = props.referenced_relations;
+    this.referenced_procedures = props.referenced_procedures;
   }
 
   get stableId(): `rlsPolicy:${string}` {
@@ -101,6 +151,59 @@ extension_table_oids as (
     d.refclassid = 'pg_extension'::regclass
     and d.classid = 'pg_class'::regclass
     and d.deptype = 'e'
+),
+policy_relation_deps as (
+  -- Relations referenced inside polqual / polwithcheck. PostgreSQL records
+  -- these via recordDependencyOnExpr(..., DEPENDENCY_NORMAL = 'n') at
+  -- CREATE POLICY time, so pg_depend is authoritative and we don't need to
+  -- re-parse the expression text. Covers regular tables, partitioned
+  -- tables, views, materialized views, and foreign tables — any relation
+  -- kind the policy can reference in a subquery.
+  select distinct
+    d.objid                 as policy_oid,
+    case ref_c.relkind
+      when 'r' then 'table'
+      when 'p' then 'table'
+      when 'v' then 'view'
+      when 'm' then 'materialized_view'
+      when 'f' then 'foreign_table'
+    end                     as ref_kind,
+    ref_ns.nspname          as ref_schema,
+    ref_c.relname           as ref_name
+  from
+    pg_depend d
+    join pg_policy p on p.oid = d.objid
+    join pg_class ref_c on ref_c.oid = d.refobjid
+    join pg_namespace ref_ns on ref_ns.oid = ref_c.relnamespace
+  where
+    d.classid = 'pg_policy'::regclass
+    and d.refclassid = 'pg_class'::regclass
+    and d.deptype = 'n'
+    and ref_c.relkind in ('r', 'p', 'v', 'm', 'f')
+    and d.refobjid <> p.polrelid
+),
+policy_procedure_deps as (
+  -- Functions / procedures referenced inside polqual / polwithcheck. Same
+  -- pg_depend mechanism as above, just refclassid = pg_proc. proargtypes
+  -- formatted via format_type(oid, null) matches the signature produced by
+  -- the procedure extractor (see procedure.model.ts), so stableId.procedure
+  -- on both sides of the diff lines up exactly.
+  select distinct
+    d.objid            as policy_oid,
+    ref_ns.nspname     as ref_schema,
+    ref_p.proname      as ref_name,
+    array(
+      select format_type(oid, null)
+      from unnest(ref_p.proargtypes) as oid
+    )                  as ref_argument_types
+  from
+    pg_depend d
+    join pg_proc ref_p on ref_p.oid = d.refobjid
+    join pg_namespace ref_ns on ref_ns.oid = ref_p.pronamespace
+  where
+    d.classid = 'pg_policy'::regclass
+    and d.refclassid = 'pg_proc'::regclass
+    and d.deptype = 'n'
 )
 select
   tc.relnamespace::regnamespace::text as schema,
@@ -120,7 +223,37 @@ select
   pg_get_expr(p.polqual, p.polrelid) as using_expression,
   pg_get_expr(p.polwithcheck, p.polrelid) as with_check_expression,
   tc.relowner::regrole::text as owner,
-  obj_description(p.oid, 'pg_policy') as comment
+  obj_description(p.oid, 'pg_policy') as comment,
+  coalesce(
+    (
+      select json_agg(
+        json_build_object(
+          'kind', prd.ref_kind,
+          'schema', prd.ref_schema,
+          'name', prd.ref_name
+        )
+        order by prd.ref_schema, prd.ref_name
+      )
+      from policy_relation_deps prd
+      where prd.policy_oid = p.oid
+    ),
+    '[]'
+  ) as referenced_relations,
+  coalesce(
+    (
+      select json_agg(
+        json_build_object(
+          'schema', ppd.ref_schema,
+          'name', ppd.ref_name,
+          'argument_types', ppd.ref_argument_types
+        )
+        order by ppd.ref_schema, ppd.ref_name, ppd.ref_argument_types
+      )
+      from policy_procedure_deps ppd
+      where ppd.policy_oid = p.oid
+    ),
+    '[]'
+  ) as referenced_procedures
 from
   pg_catalog.pg_policy p
   inner join pg_catalog.pg_class tc on tc.oid = p.polrelid

package/src/core/plan/sql-format/fixtures.ts

@@ -1000,6 +1000,8 @@ const rlsPolicy = new RlsPolicy({
   with_check_expression: null,
   owner: "owner1",
   comment: "rls policy comment",
+  referenced_relations: [],
+  referenced_procedures: [],
 });
 
 const rlsPolicyRestrictive = new RlsPolicy({
@@ -1013,6 +1015,8 @@ const rlsPolicyRestrictive = new RlsPolicy({
   with_check_expression: "status <> 'locked'",
   owner: "owner1",
   comment: null,
+  referenced_relations: [],
+  referenced_procedures: [],
 });
 
 const index = new Index({