@schemic/postgres 0.1.0-alpha.0

package/src/authoring.ts

@@ -0,0 +1,356 @@
+// The POSTGRES native authoring surface — `s.*` in pg vocabulary, built on the neutral core base
+// (@schemic/core/authoring). A pg project authors with THESE types (pg lingo: text/varchar/numeric/
+// timestamptz/jsonb/serial/...) and the driver lowers them to the portable IR (see ./lower.ts), then
+// emits pg DDL. Per the multi-DB decision (every driver owns its own `s.*`), this mirrors
+// @schemic/surrealdb's surface but in Postgres terms.
+//
+// Design constraints (Manuel):
+//  - LAYER ON ZOD: every field IS a Zod schema (`PgField extends SFieldBase`); pg-native metadata
+//    rides the field's opaque `native` slot (PgMeta), never patching Zod internals.
+//  - ESCAPE HATCH: `s.$postgres(pgType, codec)` for any type not representable on the wire — a Zod
+//    codec (encode/decode) App-side, stored as the given pg type (mirrors surreal's `$surreal`).
+//  - DX FIRST: native types + `$`-methods ($default/$check/$generated/$identity/$unique/$primaryKey/
+//    $references/$comment) + the full Zod wrapper/passthrough chain, all type-preserving.
+
+import {
+  type AnyField,
+  type SchemaOf,
+  SFieldBase,
+  toZod,
+} from "@schemic/core/authoring";
+import * as z from "zod";
+
+// --- PgMeta: the pg-native metadata bag carried on every field ----------------------------------
+
+/** A pg column type token + optional params (`varchar`/[255], `numeric`/[10,2]); the leaf factory sets it. */
+export interface PgTypeRef {
+  type: string;
+  params?: (string | number)[];
+}
+
+/** Postgres-native field metadata (the `native` slot of {@link PgField}). All optional; merged by `$`-methods. */
+export interface PgMeta {
+  /** The pg base type (sans option/nullable/array wrappers, which live on the Zod schema). */
+  pg?: PgTypeRef;
+  /** `DEFAULT <expr>` (verbatim SQL). */
+  default?: string;
+  /** Field-level `CHECK (<expr>)` (verbatim SQL boolean expr). */
+  check?: string;
+  /** `GENERATED ALWAYS AS (<expr>) STORED` (verbatim SQL expr). */
+  generated?: string;
+  /** `GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY` (also how `serial` is modeled). */
+  identity?: "always" | "by-default";
+  /** Column-level `UNIQUE`. */
+  unique?: boolean;
+  /** Column is (part of) the PRIMARY KEY. */
+  primaryKey?: boolean;
+  /** A foreign key to `table(id)` with optional referential actions. */
+  references?: { table: string; onDelete?: string; onUpdate?: string };
+  /** `COMMENT ON COLUMN`. */
+  comment?: string;
+}
+
+const blankMeta = (): PgMeta => ({});
+
+/** A raw SQL expression marker for DDL clauses (`$default`/`$check`/`$generated`) — spliced verbatim. */
+export interface SqlExpr {
+  readonly __sql: string;
+}
+/** Mark a string as a raw SQL expression (vs a literal value) for a DDL clause: `s.timestamptz().$default(sqlExpr("now()"))`. */
+export const sqlExpr = (sql: string): SqlExpr => ({ __sql: sql });
+const isSqlExpr = (v: unknown): v is SqlExpr =>
+  typeof v === "object" && v !== null && "__sql" in v;
+
+/** Render a JS literal as a Postgres literal (numbers/bools bare, strings single-quoted, null -> NULL). */
+function pgLiteral(v: string | number | boolean | null): string {
+  if (v === null) return "NULL";
+  if (typeof v === "number") return String(v);
+  if (typeof v === "boolean") return v ? "true" : "false";
+  return `'${v.replace(/'/g, "''")}'`;
+}
+const toExpr = (v: string | number | boolean | null | SqlExpr): string =>
+  isSqlExpr(v) ? v.__sql : pgLiteral(v);
+
+// --- PgField: the dialect subclass -------------------------------------------------------------
+
+/**
+ * A Postgres field: a Zod schema (App/Wire typing) + {@link PgMeta} (pg-native DDL metadata). Extends
+ * the neutral {@link SFieldBase}, which supplies the codecs, the Zod wrappers, and the `z.*` passthrough;
+ * this subclass re-types the wrappers so a chain stays a `PgField`, and adds the pg `$`-methods.
+ */
+export class PgField<
+  S extends z.ZodType = z.ZodType,
+  Flags extends string = never,
+> extends SFieldBase<S, Flags, PgMeta> {
+  protected rebuild<S2 extends z.ZodType, F2 extends string>(
+    schema: S2,
+    native: PgMeta,
+  ): PgField<S2, F2> {
+    return new PgField<S2, F2>(schema, native);
+  }
+  protected blank(): PgMeta {
+    return blankMeta();
+  }
+
+  // Type-only narrowing of the inherited portable wrappers (runtime impl is the base's, which builds a
+  // PgField via rebuild) — so a mixed chain like `s.text().$default("x").optional()` stays a PgField.
+  declare optional: () => PgField<z.ZodOptional<S>, Flags>;
+  declare nullable: () => PgField<z.ZodNullable<S>, Flags>;
+  declare nullish: () => PgField<z.ZodOptional<z.ZodNullable<S>>, Flags>;
+  declare array: () => PgField<z.ZodArray<S>, Flags>;
+  declare default: (value: z.input<S>) => PgField<z.ZodDefault<S>, Flags>;
+  declare prefault: (value: z.input<S>) => PgField<z.ZodPrefault<S>, Flags>;
+  declare catch: (value: z.output<S>) => PgField<z.ZodCatch<S>, Flags>;
+
+  private with(meta: Partial<PgMeta>): PgField<S, Flags> {
+    return new PgField<S, Flags>(this.schema, { ...this.native, ...meta });
+  }
+
+  // --- pg-native `$`-methods (DDL authoring) ---
+  /** `DEFAULT <value>` — a JS literal, or `sqlExpr("now()")` for a raw SQL default. */
+  $default(value: z.input<S> | SqlExpr): PgField<S, Flags> {
+    return this.with({ default: toExpr(value as never) });
+  }
+  /** Field-level `CHECK (<expr>)`. */
+  $check(expr: string | SqlExpr): PgField<S, Flags> {
+    return this.with({ check: isSqlExpr(expr) ? expr.__sql : expr });
+  }
+  /** `GENERATED ALWAYS AS (<expr>) STORED` — a computed column. */
+  $generated(expr: string | SqlExpr): PgField<S, Flags> {
+    return this.with({ generated: isSqlExpr(expr) ? expr.__sql : expr });
+  }
+  /** `GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY` (auto-increment). */
+  $identity(mode: "always" | "by-default" = "by-default"): PgField<S, Flags> {
+    return this.with({ identity: mode });
+  }
+  /** Column-level `UNIQUE`. */
+  $unique(): PgField<S, Flags> {
+    return this.with({ unique: true });
+  }
+  /** Mark this column (part of) the PRIMARY KEY. */
+  $primaryKey(): PgField<S, Flags> {
+    return this.with({ primaryKey: true });
+  }
+  /** Foreign key to `table(id)` with optional `ON DELETE`/`ON UPDATE` actions. */
+  $references(
+    table: string,
+    opts?: { onDelete?: string; onUpdate?: string },
+  ): PgField<S, Flags> {
+    return this.with({ references: { table, ...(opts ?? {}) } });
+  }
+  /** `COMMENT ON COLUMN`. */
+  $comment(text: string): PgField<S, Flags> {
+    return this.with({ comment: text });
+  }
+
+  /**
+   * ESCAPE HATCH (chainable form) — teach the driver how to STORE this field's value in Postgres:
+   * give the **wire type** as an `s.*`/Zod field (its pg column type is taken from it) plus a codec
+   * (`encode`: app -> wire, `decode`: wire -> app). This turns an otherwise-unmappable App value
+   * (e.g. `s.instanceof(Money)`) into a real pg column. Omit the codec for an identity mapping (the
+   * app value is stored as-is). Mirrors SurrealDB's `.$surreal(wire, codec)`; the standalone
+   * {@link s.$postgres} factory is the from-scratch equivalent. `$`-prefixed to avoid clashing with Zod.
+   */
+  $postgres<WF extends AnyField | z.ZodType, A = z.output<S>>(
+    wire: WF,
+    codec?: {
+      encode: (app: A) => z.output<SchemaOf<WF>>;
+      decode: (wire: z.output<SchemaOf<WF>>) => A;
+    },
+  ): PgField<z.ZodCodec<SchemaOf<WF>, S>, Flags> {
+    const wireSchema = toZod(wire) as SchemaOf<WF>;
+    const c = z.codec(wireSchema, this.schema, {
+      decode: (w) => (codec ? codec.decode(w as never) : w) as never,
+      encode: (a) => (codec ? codec.encode(a as A) : a) as never,
+    });
+    // The stored pg type comes from the WIRE field (its column type); App typing comes from `this`.
+    const wirePg = wire instanceof PgField ? wire.native.pg : undefined;
+    return new PgField<z.ZodCodec<SchemaOf<WF>, S>, Flags>(c, {
+      ...this.native,
+      ...(wirePg ? { pg: wirePg } : {}),
+    });
+  }
+}
+
+// --- the `s` vocabulary (pg lingo) -------------------------------------------------------------
+
+const mk = (
+  type: string,
+  schema: z.ZodType,
+  params?: (string | number)[],
+): PgField => new PgField(schema, { pg: params ? { type, params } : { type } });
+
+/** The Postgres authoring namespace. Zod drop-ins (string/number/…) + native pg types + `$postgres`. */
+export const s = {
+  // Zod drop-ins (the canonical superset; each maps to a sensible pg default). Native aliases below
+  // (text/varchar/int/numeric/…) give precise control.
+  string: () => mk("text", z.string()),
+  number: () => mk("double precision", z.number()),
+  // text
+  text: () => mk("text", z.string()),
+  varchar: (n?: number) =>
+    n === undefined
+      ? mk("varchar", z.string())
+      : mk("varchar", z.string().max(n), [n]),
+  char: (n?: number) =>
+    n === undefined ? mk("char", z.string()) : mk("char", z.string(), [n]),
+  citext: () => mk("citext", z.string()),
+  // numeric
+  smallint: () => mk("smallint", z.int().gte(-32768).lte(32767)),
+  integer: () => mk("integer", z.int()),
+  int: () => mk("integer", z.int()),
+  bigint: () => mk("bigint", z.int()),
+  serial: () => mk("integer", z.int()).$identity("by-default"),
+  bigserial: () => mk("bigint", z.int()).$identity("by-default"),
+  numeric: (precision?: number, scale?: number) =>
+    precision === undefined
+      ? mk("numeric", z.number())
+      : // Postgres stores `numeric(p)` as `numeric(p,0)`; keep scale explicit so it round-trips.
+        mk("numeric", z.number(), [precision, scale ?? 0]),
+  decimal: (precision?: number, scale?: number) => s.numeric(precision, scale),
+  real: () => mk("real", z.number()),
+  doublePrecision: () => mk("double precision", z.number()),
+  float: () => mk("double precision", z.number()),
+  money: () => mk("money", z.string()),
+  // boolean
+  boolean: () => mk("boolean", z.boolean()),
+  bool: () => mk("boolean", z.boolean()),
+  // temporal
+  timestamptz: () => mk("timestamptz", z.date()),
+  timestamp: () => mk("timestamp", z.date()),
+  date: () => mk("date", z.date()),
+  time: () => mk("time", z.string()),
+  timetz: () => mk("timetz", z.string()),
+  interval: () => mk("interval", z.string()),
+  // identity / network / uuid / bytes
+  uuid: () => mk("uuid", z.uuid()),
+  bytea: () => mk("bytea", z.instanceof(Uint8Array)),
+  inet: () => mk("inet", z.string()),
+  cidr: () => mk("cidr", z.string()),
+  macaddr: () => mk("macaddr", z.string()),
+  // json
+  jsonb: <T extends z.ZodType = z.ZodUnknown>(shape?: T) =>
+    mk("jsonb", shape ?? z.unknown()),
+  json: <T extends z.ZodType = z.ZodUnknown>(shape?: T) =>
+    mk("json", shape ?? z.unknown()),
+  // enum (string-literal union -> text) and single literal
+  enum: <const T extends readonly [string, ...string[]]>(values: T) =>
+    mk("text", z.enum(values)),
+  literal: <const V extends string | number | boolean>(value: V) =>
+    mk(
+      typeof value === "number"
+        ? "double precision"
+        : typeof value === "boolean"
+          ? "boolean"
+          : "text",
+      z.literal(value),
+    ),
+  // object -> jsonb (opaque on disk). Accepts field OR raw-Zod values (a Zod drop-in superset).
+  object: (shape: Record<string, AnyField | z.ZodType>) =>
+    mk(
+      "jsonb",
+      z.object(
+        Object.fromEntries(
+          Object.entries(shape).map(([k, v]) => [k, toZod(v)]),
+        ),
+      ),
+    ),
+  // array(elem) -> `<elem>[]`; carries the element's pg metadata so it lowers to an array of that type.
+  array: (elem: AnyField | z.ZodType): PgField =>
+    new PgField(
+      z.array(toZod(elem)),
+      elem instanceof PgField ? elem.native : {},
+    ),
+  // foreign key: `text` column + FK to `table(id)`
+  references: (
+    table: string,
+    opts?: { onDelete?: string; onUpdate?: string },
+  ): PgField =>
+    new PgField(z.string(), {
+      pg: { type: "text" },
+      references: { table, ...(opts ?? {}) },
+    }),
+  /**
+   * ESCAPE HATCH — a pg type with no portable meaning, stored via a Zod codec (encode/decode). The
+   * column is emitted as `pgType`; App-side reads/writes go through `codec`. Mirrors surreal `$surreal`.
+   */
+  $postgres: <C extends z.ZodType>(pgType: string, codec: C): PgField<C> =>
+    new PgField<C>(codec, { pg: { type: pgType } }),
+};
+
+// --- defineTable: a pg table builder producing an `Authored` object -----------------------------
+
+/** Table-level pg config: composite PK, table CHECKs, and secondary indexes. */
+export interface PgTableConfig {
+  primaryKey?: string[];
+  checks?: string[];
+  indexes?: { name?: string; cols: string[]; unique?: boolean }[];
+}
+
+/**
+ * A Postgres table definition — the `Authored` object the driver's `lower` reads. Structurally a
+ * `{ name }` (the neutral `Authored` bound); also carries its `fields` (a `{ col: PgField }` map) and
+ * table-level config. Chainable: `.primaryKey(...)`, `.check(expr)`, `.index([...])`.
+ */
+export class PgTableDef<
+  Name extends string = string,
+  F extends Record<string, PgField> = Record<string, PgField>,
+> {
+  constructor(
+    readonly name: Name,
+    readonly fields: F,
+    readonly config: PgTableConfig = {},
+  ) {}
+
+  /** Composite / custom PRIMARY KEY (overrides the implicit `id`). */
+  primaryKey(...cols: (keyof F & string)[]): PgTableDef<Name, F> {
+    return new PgTableDef(this.name, this.fields, {
+      ...this.config,
+      primaryKey: cols,
+    });
+  }
+  /** A table-level `CHECK (<expr>)`. */
+  check(expr: string): PgTableDef<Name, F> {
+    return new PgTableDef(this.name, this.fields, {
+      ...this.config,
+      checks: [...(this.config.checks ?? []), expr],
+    });
+  }
+  /** A secondary index over `cols` (optionally `UNIQUE`). */
+  index(
+    cols: (keyof F & string)[],
+    opts?: { name?: string; unique?: boolean },
+  ): PgTableDef<Name, F> {
+    return new PgTableDef(this.name, this.fields, {
+      ...this.config,
+      indexes: [...(this.config.indexes ?? []), { cols, ...(opts ?? {}) }],
+    });
+  }
+
+  /**
+   * A foreign-key field referencing THIS table (for use in another table's shape):
+   * `author: user.record({ onDelete: "cascade" })`. Also satisfies the CLI's structural table check.
+   */
+  record(opts?: { onDelete?: string; onUpdate?: string }): PgField {
+    return s.references(this.name, opts);
+  }
+}
+
+/** Declare a Postgres table: `export const user = defineTable("user", { name: s.text(), age: s.integer().optional() })`. */
+export function defineTable<
+  Name extends string,
+  F extends Record<string, PgField>,
+>(name: Name, fields: F, config?: PgTableConfig): PgTableDef<Name, F> {
+  return new PgTableDef(name, fields, config ?? {});
+}
+
+// --- App/Wire type inference (DX) --------------------------------------------------------------
+
+/** The decoded (App-land) row type of a table — `z.output` of each field's schema. */
+export type App<T extends PgTableDef> = {
+  [K in keyof T["fields"]]: z.output<T["fields"][K]["schema"]>;
+};
+/** The encoded (wire) row type of a table — `z.input` of each field's schema. */
+export type Wire<T extends PgTableDef> = {
+  [K in keyof T["fields"]]: z.input<T["fields"][K]["schema"]>;
+};

