@intentius/chant-lexicon-sql 0.122.0 → 0.123.0

package/src/sql-types.test.ts

@@ -0,0 +1,132 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { COLUMN_TYPES } from "./generated/postgres";
+import { TYPE_FAMILIES } from "./generated/clickhouse";
+import { POSTGRES_ROW_TYPES } from "./postgres/row-types";
+import { CLICKHOUSE_ROW_TYPES, clickhouseRowType } from "./clickhouse/row-types";
+import * as pg from "./postgres/entities";
+import * as ch from "./clickhouse/entities";
+import { getTypedSlots, relationKey } from "./core/typed";
+import { sqlSerializer } from "./serializer";
+import { renderSqlTypes } from "./sql-types";
+import { runTypes, shadowingSource } from "./sql-types-command";
+
+const entities = (o: Record<string, unknown>) => new Map(Object.entries(o)) as Map<string, Declarable>;
+
+describe("the row type mapping covers the pinned catalogs", () => {
+  test("every Postgres built-in type of every supported major has a row type, and nothing else does", () => {
+    expect(Object.keys(POSTGRES_ROW_TYPES).sort()).toEqual(Object.keys(COLUMN_TYPES).sort());
+  });
+
+  test("every ClickHouse type family has a row type, and nothing else does", () => {
+    const families = [...new Set(Object.values(TYPE_FAMILIES).map((f) => f.canonical))].sort();
+    expect(Object.keys(CLICKHOUSE_ROW_TYPES).sort()).toEqual(families);
+  });
+
+  test("ClickHouse wrappers and containers compose; an alias reads as its family", () => {
+    expect(clickhouseRowType("Nullable(UInt64)")).toEqual({ ts: "string", nullable: true });
+    expect(clickhouseRowType("LowCardinality(Nullable(String))")).toEqual({ ts: "string", nullable: true });
+    expect(clickhouseRowType("Array(Nullable(Int32))").ts).toBe("(number | null)[]");
+    expect(clickhouseRowType("Map(String, Array(UInt8))").ts).toBe("Record<string, number[]>");
+    expect(clickhouseRowType("Tuple(String, UInt8)").ts).toBe("[string, number]");
+    expect(clickhouseRowType("Enum8('a' = 1, 'it''s' = 2)").ts).toBe('"a" | "it\'s"');
+    expect(clickhouseRowType("BIGINT UNSIGNED").ts).toBe("string");
+    expect(clickhouseRowType("SimpleAggregateFunction(sum, Float64)").ts).toBe("number");
+    expect(clickhouseRowType("NoSuchType").ts).toBe("unknown");
+  });
+});
+
+describe("the slots a tag records", () => {
+  test("a Postgres foreign key's interpolated referenced column, paired with the referencing column, off the output", () => {
+    const s = pg.schema`CREATE SCHEMA shop`;
+    const a = pg.table`CREATE TABLE ${s}.a (id bigint PRIMARY KEY, code text UNIQUE)`;
+    const b = pg.table<"shop.b">`
+      CREATE TABLE ${s}.b (
+        a_id bigint REFERENCES ${a} (${a.columns.id}),
+        a_code text,
+        FOREIGN KEY (a_code) REFERENCES ${a} (${a.columns.code}),
+        other bigint REFERENCES ${a}
+      )`;
+    expect(getTypedSlots(b)).toEqual([
+      { index: 2, kind: "references", column: "a_id" },
+      { index: 4, kind: "references", column: "a_code" },
+    ]);
+    expect(Object.getOwnPropertySymbols(b).some((k) => Object.getOwnPropertyDescriptor(b, k)!.enumerable)).toBe(false);
+    const out = sqlSerializer.serialize(entities({ s, a, b })) as { primary: string };
+    expect(out.primary).not.toContain("references\", \"column");
+  });
+
+  test("a ClickHouse sort key's bare interpolated columns, and nothing inside an expression", () => {
+    const db = ch.database`CREATE DATABASE shop`;
+    const e = ch.table`CREATE TABLE ${db}.e (k String, c Nullable(String), n UInt8) ENGINE = MergeTree ORDER BY k`;
+    const v = ch.view`
+      CREATE MATERIALIZED VIEW ${db}.v ENGINE = MergeTree
+      ORDER BY (${e.columns.k}, ifNull(${e.columns.c}, ''))
+      PRIMARY KEY ${e.columns.k}
+      AS SELECT ${e.columns.k}, ${e.columns.c} FROM ${e}`;
+    expect(getTypedSlots(v)).toEqual([
+      { index: 1, kind: "sortKey" },
+      { index: 3, kind: "sortKey" },
+    ]);
+  });
+});
+
+describe("renderSqlTypes", () => {
+  test("keys are qualified and folded, a view passes its column through, slots stop at the last checked one", () => {
+    const s = pg.schema`CREATE SCHEMA Shop`;
+    const users = pg.table`CREATE TABLE ${s}.Users (Id serial PRIMARY KEY, mood text, born date NOT NULL)`;
+    const posts = pg.table`CREATE TABLE ${s}.posts (author integer REFERENCES ${users} (${users.columns.id}), body text)`;
+    const feed = pg.view`CREATE VIEW ${s}.feed AS SELECT p.${posts.columns.body}, upper(p.${posts.columns.body}) AS loud FROM ${posts} p`;
+    const text = renderSqlTypes(entities({ s, users, posts, feed }), { projectDir: "/" });
+    expect(text.split("\n")[0]).toContain("Generated by chant");
+    expect(text).toContain('import type { Column, KeyColumn } from "@intentius/chant-lexicon-sql/postgres";');
+    expect(text).toContain('"shop.users": {');
+    expect(text).toContain('id: Column<"integer", { ts: number; nullable: false; cmp: "N" }>;');
+    expect(text).toContain('born: Column<"date", { ts: Date; nullable: false; cmp: "D" }>;');
+    expect(text).toContain("slots: [unknown, unknown, KeyColumn<\"N\">];");
+    expect(text).toContain('body: Column<"text", { ts: string; nullable: true; cmp: "S" }>;');
+    expect(text).toContain('loud: Column<"unknown", { ts: unknown; nullable: never; cmp: never }>;');
+    expect(text.indexOf('"shop.feed"')).toBeLessThan(text.indexOf('"shop.posts"'));
+  });
+
+  test("with nothing declared, a module that augments nothing", () => {
+    expect(renderSqlTypes(new Map(), { config: { sql: { dialect: "postgres" } } })).toBe(
+      [
+        "// Generated by chant — do not edit directly. `chant sql types` writes it from the build's entities.",
+        'import type {} from "@intentius/chant-lexicon-sql/postgres";',
+        "",
+        'declare module "@intentius/chant-lexicon-sql/postgres" {',
+        "  interface SqlSchema {}",
+        "}",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("relationKey: qualified when the DDL qualifies it", () => {
+    expect(relationKey({ schema: "app", name: "users" })).toBe("app.users");
+    expect(relationKey({ database: "shop", name: "events" })).toBe("shop.events");
+    expect(relationKey({ name: "events" })).toBe("events");
+  });
+});
+
+describe("chant sql types", () => {
+  test("refuses to write beside a sql-types.ts, which tsc would read instead", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sql-types-"));
+    writeFileSync(join(dir, "sql-types.ts"), "export {};\n");
+    expect(shadowingSource(join(dir, "sql-types.d.ts"))).toBe(join(dir, "sql-types.ts"));
+    expect(shadowingSource(join(dir, "other.d.ts"))).toBeUndefined();
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      expect(await runTypes({ verb: "types", rawArgs: ["--output", "sql-types.d.ts"] })).toBe(1);
+      expect(await runTypes({ verb: "types", rawArgs: ["--bogus"] })).toBe(1);
+    } finally {
+      process.chdir(cwd);
+    }
+    expect(readFileSync(join(dir, "sql-types.ts"), "utf8")).toBe("export {};\n");
+  });
+});

package/src/sql-types.ts

@@ -0,0 +1,352 @@
+/**
+ * The declarations `chant sql types` writes (#3751): one `sql-types.d.ts`
+ * that augments the dialect's `SqlSchema` with every table, view and
+ * dictionary the build declares, keyed by qualified name.
+ *
+ * {@link renderSqlTypes} is pure: the entities of a build in, the file's text
+ * out. It reads the objects as the serializer writes them, so a `.sql`
+ * file's objects and a composite's members are covered exactly as the build
+ * covers them, and it reads each template's slot record (`core/typed.ts`) for
+ * the `${}` positions a foreign key or a sort key consumes.
+ *
+ * Each column is a `Column<sqlType, { ts, nullable, cmp }>`:
+ *
+ * - `sqlType` is the type as the catalog spells it (`bigint`,
+ *   `timestamp(3) with time zone`, `Nullable(String)`);
+ * - `ts` is its value in application code (`./postgres/row-types.ts`,
+ *   `./clickhouse/row-types.ts`);
+ * - `nullable` is whether the value can be NULL. A Postgres view's columns
+ *   always can, as the server's own catalog says; a column whose type the
+ *   generator cannot tell is `never`, which fits every slot;
+ * - `cmp` is how it compares in a key: SQLPG124's type identity in Postgres
+ *   (`./lint/post-synth/postgres-names.ts`'s `typeIdentity`), the type
+ *   family in ClickHouse; `never` when it cannot be told.
+ *
+ * A view's column that is one column reference (`${t.columns.c}`, `o.${t.columns.c}`)
+ * is that column's type; any other expression is `unknown`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import type { Declarable } from "@intentius/chant/declarable";
+import { GENERATED_MARKER } from "@intentius/chant/discovery/files";
+import { getProvenance } from "@intentius/chant/provenance";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { isPostgresObject } from "./postgres/entities";
+import { isClickHouseObject, quoteIdentifier } from "./clickhouse/entities";
+import { quoteIdent } from "./postgres/keywords";
+import { getTypedSlots, relationKey } from "./core/typed";
+import { sqlSerializer } from "./serializer";
+import { sqlFileOf } from "./sql-files";
+import { filesDialect } from "./files/build-root";
+import type { SqlDialect } from "./dialects";
+import { POSTGRES_ROW_TYPES } from "./postgres/row-types";
+import { clickhouseRowType } from "./clickhouse/row-types";
+import { typeFamily } from "./lint/post-synth/clickhouse-helpers";
+import { PINNED_MAJOR } from "./lint/post-synth/postgres-helpers";
+import { parseType, projectFromObjects, resolveType, typeIdentity, type ParsedType, type PgProject } from "./lint/post-synth/postgres-names";
+import type { OutputObject } from "./lint/post-synth/sql-helpers";
+
+/** The file `chant sql types` writes, in the project's source directory. */
+export const SQL_TYPES_FILE = "sql-types.d.ts";
+
+/**
+ * Where `chant sql types` writes the file by default: the project's
+ * `sourceDir`, or the project root when it is unset.
+ */
+export function sqlTypesPath(projectDir: string, config: Record<string, unknown> | undefined): string {
+  const sourceDir = typeof config?.sourceDir === "string" ? config.sourceDir : ".";
+  return join(resolve(projectDir, sourceDir), SQL_TYPES_FILE);
+}
+
+/** The file on disk against what the build's entities render: `missing`, `stale` or `current`. */
+export function sqlTypesState(
+  entities: ReadonlyMap<string, Declarable>,
+  file: string,
+  opts: RenderSqlTypesOptions = {},
+): "missing" | "stale" | "current" {
+  if (!existsSync(file)) return "missing";
+  let onDisk: string;
+  try {
+    onDisk = readFileSync(file, "utf8");
+  } catch {
+    return "missing";
+  }
+  return onDisk === renderSqlTypes(entities, opts) ? "current" : "stale";
+}
+
+/** The module each dialect's `SqlSchema` is augmented in. */
+export const SQL_TYPES_MODULE: Readonly<Record<SqlDialect, string>> = {
+  postgres: "@intentius/chant-lexicon-sql/postgres",
+  clickhouse: "@intentius/chant-lexicon-sql/clickhouse",
+};
+
+export interface RenderSqlTypesOptions {
+  /** The directory each declaration's source file is named relative to. Default: the working directory. */
+  projectDir?: string;
+  /** The project's config: `sql.postgresMajor` for the catalog, `sql.dialect` when nothing is declared. */
+  config?: Record<string, unknown>;
+}
+
+interface ColumnEntry {
+  name: string;
+  sqlType: string;
+  ts: string;
+  /** `never` when the generator cannot tell. */
+  nullable: boolean | "never";
+  /** Undefined when it cannot be told; written `never`. */
+  cmp?: string;
+}
+
+interface RelationEntry {
+  key: string;
+  origin: string;
+  columns: ColumnEntry[];
+  /** Per `${}` index, the slot's type; holes are `unknown`. */
+  slots: Map<number, { type: string; note: string }>;
+}
+
+const UNKNOWN_COLUMN = (name: string): ColumnEntry => ({ name, sqlType: "unknown", ts: "unknown", nullable: "never" });
+
+const posix = (p: string) => p.split(sep).join("/");
+
+/** Where a declaration came from: its file relative to the project, and its export. */
+function originOf(entity: Declarable, exportName: string, projectDir: string): string {
+  const prov = getProvenance(entity);
+  const file = sqlFileOf(entity) ?? (prov?.sourceFile ? relative(projectDir, prov.sourceFile) : undefined);
+  const composite = prov?.composite ? ` (${prov.composite})` : "";
+  return `${file ? posix(file) : "?"}: ${exportName}${composite}`;
+}
+
+/** The names a relation's `.columns` record holds at run time, in order. */
+const runtimeColumns = (entity: Declarable | undefined): string[] => Object.keys((entity as { columns?: object } | undefined)?.columns ?? {});
+
+/** Whether `expr` is the column `column` alone, bare or qualified (`o.user_id`). */
+function isBareColumn(expr: string, quoted: string): boolean {
+  const unqualified = expr.trim().replace(/^(?:"(?:[^"]|"")+"|`(?:[^`]|``)+`|[A-Za-z_][\w$]*)\./, "");
+  return unqualified === quoted;
+}
+
+interface LineageJson {
+  output: string;
+  expr: string;
+  from: Array<string | null>;
+}
+
+/** A view's column that passes one column through: that column's export and name. */
+function passthrough(o: OutputObject, name: string, quote: (c: string) => string): { export: string; column: string } | undefined {
+  const edge = ((o.lineage as LineageJson[] | undefined) ?? []).find((e) => e.output === name);
+  const ref = edge?.from.length === 1 ? edge.from[0] : undefined;
+  if (!edge || !ref) return undefined;
+  const dot = ref.indexOf(".");
+  if (dot < 0) return undefined;
+  const column = ref.slice(dot + 1);
+  return isBareColumn(edge.expr, quote(column)) ? { export: ref.slice(0, dot), column } : undefined;
+}
+
+// ── Postgres ────────────────────────────────────────────────────────────
+
+const PG_RELATIONS = new Set(["Postgres::Table", "Postgres::View", "Postgres::MaterializedView"]);
+
+/** A built-in type spelled as `format_type()` spells it, with its modifiers. */
+function spell(canonical: string, t: ParsedType): string {
+  let s = canonical;
+  if (t.fields) s = `${s} ${t.fields.toLowerCase()}`;
+  if (t.modifiers && t.modifiers.length > 0) {
+    const mods = `(${t.modifiers.join(",")})`;
+    const zoned = /^(time|timestamp)( with(?:out)? time zone)$/.exec(s);
+    s = zoned ? `${zoned[1]}${mods}${zoned[2]}` : `${s}${mods}`;
+  }
+  return s;
+}
+
+const arrayOf = (ts: string): string => `${/[|&]/.test(ts) && !/^\{.*\}$/s.test(ts) ? `(${ts})` : ts}[]`;
+
+/** A Postgres type's spelling, row type, and whether the type itself forbids NULL (a serial, a NOT NULL domain). */
+function pgType(p: PgProject, text: string | undefined, depth = 0): { sqlType: string; ts: string; notNull: boolean } {
+  const t = parseType(text);
+  if (!t || depth > 5) return { sqlType: text?.trim() || "unknown", ts: "unknown", notNull: false };
+  const r = resolveType(p, t, { serial: true });
+  const array = (x: { sqlType: string; ts: string; notNull: boolean }) => (t.array ? { sqlType: `${x.sqlType}[]`, ts: arrayOf(x.ts), notNull: x.notNull } : x);
+  if (r.kind === "builtin") {
+    const ts = (POSTGRES_ROW_TYPES as Readonly<Record<string, string | undefined>>)[r.canonical] ?? "unknown";
+    return array({ sqlType: spell(r.canonical, t), ts, notNull: r.serial === true });
+  }
+  if (r.kind === "declared") {
+    const o = r.object;
+    const sqlType = String(o.sqlName ?? o.name);
+    if (o.type === "Postgres::Enum") {
+      const labels = (o.labels as string[] | undefined) ?? [];
+      return array({ sqlType, ts: labels.length > 0 ? labels.map((l) => JSON.stringify(l)).join(" | ") : "string", notNull: false });
+    }
+    if (o.type === "Postgres::Domain") {
+      const base = pgType(p, o.dataType as string | undefined, depth + 1);
+      return array({ sqlType, ts: base.ts, notNull: o.notNull === true || base.notNull });
+    }
+    // A row type: the driver hands back its text.
+    return array({ sqlType, ts: "string", notNull: false });
+  }
+  return { sqlType: text!.trim(), ts: "unknown", notNull: false };
+}
+
+interface PgTableJson extends OutputObject {
+  columns: Array<{ name: string; type?: string; notNull?: boolean; generated?: { kind: string } }>;
+  primaryKey?: { columns: string[] };
+}
+
+function postgresEntries(objects: OutputObject[], major: number, entities: ReadonlyMap<string, Declarable>, projectDir: string): RelationEntry[] {
+  const p = projectFromObjects(objects, major);
+  const done = new Map<string, RelationEntry | undefined>();
+  const entryOf = (exportName: string): RelationEntry | undefined => {
+    if (done.has(exportName)) return done.get(exportName);
+    done.set(exportName, undefined);
+    const o = p.byExport.get(exportName);
+    const entity = entities.get(exportName);
+    if (!o || !entity || !PG_RELATIONS.has(o.type)) return undefined;
+    const names = runtimeColumns(entity);
+    let columns: ColumnEntry[];
+    if (o.type === "Postgres::Table") {
+      const t = o as PgTableJson;
+      const own = new Map(t.columns.map((c) => [c.name, c]));
+      // A partition's `col WITH OPTIONS` has no type of its own: its parent's stands.
+      const inherited = new Map<string, string | undefined>();
+      for (const parent of [...(((t.inherits as unknown[]) ?? []) as unknown[]), ...(t.partitionOf !== undefined ? [t.partitionOf] : [])]) {
+        const pt = typeof parent === "string" ? (p.byExport.get(parent) as PgTableJson | undefined) : undefined;
+        for (const c of pt?.columns ?? []) if (!inherited.has(c.name)) inherited.set(c.name, c.type);
+      }
+      const pk = new Set(t.primaryKey?.columns ?? []);
+      columns = names.map((name) => {
+        const c = own.get(name);
+        const text = c?.type ?? inherited.get(name);
+        if (text === undefined) return UNKNOWN_COLUMN(name);
+        const ty = pgType(p, text);
+        const notNull = c?.notNull === true || pk.has(name) || c?.generated?.kind === "identity" || ty.notNull;
+        return { name, sqlType: ty.sqlType, ts: ty.ts, nullable: !notNull, cmp: typeIdentity(p, text) };
+      });
+    } else {
+      columns = names.map((name) => {
+        const via = passthrough(o, name, quoteIdent);
+        const source = via && entryOf(via.export)?.columns.find((c) => c.name === via.column);
+        // A view's column is nullable to Postgres whatever it reads.
+        return source ? { ...source, name, nullable: source.nullable === "never" ? "never" : true } : UNKNOWN_COLUMN(name);
+      });
+    }
+    const slots = new Map<number, { type: string; note: string }>();
+    for (const s of getTypedSlots(entity)) {
+      if (s.kind !== "references") continue;
+      const cmp = columns.find((c) => c.name === s.column)?.cmp;
+      if (cmp !== undefined) slots.set(s.index, { type: `KeyColumn<${JSON.stringify(cmp)}>`, note: `the column ${s.column} references` });
+    }
+    const entry: RelationEntry = { key: relationKey(o as { schema?: string; name: string }), origin: originOf(entity, exportName, projectDir), columns, slots };
+    done.set(exportName, entry);
+    return entry;
+  };
+  return objects.filter((o) => PG_RELATIONS.has(o.type)).map((o) => entryOf(o.export)).filter((e): e is RelationEntry => e !== undefined);
+}
+
+// ── ClickHouse ──────────────────────────────────────────────────────────
+
+const CH_RELATIONS = new Set(["ClickHouse::Table", "ClickHouse::View", "ClickHouse::MaterializedView", "ClickHouse::Dictionary"]);
+
+function chColumn(name: string, type: string | undefined, nullableModifier: boolean | undefined): ColumnEntry {
+  if (!type) return UNKNOWN_COLUMN(name);
+  const sqlType = nullableModifier === true && !/^Nullable\s*\(/i.test(type.trim()) ? `Nullable(${type.trim()})` : type.trim();
+  const row = clickhouseRowType(sqlType);
+  return { name, sqlType, ts: row.ts, nullable: row.nullable, cmp: typeFamily(sqlType) || undefined };
+}
+
+function clickhouseEntries(objects: OutputObject[], entities: ReadonlyMap<string, Declarable>, projectDir: string): RelationEntry[] {
+  const byExport = new Map(objects.map((o) => [o.export, o]));
+  const done = new Map<string, RelationEntry | undefined>();
+  const entryOf = (exportName: string): RelationEntry | undefined => {
+    if (done.has(exportName)) return done.get(exportName);
+    done.set(exportName, undefined);
+    const o = byExport.get(exportName);
+    const entity = entities.get(exportName);
+    if (!o || !entity || !CH_RELATIONS.has(o.type)) return undefined;
+    const declared = new Map(((o.columns as Array<{ name: string; type?: string; nullable?: boolean }> | undefined) ?? []).map((c) => [c.name, c]));
+    const columns = runtimeColumns(entity).map((name) => {
+      const c = declared.get(name);
+      if (c) return chColumn(name, c.type, c.nullable);
+      const via = passthrough(o, name, quoteIdentifier);
+      const source = via && entryOf(via.export)?.columns.find((x) => x.name === via.column);
+      return source ? { ...source, name } : UNKNOWN_COLUMN(name);
+    });
+    const slots = new Map<number, { type: string; note: string }>();
+    for (const s of getTypedSlots(entity)) if (s.kind === "sortKey") slots.set(s.index, { type: "NotNullColumn", note: "a sort key element" });
+    const entry: RelationEntry = { key: relationKey(o as { database?: string; name: string }), origin: originOf(entity, exportName, projectDir), columns, slots };
+    done.set(exportName, entry);
+    return entry;
+  };
+  return objects.filter((o) => CH_RELATIONS.has(o.type)).map((o) => entryOf(o.export)).filter((e): e is RelationEntry => e !== undefined);
+}
+
+// ── Rendering ───────────────────────────────────────────────────────────
+
+const propertyName = (name: string): string => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+
+function renderEntry(e: RelationEntry, lines: string[]): void {
+  lines.push(`    /** ${e.origin.replace(/\*\//g, "* /")} */`, `    ${JSON.stringify(e.key)}: {`, "      columns: {");
+  for (const c of e.columns) {
+    const nullable = c.nullable === "never" ? "never" : String(c.nullable);
+    const cmp = c.cmp === undefined ? "never" : JSON.stringify(c.cmp);
+    lines.push(`        ${propertyName(c.name)}: Column<${JSON.stringify(c.sqlType)}, { ts: ${c.ts}; nullable: ${nullable}; cmp: ${cmp} }>;`);
+  }
+  lines.push("      };");
+  if (e.slots.size > 0) {
+    const last = Math.max(...e.slots.keys());
+    const types = Array.from({ length: last + 1 }, (_, i) => e.slots.get(i)?.type ?? "unknown");
+    const notes = [...e.slots].sort(([a], [b]) => a - b).map(([i, s]) => `\`\${}\` ${i + 1} is ${s.note}`);
+    lines.push(`      /** ${notes.join("; ")}. */`, `      slots: [${types.join(", ")}];`);
+  }
+  lines.push("    };");
+}
+
+/** The dialect a build's entities declare, else the config's, else ClickHouse. */
+function dialectOf(entities: ReadonlyMap<string, Declarable>, config: Record<string, unknown>): SqlDialect {
+  try {
+    return filesDialect(entities, config);
+  } catch {
+    return "clickhouse";
+  }
+}
+
+/**
+ * The `sql-types.d.ts` for a build's entities: one module that augments the
+ * dialect's `SqlSchema` with each table, view and dictionary, in key order.
+ * Pure, so a check can render it in memory and compare it with the file.
+ */
+export function renderSqlTypes(entities: ReadonlyMap<string, Declarable>, opts: RenderSqlTypesOptions = {}): string {
+  const config = opts.config ?? {};
+  const projectDir = opts.projectDir ?? process.cwd();
+  const dialect = dialectOf(entities, config);
+  const sqlEntities = new Map([...entities].filter(([, e]) => isPostgresObject(e) || isClickHouseObject(e)));
+  let entries: RelationEntry[] = [];
+  if (sqlEntities.size > 0) {
+    const out = sqlSerializer.serialize(new Map(entities), undefined, { config }) as SerializerResult | string;
+    const doc = JSON.parse(typeof out === "string" ? out : out.primary) as { objects: OutputObject[]; postgresMajor?: number };
+    entries = dialect === "postgres" ? postgresEntries(doc.objects, doc.postgresMajor ?? PINNED_MAJOR, entities, projectDir) : clickhouseEntries(doc.objects, entities, projectDir);
+  }
+  const byKey = new Map<string, RelationEntry>();
+  for (const e of entries) if (!byKey.has(e.key)) byKey.set(e.key, e);
+  const sorted = [...byKey.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+
+  const brands = new Set<string>();
+  if (sorted.length > 0) brands.add("Column");
+  for (const e of sorted) for (const s of e.slots.values()) brands.add(s.type.replace(/<.*$/, ""));
+  const module = SQL_TYPES_MODULE[dialect];
+  const lines = [
+    `// ${GENERATED_MARKER}. \`chant sql types\` writes it from the build's entities.`,
+    `import type ${brands.size > 0 ? `{ ${[...brands].sort().join(", ")} }` : "{}"} from ${JSON.stringify(module)};`,
+    "",
+    `declare module ${JSON.stringify(module)} {`,
+  ];
+  if (sorted.length === 0) lines.push("  interface SqlSchema {}");
+  else {
+    lines.push("  interface SqlSchema {");
+    for (const e of sorted) renderEntry(e, lines);
+    lines.push("  }");
+  }
+  lines.push("}");
+  return `${lines.join("\n")}\n`;
+}

package/src/typecheck.test.ts

@@ -23,6 +23,8 @@ import {
   type SkipIndexType,
   type SqlLiteral,
   type TableEngineName,
+  type UncheckedColumn,
+  type Unnamed,
 } from "./clickhouse";
 
 describe("the tags", () => {
@@ -32,9 +34,16 @@ describe("the tags", () => {
     const recent = view`CREATE VIEW ${db}.recent AS SELECT ${events.columns.user_id} FROM ${events}`;
 
     expectTypeOf(db).toEqualTypeOf<ClickHouseDatabase>();
-    expectTypeOf(events).toEqualTypeOf<ClickHouseTable>();
-    expectTypeOf(recent).toEqualTypeOf<ClickHouseView>();
-    expectTypeOf(events.columns.user_id).toEqualTypeOf<AttrRef>();
+    // No type argument: the relation is unnamed and its columns unchecked, each still an AttrRef.
+    expectTypeOf(events).toEqualTypeOf<ClickHouseTable<Unnamed>>();
+    expectTypeOf(recent).toEqualTypeOf<ClickHouseView<Unnamed>>();
+    expectTypeOf(events.columns.user_id).toEqualTypeOf<UncheckedColumn>();
+    expectTypeOf(events.columns.user_id).toExtend<AttrRef>();
+    expectTypeOf(events).toExtend<ClickHouseTable>();
+    // A name no generated declaration lists yet keeps unchecked columns too.
+    const fresh = table<"analytics.fresh">`CREATE TABLE ${db}.fresh (a UInt8) ENGINE = Log`;
+    expectTypeOf(fresh.columns.anything).toEqualTypeOf<UncheckedColumn>();
+    expectTypeOf(fresh).toExtend<ClickHouseTable>();
     expectTypeOf(events.entityType).toEqualTypeOf<"ClickHouse::Table">();
     expectTypeOf(db.entityType).toEqualTypeOf<"ClickHouse::Database">();
     expectTypeOf(recent.entityType).toEqualTypeOf<"ClickHouse::View" | "ClickHouse::MaterializedView">();

package/src/typed-columns.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Typed columns reach plain `tsc` (#3751). Each fixture project under
+ * `test-fixtures/typed-columns/` is built the way `chant sql types` builds
+ * it, its declarations rendered and compared with the committed
+ * `src/sql-types.d.ts`, and then the project is type-checked with the
+ * compiler options a strict application uses. tsc must report exactly the
+ * errors the fixture plants: a misspelled column, a foreign key between
+ * types that do not compare, a Nullable column in a sort key, and `RowOf` of
+ * a name no declaration has or of a relation with no name.
+ *
+ * The fixtures sit outside `src/` and are excluded from the repo's
+ * typecheck: their declarations augment `SqlSchema`, which would leak into
+ * every other program, and their errors are on purpose.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { describe, expect, test } from "vitest";
+import { build } from "@intentius/chant/build";
+import { resolveProjectBuildOptions } from "@intentius/chant/cli/build-options";
+import { sqlPlugin } from "./plugin";
+import { sqlSerializer } from "./serializer";
+import { renderSqlTypes, SQL_TYPES_FILE } from "./sql-types";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(here, "..", "..", "..");
+const fixtures = join(here, "..", "test-fixtures", "typed-columns");
+
+async function rendered(dir: string): Promise<string> {
+  const options = resolveProjectBuildOptions({ config: {}, configDir: dir, plugins: [sqlPlugin], modes: { fold: true, sandbox: false } });
+  const result = await build(join(dir, "src"), [sqlSerializer], undefined, options);
+  expect(result.errors.map(String)).toEqual([]);
+  return renderSqlTypes(result.entities, { projectDir: dir });
+}
+
+/** Every error tsc reports in the fixture's own files, as `file(line): TScode message`. */
+function tscErrors(dir: string): string[] {
+  const options: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ES2022,
+    lib: ["lib.es2023.d.ts"],
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    noUncheckedIndexedAccess: true,
+    exactOptionalPropertyTypes: true,
+    isolatedModules: true,
+    noEmit: true,
+    skipLibCheck: true,
+    types: ["node"],
+    typeRoots: [join(repoRoot, "node_modules", "@types")],
+    paths: {
+      "@intentius/chant": [join(repoRoot, "packages/core/src/index.ts")],
+      "@intentius/chant/*": [join(repoRoot, "packages/core/src/*")],
+      "@intentius/chant-lexicon-sql/*": [join(repoRoot, "lexicons/sql/src/*")],
+    },
+  };
+  const files = ts.sys.readDirectory(dir, [".ts"]);
+  const program = ts.createProgram(files, options);
+  const out: string[] = [];
+  for (const file of files) {
+    const sf = program.getSourceFile(file)!;
+    for (const d of [...program.getSyntacticDiagnostics(sf), ...program.getSemanticDiagnostics(sf)]) {
+      const { line } = sf.getLineAndCharacterOfPosition(d.start ?? 0);
+      out.push(`${relative(dir, file)}(${line + 1}): TS${d.code} ${ts.flattenDiagnosticMessageText(d.messageText, "\n").split("\n")[0]}`);
+    }
+  }
+  return out.sort();
+}
+
+describe("chant sql types, through tsc", () => {
+  test("Postgres: a misspelled column, a foreign key of another category and RowOf of no declaration fail; the rest compiles", async () => {
+    const dir = join(fixtures, "postgres");
+    expect(await rendered(dir)).toBe(readFileSync(join(dir, "src", SQL_TYPES_FILE), "utf8"));
+    expect(tscErrors(dir)).toEqual([
+      expect.stringMatching(/^checks\/misspelled\.ts\(4\): TS2551 Property 'emial' does not exist .* Did you mean 'email'\?$/),
+      expect.stringMatching(/^checks\/rows\.ts\(23\): TS2344 Type '"shop\.ordrs"' does not satisfy the constraint/),
+      expect.stringMatching(/^checks\/rows\.ts\(24\): TS2344 Type 'PostgresTable<Unnamed>' does not satisfy the constraint/),
+      expect.stringMatching(/^src\/refunds\.ts\(8\): TS2345 Argument of type 'Column<"bigint", .*' is not assignable to parameter of type 'KeyColumn<"S">'/),
+    ]);
+  }, 120_000);
+
+  test("ClickHouse: a Nullable column in a materialized view's ORDER BY and a misspelled column fail; the rest compiles", async () => {
+    const dir = join(fixtures, "clickhouse");
+    expect(await rendered(dir)).toBe(readFileSync(join(dir, "src", SQL_TYPES_FILE), "utf8"));
+    expect(tscErrors(dir)).toEqual([
+      expect.stringMatching(/^checks\/rows\.ts\(18\): TS2551 Property 'contry' does not exist .* Did you mean 'country'\?$/),
+      expect.stringMatching(/^src\/by-country\.ts\(7\): TS2345 Argument of type 'Column<"Nullable\(String\)", .*' is not assignable to parameter of type 'NotNullColumn'/),
+    ]);
+  }, 120_000);
+});