@prisma-next/target-postgres 0.14.0-dev.6 → 0.14.0-dev.61

package/src/core/psl-infer/postgres-default-mapping.ts

@@ -0,0 +1,16 @@
+import type { DefaultMappingOptions } from '@prisma-next/family-sql/psl-infer';
+
+const POSTGRES_FUNCTION_ATTRIBUTES: Readonly<Record<string, string>> = {
+  'gen_random_uuid()': '@default(dbgenerated("gen_random_uuid()"))',
+};
+
+function formatDbGeneratedAttribute(expression: string): string {
+  return `@default(dbgenerated(${JSON.stringify(expression)}))`;
+}
+
+export function createPostgresDefaultMapping(): DefaultMappingOptions {
+  return {
+    functionAttributes: POSTGRES_FUNCTION_ATTRIBUTES,
+    fallbackFunctionAttribute: formatDbGeneratedAttribute,
+  };
+}

package/src/core/psl-infer/postgres-type-map.ts

@@ -0,0 +1,128 @@
+import type {
+  PslNativeTypeAttribute,
+  PslTypeMap,
+  PslTypeResolution,
+} from '@prisma-next/family-sql/psl-infer';
+
+const POSTGRES_TO_PSL: Record<string, string> = {
+  text: 'String',
+  bool: 'Boolean',
+  boolean: 'Boolean',
+  int4: 'Int',
+  integer: 'Int',
+  int8: 'BigInt',
+  bigint: 'BigInt',
+  float8: 'Float',
+  'double precision': 'Float',
+  numeric: 'Decimal',
+  decimal: 'Decimal',
+  timestamptz: 'DateTime',
+  'timestamp with time zone': 'DateTime',
+  jsonb: 'Json',
+  bytea: 'Bytes',
+};
+
+const PRESERVED_NATIVE_TYPES: Record<
+  string,
+  { readonly pslType: string; readonly attributeName: string }
+> = {
+  'character varying': { pslType: 'String', attributeName: 'db.VarChar' },
+  character: { pslType: 'String', attributeName: 'db.Char' },
+  char: { pslType: 'String', attributeName: 'db.Char' },
+  varchar: { pslType: 'String', attributeName: 'db.VarChar' },
+  uuid: { pslType: 'String', attributeName: 'db.Uuid' },
+  int2: { pslType: 'Int', attributeName: 'db.SmallInt' },
+  smallint: { pslType: 'Int', attributeName: 'db.SmallInt' },
+  float4: { pslType: 'Float', attributeName: 'db.Real' },
+  real: { pslType: 'Float', attributeName: 'db.Real' },
+  timestamp: { pslType: 'DateTime', attributeName: 'db.Timestamp' },
+  'timestamp without time zone': { pslType: 'DateTime', attributeName: 'db.Timestamp' },
+  date: { pslType: 'DateTime', attributeName: 'db.Date' },
+  time: { pslType: 'DateTime', attributeName: 'db.Time' },
+  'time without time zone': { pslType: 'DateTime', attributeName: 'db.Time' },
+  timetz: { pslType: 'DateTime', attributeName: 'db.Timetz' },
+  'time with time zone': { pslType: 'DateTime', attributeName: 'db.Timetz' },
+  json: { pslType: 'Json', attributeName: 'db.Json' },
+};
+
+const PARAMETERIZED_NATIVE_TYPES: Record<
+  string,
+  { readonly pslType: string; readonly attributeName: string }
+> = {
+  'character varying': { pslType: 'String', attributeName: 'db.VarChar' },
+  character: { pslType: 'String', attributeName: 'db.Char' },
+  char: { pslType: 'String', attributeName: 'db.Char' },
+  varchar: { pslType: 'String', attributeName: 'db.VarChar' },
+  numeric: { pslType: 'Decimal', attributeName: 'db.Numeric' },
+  timestamp: { pslType: 'DateTime', attributeName: 'db.Timestamp' },
+  timestamptz: { pslType: 'DateTime', attributeName: 'db.Timestamptz' },
+  time: { pslType: 'DateTime', attributeName: 'db.Time' },
+  timetz: { pslType: 'DateTime', attributeName: 'db.Timetz' },
+};
+
+const PARAMETERIZED_TYPE_PATTERN = /^(.+?)\((.+)\)$/;
+
+function getOwnMappingValue(map: Record<string, string>, key: string): string | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+
+function getOwnRecordValue<T>(map: Record<string, T>, key: string): T | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+
+function createNativeTypeAttribute(name: string, args?: readonly string[]): PslNativeTypeAttribute {
+  return args && args.length > 0 ? { name, args } : { name };
+}
+
+function splitTypeParameterList(params: string): readonly string[] {
+  return params
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+export function createPostgresTypeMap(enumTypeNames?: ReadonlySet<string>): PslTypeMap {
+  return {
+    resolve(nativeType: string): PslTypeResolution {
+      if (enumTypeNames?.has(nativeType)) {
+        return { pslType: nativeType, nativeType };
+      }
+
+      const paramMatch = nativeType.match(PARAMETERIZED_TYPE_PATTERN);
+      if (paramMatch) {
+        const [, baseType = nativeType, params = ''] = paramMatch;
+        const template = getOwnRecordValue(PARAMETERIZED_NATIVE_TYPES, baseType);
+        if (template) {
+          return {
+            pslType: template.pslType,
+            nativeType,
+            typeParams: { baseType, params },
+            nativeTypeAttribute: createNativeTypeAttribute(
+              template.attributeName,
+              splitTypeParameterList(params),
+            ),
+          };
+        }
+      }
+
+      const preservedType = getOwnRecordValue(PRESERVED_NATIVE_TYPES, nativeType);
+      if (preservedType) {
+        return {
+          pslType: preservedType.pslType,
+          nativeType,
+          nativeTypeAttribute: createNativeTypeAttribute(preservedType.attributeName),
+        };
+      }
+
+      const pslType = getOwnMappingValue(POSTGRES_TO_PSL, nativeType);
+      if (pslType) {
+        return {
+          pslType,
+          nativeType,
+        };
+      }
+
+      return { unsupported: true, nativeType };
+    },
+  };
+}

package/src/core/rls/canonicalize.ts

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+
+export type RlsPolicyOperation = 'select' | 'insert' | 'update' | 'delete' | 'all';
+
+export interface ContentHashParts {
+  readonly using?: string;
+  readonly withCheck?: string;
+  readonly roles: readonly string[];
+  readonly operation: RlsPolicyOperation;
+  readonly permissive: boolean;
+}
+
+/**
+ * Stabilizes an authored predicate for hashing: trim, and collapse runs of
+ * internal whitespace to a single space.
+ *
+ * This is deliberately minimal. The content hash is the equivalence relation
+ * for a policy, and the wire name (prefix + hash) is the only thing ever
+ * compared — we never recompute the hash from an introspected policy body, so
+ * there is no need to match Postgres's reprinted form. Minimal normalization
+ * also protects the no-collision property: aggressive rewriting (lowercasing,
+ * paren-stripping, cast-alias folding) risks collapsing two distinct predicates
+ * onto one hash. Out-of-band alteration of a hashed policy is unsupported.
+ *
+ * The normalizer is a stability commitment: any change re-suffixes all wire names.
+ */
+export function normalizePredicate(sql: string): string {
+  return sql.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Returns the first 8 lowercase hex characters of the SHA-256 digest over the
+ * canonical content tuple for an RLS policy:
+ *
+ *   [normalize(using), normalize(withCheck), sortedRoles, operation, permissive]
+ *
+ * Schema and table are excluded (they are orthogonal to policy equivalence).
+ * Uses `JSON.stringify` for a deterministic encoding.
+ */
+export function computeContentHash(parts: ContentHashParts): string {
+  const using = normalizePredicate(parts.using ?? '');
+  const withCheck = normalizePredicate(parts.withCheck ?? '');
+  const roles = [...new Set(parts.roles)].sort();
+  const permissive = parts.permissive ? 'permissive' : 'restrictive';
+
+  const tuple = JSON.stringify([using, withCheck, roles, parts.operation, permissive]);
+  return createHash('sha256').update(tuple).digest('hex').slice(0, 8);
+}

package/src/core/rls/wire-name.ts

@@ -0,0 +1,33 @@
+export interface RlsPolicyWireName {
+  /** The user-supplied part before the `_<8hex>` suffix. */
+  readonly prefix: string;
+  /** The 8-lowercase-hex content-hash suffix. */
+  readonly hash: string;
+}
+
+const WIRE_NAME_PATTERN = /^(.+)_([0-9a-f]{8})$/;
+
+/**
+ * Assembles an RLS policy wire name from its user-supplied prefix and its
+ * 8-hex content-hash suffix. This module owns the `<prefix>_<hash>` format
+ * on both sides — construction here and parsing in
+ * {@link parseRlsPolicyWireName} — so the two never drift.
+ */
+export function formatRlsPolicyWireName(prefix: string, hash: string): string {
+  return `${prefix}_${hash}`;
+}
+
+/**
+ * Splits an RLS policy wire name (`<prefix>_<8hex>`) into its prefix and
+ * content-hash suffix. Returns `undefined` when the name does not follow the
+ * wire-name shape (e.g. a policy created outside the toolchain) — callers
+ * treat such names as all-prefix. Consumed by introspection (prefix
+ * extraction) and by rename pairing (same hash, different prefix).
+ */
+export function parseRlsPolicyWireName(name: string): RlsPolicyWireName | undefined {
+  const match = WIRE_NAME_PATTERN.exec(name);
+  const prefix = match?.[1];
+  const hash = match?.[2];
+  if (prefix === undefined || hash === undefined) return undefined;
+  return { prefix, hash };
+}

package/src/core/schema-ir/postgres-database-schema-node.ts

@@ -0,0 +1,61 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import type { PostgresNamespaceSchemaNode } from './postgres-namespace-schema-node';
+import type { PostgresRoleSchemaNode } from './postgres-role-schema-node';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresDatabaseSchemaNodeInput {
+  readonly namespaces: Readonly<Record<string, PostgresNamespaceSchemaNode>>;
+  readonly roles: readonly PostgresRoleSchemaNode[];
+  readonly existingSchemas: readonly string[];
+  readonly pgVersion: string;
+}
+
+/**
+ * The root of the Postgres schema-diff tree: one node per database.
+ *
+ * `id` is the fixed sentinel `'database'` — the root has no siblings and
+ * the value is never emitted into migration paths. `isEqualTo` is identity
+ * (roots always share the `'database'` id). `children()` yields the namespace
+ * nodes followed by the role nodes — both are root-level diff subjects. The
+ * differ pairs siblings by `(nodeKind, id)`, so a role and a namespace may
+ * share a name without colliding.
+ */
+export class PostgresDatabaseSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.database;
+
+  readonly namespaces: Readonly<Record<string, PostgresNamespaceSchemaNode>>;
+  readonly roles: readonly PostgresRoleSchemaNode[];
+  readonly existingSchemas: readonly string[];
+  readonly pgVersion: string;
+
+  constructor(input: PostgresDatabaseSchemaNodeInput) {
+    super();
+    this.namespaces = Object.freeze({ ...input.namespaces });
+    this.roles = Object.freeze([...input.roles]);
+    this.existingSchemas = Object.freeze([...input.existingSchemas]);
+    this.pgVersion = input.pgVersion;
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return 'database';
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    return this.id === other.id;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [...Object.values(this.namespaces), ...this.roles];
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresDatabaseSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.database;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresDatabaseSchemaNode {
+    assertNode(node, 'PostgresDatabaseSchemaNode', PostgresDatabaseSchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-namespace-schema-node.ts

@@ -0,0 +1,79 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import type { PostgresTableSchemaNode } from './postgres-table-schema-node';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+/** One introspected native Postgres enum type, in `pg_enum.enumsortorder` (declaration) order. */
+export interface PostgresNativeEnumIntrospection {
+  readonly typeName: string;
+  readonly values: readonly string[];
+}
+
+export interface PostgresNamespaceSchemaNodeInput {
+  readonly schemaName: string;
+  readonly tables: Readonly<Record<string, PostgresTableSchemaNode>>;
+  readonly nativeEnumTypeNames: readonly string[];
+  readonly nativeEnums?: readonly PostgresNativeEnumIntrospection[];
+}
+
+/**
+ * One-per-Postgres-schema diff-tree node. Groups the tables belonging to a
+ * single namespace. Per-schema consumers (the relational planner,
+ * toSchemaView) read this node's `tables` field structurally via
+ * `blindCast`/`SqlSchemaIRNode` — not through a static `SqlSchemaIR`
+ * assignment — because `nodeKind` now carries this node's own literal
+ * (`postgres-namespace`), distinct from `SqlSchemaIR`'s own (`sql-schema`).
+ *
+ * `id` is the schema name. `isEqualTo` is identity — two namespace nodes are
+ * equal iff their ids (schema names) match. `children()` returns the table
+ * nodes. Per-schema metadata is carried on the typed `nativeEnumTypeNames`
+ * field, not an annotations bag.
+ *
+ * `nativeEnums` carries the same enum types with their ordered member
+ * values (`{ typeName, values }`), for consumers that need the values
+ * (PSL inference, the printer). `nativeEnumTypeNames` stays a plain name
+ * list read independently by existing consumers (codec `planTypeOperations`
+ * hooks, the infer throw) so none of them need the values to keep working.
+ */
+export class PostgresNamespaceSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.namespace;
+
+  readonly schemaName: string;
+  readonly tables: Readonly<Record<string, PostgresTableSchemaNode>>;
+  readonly nativeEnumTypeNames: readonly string[];
+  readonly nativeEnums: readonly PostgresNativeEnumIntrospection[];
+
+  constructor(input: PostgresNamespaceSchemaNodeInput) {
+    super();
+    this.schemaName = input.schemaName;
+    this.tables = Object.freeze({ ...input.tables });
+    this.nativeEnumTypeNames = Object.freeze([...input.nativeEnumTypeNames]);
+    this.nativeEnums = Object.freeze(
+      (input.nativeEnums ?? []).map((entry) =>
+        Object.freeze({ typeName: entry.typeName, values: Object.freeze([...entry.values]) }),
+      ),
+    );
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.schemaName;
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    return this.id === other.id;
+  }
+
+  children(): readonly DiffableNode[] {
+    return Object.values(this.tables);
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresNamespaceSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.namespace;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresNamespaceSchemaNode {
+    assertNode(node, 'PostgresNamespaceSchemaNode', PostgresNamespaceSchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-policy-schema-node.ts

@@ -0,0 +1,90 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { RlsPolicyOperation } from '../postgres-rls-policy';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresPolicySchemaNodeInput {
+  /** Full wire name: `<prefix>_<8hex>`. */
+  readonly name: string;
+  /** User-supplied prefix (the part before the `_<8hex>` suffix). */
+  readonly prefix: string;
+  /** Name of the table this policy attaches to, by name within the same schema. */
+  readonly tableName: string;
+  /** Namespace coordinate (schema name). */
+  readonly namespaceId: string;
+  readonly operation: RlsPolicyOperation;
+  /** Sorted role names rendered in `TO <roles>`. */
+  readonly roles: readonly string[];
+  /** USING predicate SQL string, if present. */
+  readonly using?: string;
+  /** WITH CHECK predicate SQL string, if present. */
+  readonly withCheck?: string;
+  /** `true` = `AS PERMISSIVE`, `false` = `AS RESTRICTIVE`. */
+  readonly permissive: boolean;
+}
+
+/**
+ * Schema-diff leaf node for a Postgres row-level security policy.
+ *
+ * This is a derived, transient node walked by the differ — it is NEVER serialized.
+ * Built by project-from-contract and project-from-database from their respective
+ * `PostgresRlsPolicy` contract entities / introspected rows.
+ *
+ * `id` is the wire name (`<prefix>_<sha256(body)[0..8]>`), so name-equality is
+ * body-equality. `isEqualTo` compares names only — never byte-compare predicate
+ * bodies, because Postgres reprints them.
+ */
+export class PostgresPolicySchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.policy;
+
+  readonly name: string;
+  readonly prefix: string;
+  readonly tableName: string;
+  readonly namespaceId: string;
+  readonly operation: RlsPolicyOperation;
+  readonly roles: readonly string[];
+  declare readonly using?: string;
+  declare readonly withCheck?: string;
+  readonly permissive: boolean;
+
+  constructor(input: PostgresPolicySchemaNodeInput) {
+    super();
+    this.name = input.name;
+    this.prefix = input.prefix;
+    this.tableName = input.tableName;
+    this.namespaceId = input.namespaceId;
+    this.operation = input.operation;
+    this.roles = Object.freeze([...input.roles]);
+    if (input.using !== undefined) this.using = input.using;
+    if (input.withCheck !== undefined) this.withCheck = input.withCheck;
+    this.permissive = input.permissive;
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.name;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode; the guard rejects non-policy kinds'
+    >(other);
+    PostgresPolicySchemaNode.assert(node);
+    return this.id === node.id;
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresPolicySchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.policy;
+  }
+
+  static assert(node: SqlSchemaIRNode | undefined): asserts node is PostgresPolicySchemaNode {
+    assertNode(node, 'PostgresPolicySchemaNode', PostgresPolicySchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-role-schema-node.ts

@@ -0,0 +1,65 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { assertNode, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresRoleSchemaNodeInput {
+  readonly name: string;
+  /**
+   * Namespace coordinate. Roles are cluster-scoped; callers pass
+   * `UNBOUND_NAMESPACE_ID` from `@prisma-next/framework-components/ir`.
+   */
+  readonly namespaceId: string;
+}
+
+/**
+ * Schema-diff leaf node for a Postgres database role.
+ *
+ * This is a derived, transient node walked by the differ — it is NEVER serialized.
+ * Built by project-from-contract and project-from-database from their respective
+ * `PostgresRole` contract entities / introspected rows.
+ *
+ * Roles are cluster-scoped, so `id` is the bare role name. The differ pairs
+ * siblings by `(nodeKind, id)`, so a role and a namespace may share a name
+ * (role `public`, schema `public`) without colliding. `isEqualTo` compares
+ * ids — name-equality is role-equality for cluster-scoped objects.
+ */
+export class PostgresRoleSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.role;
+
+  readonly name: string;
+  readonly namespaceId: string;
+
+  constructor(input: PostgresRoleSchemaNodeInput) {
+    super();
+    this.name = input.name;
+    this.namespaceId = input.namespaceId;
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.name;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode; the guard rejects non-role kinds'
+    >(other);
+    PostgresRoleSchemaNode.assert(node);
+    return this.id === node.id;
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresRoleSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.role;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresRoleSchemaNode {
+    assertNode(node, 'PostgresRoleSchemaNode', PostgresRoleSchemaNode.is);
+  }
+}

package/src/core/schema-ir/postgres-table-schema-node.ts

@@ -0,0 +1,140 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import {
+  assertNode,
+  PrimaryKey,
+  type SqlAnnotations,
+  SqlCheckConstraintIR,
+  SqlColumnIR,
+  SqlForeignKeyIR,
+  SqlIndexIR,
+  SqlSchemaIRNode,
+  type SqlTableIRInput,
+  SqlUniqueIR,
+} from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { PostgresPolicySchemaNode } from './postgres-policy-schema-node';
+import { PostgresSchemaNodeKind } from './schema-node-kinds';
+
+export interface PostgresTableSchemaNodeInput extends SqlTableIRInput {
+  readonly policies?: readonly PostgresPolicySchemaNode[];
+  /**
+   * Whether row-level security is enabled on this table. Expected side:
+   * stamped from the contract's `entries.rls` marker (never from the
+   * policy set). Actual side: stamped from `pg_class.relrowsecurity` at
+   * introspection. Required with no default so every construction site
+   * supplies a deliberate value.
+   */
+  readonly rlsEnabled: boolean;
+}
+
+/**
+ * Postgres-specific table schema-diff node. Carries all `SqlTableIR` fields
+ * plus `policies`, and implements `DiffableNode` so the table instance is
+ * directly the diff-tree node — no separate wrapper needed.
+ *
+ * Extends `SqlSchemaIRNode` directly rather than `SqlTableIR` because
+ * `SqlTableIR` calls `freezeNode` in its own constructor, which prevents
+ * subclass field initialisation.
+ *
+ * `id` is the table name. `isEqualTo` compares id + `rlsEnabled` — the
+ * table's one own diffable attribute; all other structural drift is
+ * expressed by its children. `children()` returns every column, the primary
+ * key (when present), every foreign key, unique, index, and check constraint,
+ * plus the policy nodes — one flat list, so a drifted column and a drifted
+ * policy are both reported by the same walk. Order is deterministic (object
+ * key order for columns, array order for the rest) so two structurally equal
+ * tables always produce the same child list.
+ */
+export class PostgresTableSchemaNode extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = PostgresSchemaNodeKind.table;
+
+  readonly name: string;
+  readonly columns: Readonly<Record<string, SqlColumnIR>>;
+  readonly foreignKeys: ReadonlyArray<SqlForeignKeyIR>;
+  readonly uniques: ReadonlyArray<SqlUniqueIR>;
+  readonly indexes: ReadonlyArray<SqlIndexIR>;
+  declare readonly primaryKey?: PrimaryKey;
+  declare readonly annotations?: SqlAnnotations;
+  declare readonly checks?: ReadonlyArray<SqlCheckConstraintIR>;
+  readonly policies: readonly PostgresPolicySchemaNode[];
+  readonly rlsEnabled: boolean;
+
+  constructor(input: PostgresTableSchemaNodeInput) {
+    super();
+    this.name = input.name;
+    this.rlsEnabled = input.rlsEnabled;
+    this.columns = Object.freeze(
+      Object.fromEntries(
+        Object.entries(input.columns).map(([key, col]) => [
+          key,
+          col instanceof SqlColumnIR ? col : new SqlColumnIR(col),
+        ]),
+      ),
+    );
+    this.foreignKeys = Object.freeze(
+      input.foreignKeys.map((fk) => (fk instanceof SqlForeignKeyIR ? fk : new SqlForeignKeyIR(fk))),
+    );
+    this.uniques = Object.freeze(
+      input.uniques.map((u) => (u instanceof SqlUniqueIR ? u : new SqlUniqueIR(u))),
+    );
+    this.indexes = Object.freeze(
+      input.indexes.map((i) => (i instanceof SqlIndexIR ? i : new SqlIndexIR(i))),
+    );
+    if (input.primaryKey !== undefined) {
+      this.primaryKey =
+        input.primaryKey instanceof PrimaryKey
+          ? input.primaryKey
+          : new PrimaryKey(input.primaryKey);
+    }
+    if (input.annotations !== undefined) this.annotations = input.annotations;
+    if (input.checks !== undefined && input.checks.length > 0) {
+      this.checks = Object.freeze(
+        input.checks.map((c) =>
+          c instanceof SqlCheckConstraintIR ? c : new SqlCheckConstraintIR(c),
+        ),
+      );
+    }
+    this.policies = Object.freeze([...(input.policies ?? [])]);
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return this.name;
+  }
+
+  /**
+   * Equal iff the ids (names) match AND `rlsEnabled` matches — the table's
+   * one own attribute in the diff; all other structural drift is expressed
+   * by children. A paired `not-equal` therefore always means enablement
+   * drift, which the planner maps to ENABLE/DISABLE ROW LEVEL SECURITY.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    PostgresTableSchemaNode.assert(node);
+    return this.id === node.id && this.rlsEnabled === node.rlsEnabled;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [
+      ...Object.values(this.columns),
+      ...(this.primaryKey ? [this.primaryKey] : []),
+      ...this.foreignKeys,
+      ...this.uniques,
+      ...this.indexes,
+      ...(this.checks ?? []),
+      ...this.policies,
+    ];
+  }
+
+  static is(node: SqlSchemaIRNode): node is PostgresTableSchemaNode {
+    return node.nodeKind === PostgresSchemaNodeKind.table;
+  }
+
+  static assert(node: SqlSchemaIRNode): asserts node is PostgresTableSchemaNode {
+    assertNode(node, 'PostgresTableSchemaNode', PostgresTableSchemaNode.is);
+  }
+}