package/src/emit.ts

@@ -0,0 +1,253 @@
+// Pure Postgres DDL + type helpers — the shared emit primitives the kind engines (./kinds.ts) +
+// authoring lower (./lower.ts) + introspection (./index.ts) build on, so a table's CREATE/ALTER DDL
+// is produced by ONE set of functions (no drift). No Driver/connection state here: just IR -> pg DDL
+// string transforms. The field/type SUBSTRATE (`PortableField`/`PortableType`) is core's; the table-
+// level container is this driver's own (`PgTable`) — `PortableTable` retired at the kind-registry flip.
+
+import type {
+  PortableField,
+  PortableType,
+  ScalarName,
+} from "@schemic/core/driver";
+import { nullable } from "@schemic/core/driver";
+
+/** A secondary index over one table's columns (this driver emits UNIQUE; others tracked for parity). */
+export interface PgIndexInfo {
+  name: string;
+  cols: string[];
+  unique: boolean;
+}
+
+/** The driver-private table shape (replaces the retired `PortableTable`): columns + PK + CHECKs + idx. */
+export interface PgTable {
+  name: string;
+  fields: PortableField[];
+  indexes: PgIndexInfo[];
+  primaryKey?: string[];
+  checks?: string[];
+}
+
+/** Just what `createTableDdl` needs (a `PgTable` is a structural superset). */
+export type PgCreateInput = Omit<PgTable, "indexes">;
+
+export const escId = (name: string) => `"${name.replace(/"/g, '""')}"`;
+
+// --- Type mapping (portable <-> Postgres) -------------------------------------------------------
+
+const SCALAR_TO_PG: Partial<Record<ScalarName, string>> = {
+  string: "text",
+  int: "integer",
+  float: "double precision",
+  decimal: "numeric",
+  number: "double precision",
+  bool: "boolean",
+  datetime: "timestamp with time zone",
+  uuid: "uuid",
+  bytes: "bytea",
+  duration: "interval",
+};
+
+/** A portable column type and how it lands in Postgres: base SQL type, nullability, and FK target. */
+export interface PgColumn {
+  sql: string;
+  nullable: boolean;
+  /** A `record<table>` link -> a FK to that table (single-target only; spike scope). */
+  references?: string;
+}
+
+export function pgColumn(type: PortableType): PgColumn {
+  // Peel option/nullable: Postgres represents both as a nullable column (the documented collapse).
+  if (type.t === "option" || type.t === "nullable") {
+    return { ...pgColumn(type.inner), nullable: true };
+  }
+  if (type.t === "scalar") {
+    const sql = SCALAR_TO_PG[type.name];
+    if (!sql) throw new Error(`postgres: unsupported scalar "${type.name}"`);
+    return { sql, nullable: false };
+  }
+  if (type.t === "literal") {
+    // A single literal -> its base scalar (PG has no singleton types). Enums (literal unions) below.
+    const base =
+      typeof type.value === "number"
+        ? "double precision"
+        : typeof type.value === "boolean"
+          ? "boolean"
+          : "text";
+    return { sql: base, nullable: false };
+  }
+  if (type.t === "union") {
+    // A union of string literals -> text (an enum-ish column; a CHECK could be added later).
+    if (
+      type.members.every(
+        (m) => m.t === "literal" && typeof m.value === "string",
+      )
+    ) {
+      return { sql: "text", nullable: false };
+    }
+    throw new Error("postgres: non-enum unions are unsupported");
+  }
+  if (type.t === "array" || type.t === "set") {
+    const elem = pgColumn(type.elem);
+    return { sql: `${elem.sql}[]`, nullable: false };
+  }
+  if (type.t === "object") {
+    return { sql: "jsonb", nullable: false };
+  }
+  if (type.t === "record") {
+    if (type.tables.length !== 1) {
+      // Multi-target links would need a polymorphic FK; out of spike scope -> plain text id.
+      return { sql: "text", nullable: false };
+    }
+    return { sql: "text", nullable: false, references: type.tables[0] };
+  }
+  if (type.t === "geometry") {
+    // Would map to PostGIS `geometry`; without the extension, store GeoJSON as jsonb.
+    return { sql: "jsonb", nullable: false };
+  }
+  if (type.t === "native") {
+    if (type.db !== "postgres") {
+      throw new Error(
+        `postgres: native type "${type.name}" belongs to driver "${type.db}"`,
+      );
+    }
+    // params are order-significant: varchar -> (n), numeric -> (p[, s]).
+    const params = type.params as (string | number)[] | undefined;
+    const sql =
+      params && params.length > 0
+        ? `${type.name}(${params.join(", ")})`
+        : type.name;
+    return { sql, nullable: false };
+  }
+  throw new Error(`postgres: cannot emit type ${JSON.stringify(type)}`);
+}
+
+// --- normalize: project the portable IR onto what Postgres represents ---------------------------
+
+/** Collapse option -> nullable (Postgres can't distinguish absence from NULL). Idempotent. */
+export function pgCanonType(type: PortableType): PortableType {
+  if (type.t === "option") return nullable(pgCanonType(type.inner));
+  if (type.t === "nullable") return nullable(pgCanonType(type.inner));
+  if (type.t === "array")
+    return {
+      t: "array",
+      elem: pgCanonType(type.elem),
+      ...(type.size !== undefined ? { size: type.size } : {}),
+    };
+  if (type.t === "set")
+    return {
+      t: "set",
+      elem: pgCanonType(type.elem),
+      ...(type.size !== undefined ? { size: type.size } : {}),
+    };
+  // A nested object becomes an opaque jsonb column -> canonical empty object (sub-keys not tracked).
+  if (type.t === "object") return { t: "object", fields: {} };
+  return type;
+}
+
+/** Uppercase a referential action so authored `cascade` matches introspected `CASCADE`; drop NO ACTION (default). */
+export function normAction(a?: string): string | undefined {
+  const u = a?.toUpperCase();
+  return u && u !== "NO ACTION" ? u : undefined;
+}
+
+/**
+ * A field reduced to its EQUALITY-relevant shape: canonical type + the STRUCTURAL clauses Postgres
+ * round-trips (identity, FK referential actions). EXPRESSION clauses (`default`/`check`/`computed`/
+ * `comment`) are dropped here: Postgres rewrites them on read (`0` -> `0`, `'x'` -> `'x'::text`,
+ * `a>0` -> `(a > 0)`), so they emit faithfully but can't round-trip to an exact match — a documented
+ * capability gap, not an equality difference (see docs/COVERAGE.md).
+ */
+export function canonField(f: PortableField, table: string): PortableField {
+  const out: PortableField = { name: f.name, table, type: pgCanonType(f.type) };
+  if (f.identity !== undefined) out.identity = f.identity;
+  if (f.reference) {
+    const ref: { on_delete?: string; on_update?: string } = {};
+    const od = normAction(f.reference.on_delete);
+    const ou = normAction(f.reference.on_update);
+    if (od) ref.on_delete = od;
+    if (ou) ref.on_update = ou;
+    if (ref.on_delete !== undefined || ref.on_update !== undefined)
+      out.reference = ref;
+  }
+  return out;
+}
+
+/** Fields ready for emit: drop dotted sub-fields, canonicalize the type, KEEP all DDL clauses, sort. */
+export function pgEmitFields(t: PgCreateInput): PortableField[] {
+  return t.fields
+    .filter((f) => !f.name.includes("."))
+    .map((f) => ({ ...f, table: t.name, type: pgCanonType(f.type) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// --- column + table DDL -------------------------------------------------------------------------
+
+/** `ON DELETE …`/`ON UPDATE …` suffix for a FK constraint (empty when no actions). */
+export function fkActions(ref?: {
+  on_delete?: string;
+  on_update?: string;
+}): string {
+  let s = "";
+  if (ref?.on_delete) s += ` ON DELETE ${ref.on_delete}`;
+  if (ref?.on_update) s += ` ON UPDATE ${ref.on_update}`;
+  return s;
+}
+
+/** A column body for CREATE TABLE: type + NOT NULL + identity/default/generated/check clauses. */
+export function fieldColumnDdl(f: PortableField): string {
+  const col = pgColumn(f.type);
+  let s = `${escId(f.name)} ${col.sql}`;
+  if (!col.nullable) s += " NOT NULL";
+  if (f.identity)
+    s += ` GENERATED ${f.identity === "always" ? "ALWAYS" : "BY DEFAULT"} AS IDENTITY`;
+  if (f.default !== undefined) s += ` DEFAULT ${f.default}`;
+  if (f.computed !== undefined)
+    s += ` GENERATED ALWAYS AS (${f.computed}) STORED`;
+  if (f.check !== undefined) s += ` CHECK (${f.check})`;
+  return s;
+}
+
+/**
+ * The `CREATE TABLE (...)` statement body for a table — the implicit `id` PK (or a custom/composite
+ * PRIMARY KEY), every column with its clauses, and table-level CHECKs. The single source for table
+ * creation DDL, used by the `table` kind's `emit`/`canonical`.
+ */
+export function createTableDdl(t: PgCreateInput): string {
+  const fields = pgEmitFields(t);
+  const custom = !!(t.primaryKey && t.primaryKey.length > 0);
+  const cols: string[] = [];
+  if (!custom) cols.push(`${escId("id")} text PRIMARY KEY`); // implicit id (mirrors Surreal).
+  for (const f of fields) cols.push(fieldColumnDdl(f));
+  if (custom) cols.push(`PRIMARY KEY (${t.primaryKey?.map(escId).join(", ")})`);
+  for (const c of t.checks ?? []) cols.push(`CHECK (${c})`);
+  return `CREATE TABLE ${escId(t.name)} (\n  ${cols.join(",\n  ")}\n);`;
+}
+
+// --- column-level ALTER helpers (used by the field-level diff + the table kind's overwrite) ------
+
+/** A column definition body (`"name" type [NOT NULL]`) for ADD COLUMN / CREATE TABLE. */
+export function colDef(f: PortableField): string {
+  const c = pgColumn(f.type);
+  return `${escId(f.name)} ${c.sql}${c.nullable ? "" : " NOT NULL"}`;
+}
+export const fkName = (table: string, field: string) =>
+  `${table}_${field}_fkey`;
+export const addColSql = (table: string, f: PortableField) =>
+  `ALTER TABLE ${escId(table)} ADD COLUMN ${colDef(f)};`;
+export const dropColSql = (table: string, field: string) =>
+  `ALTER TABLE ${escId(table)} DROP COLUMN IF EXISTS ${escId(field)};`;
+export const dropTableSql = (table: string) =>
+  `DROP TABLE IF EXISTS ${escId(table)} CASCADE;`;
+
+/** `ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY …` for a single-column FK to `ref(id)`. */
+export const addFkSql = (
+  table: string,
+  field: string,
+  ref: string,
+  actions = "",
+) =>
+  `ALTER TABLE ${escId(table)} ADD CONSTRAINT ${escId(fkName(table, field))} FOREIGN KEY (${escId(field)}) REFERENCES ${escId(ref)} (${escId("id")})${actions};`;
+
+/** Drop a FK constraint by its generated name. */
+export const dropFkSql = (table: string, field: string) =>
+  `ALTER TABLE ${escId(table)} DROP CONSTRAINT IF EXISTS ${escId(fkName(table, field))};`;