@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/sql-files.js

@@ -0,0 +1,206 @@
+/**
+ * Plain `.sql` files as a schema source (#3646): DDL read into the same
+ * declarations the tagged templates make. Also at the package root.
+ *
+ * - {@link readSqlFile}: the objects a file of DDL declares, each with its
+ *   export name, type, qualified name and DDL.
+ * - {@link sqlFileDeclarations}: the same file as TypeScript, one `schema.ts`
+ *   of `table`, `view`, ... templates, as `chant import <file>.sql` writes it.
+ * - {@link sqlFileEntities}: the declarations themselves, with the references
+ *   between the files' objects, and to objects declared elsewhere, as
+ *   interpolations, so dependency order comes from the graph. The build uses
+ *   it for every `.sql` file in the source directory.
+ *
+ * Postgres reads each `CREATE`, `GRANT`, `REVOKE` and `ALTER DEFAULT
+ * PRIVILEGES` as an object, with `COMMENT ON`, `ALTER TABLE ... ROW LEVEL
+ * SECURITY` and `ALTER TABLE ... ADD <table constraint>` folded into the
+ * object they finish; ClickHouse reads `CREATE DATABASE`, `TABLE`, `VIEW`,
+ * `MATERIALIZED VIEW`, `DICTIONARY`, `FUNCTION`, `USER`, `ROLE` and `ROW
+ * POLICY`, and `GRANT` (#3711). Any other statement, and any
+ * statement that does not parse, throws a {@link SqlFileError} naming every
+ * such statement: none is left out. A statement that parses except for a
+ * clause the parser does not know (#3872) is read, kept as written, and the
+ * clause listed in its object's `unparsed` with the line it is on.
+ *
+ * A name is a reference where it is qualified (`app.users`), or bare where an
+ * object is named (`REFERENCES users`, `FROM users`, an index's table, a
+ * column of an enum type) and an object declared without a schema has it.
+ */
+import { SqlFileError } from "./files/common.js";
+import { postgresTag, readPostgres, templateStrings } from "./files/postgres.js";
+import { clickhouseTag, readClickHouse } from "./files/clickhouse.js";
+import { exportNames as pgExportNames, objectsToIR as pgObjectsToIR } from "./postgres/import/ir.js";
+import { exportNames as chExportNames, objectsToIR as chObjectsToIR } from "./clickhouse/import/ir.js";
+import { PostgresGenerator, postgresTemplates } from "./postgres/import/generator.js";
+import { ClickHouseGenerator, clickhouseTemplates } from "./clickhouse/import/generator.js";
+import { isPostgresObject } from "./postgres/entities.js";
+import { isClickHouseObject } from "./clickhouse/entities.js";
+export { SqlFileError };
+const qualifierOf = (o) => ("schema" in o ? o.schema : "database" in o ? o.database : undefined);
+const qualifiedName = (o) => (qualifierOf(o) ? `${qualifierOf(o)}.${o.name}` : o.name);
+function readObjects(dialect, sources) {
+    const out = [];
+    for (const source of sources) {
+        const problems = [];
+        const objects = dialect === "postgres" ? readPostgres(source.ddl, source, problems) : readClickHouse(source.ddl, source, problems);
+        if (problems.length > 0)
+            throw new SqlFileError(source.origin, problems);
+        out.push(...objects.map((o) => ({ ...o, origin: source.origin })));
+    }
+    return out;
+}
+/** An object's line and unknown clauses, the fields that are set. */
+const fileMeta = (o) => ({ ...(o.line !== undefined ? { line: o.line } : {}), ...(o.unparsed ? { unparsed: o.unparsed } : {}) });
+/** Export names for objects read from files, unique across them. */
+function namesFor(dialect, objects) {
+    return dialect === "postgres" ? pgExportNames(objects) : chExportNames(objects);
+}
+/** The objects a file of DDL declares. Throws a {@link SqlFileError} naming each statement it cannot read. */
+export function readSqlFile(dialect, ddl, options) {
+    const objects = readObjects(dialect, [{ ...options, ddl }]);
+    const names = namesFor(dialect, objects);
+    return objects.map((o, i) => ({ export: names[i], type: o.type, name: qualifiedName(o), ddl: o.ddl, origin: o.origin, ...fileMeta(o) }));
+}
+/**
+ * A file of DDL as TypeScript declarations: the `schema.ts` `chant import`
+ * writes, with `header` as comment lines at its top, and the objects in it.
+ */
+export function sqlFileDeclarations(dialect, ddl, options) {
+    const objects = readObjects(dialect, [{ ...options, ddl }]);
+    if (objects.length === 0)
+        throw new SqlFileError(options.origin, ["the DDL creates no objects"]);
+    const ir = dialect === "postgres" ? pgObjectsToIR(objects) : chObjectsToIR(objects);
+    const files = dialect === "postgres" ? new PostgresGenerator(options.header).generate(ir) : new ClickHouseGenerator(options.header).generate(ir);
+    const [file] = files;
+    if (!file)
+        throw new SqlFileError(options.origin, ["the DDL creates no objects"]);
+    return {
+        content: file.content,
+        objects: ir.resources.map((r, i) => ({ export: r.logicalId, type: r.type, name: qualifiedName(objects[i]), ddl: objects[i].ddl, origin: options.origin, ...fileMeta(objects[i]) })),
+    };
+}
+/** Where an entity read from a `.sql` file came from: its `origin`. Undefined for any other entity. */
+export function sqlFileOf(entity) {
+    return typeof entity === "object" && entity !== null ? entity[FROM_FILE] : undefined;
+}
+/** The line an entity read from a `.sql` file starts on in it. Undefined for any other entity. */
+export function sqlFileLineOf(entity) {
+    return typeof entity === "object" && entity !== null ? entity[FROM_LINE] : undefined;
+}
+const FROM_FILE = Symbol.for("chant.sql.fromFile");
+const FROM_LINE = Symbol.for("chant.sql.fromLine");
+/** A declared entity as a template target: its export, type and name. */
+function targetOf(dialect, exportName, entity) {
+    const p = entity.props;
+    if (typeof p.name !== "string")
+        return undefined;
+    const qualifier = dialect === "postgres" ? p.schema : p.database;
+    return {
+        exportName,
+        type: entity.entityType,
+        ...(qualifier ? (dialect === "postgres" ? { schema: qualifier } : { database: qualifier }) : {}),
+        name: p.name,
+        ddl: typeof p.ddl === "string" ? p.ddl : "",
+    };
+}
+function templates(dialect, items, targets) {
+    return dialect === "postgres" ? postgresTemplates(items, targets) : clickhouseTemplates(items, targets);
+}
+/** The entities of one dialect in a set, by export name. */
+function ofDialect(dialect, entities) {
+    const is = dialect === "postgres" ? isPostgresObject : isClickHouseObject;
+    return new Map([...(entities ?? new Map())].filter(([, e]) => is(e)));
+}
+/**
+ * The declarations the files make, by export name. `known` holds the
+ * entities declared elsewhere (the project's tagged templates): a file's
+ * reference to one of them is an interpolation of it, as an import would
+ * write it, and an export name or an object one of them already declares is
+ * an error naming both.
+ */
+export function sqlFileEntities(dialect, sources, options = {}) {
+    const objects = readObjects(dialect, sources);
+    const names = namesFor(dialect, objects);
+    const known = ofDialect(dialect, options.known);
+    const problems = [];
+    const items = objects.map((o, i) => ({ exportName: names[i], type: o.type, ...("schema" in o && o.schema ? { schema: o.schema } : {}), ...("database" in o && o.database ? { database: o.database } : {}), name: o.name, ddl: o.ddl }));
+    const origin = new Map(objects.map((o, i) => [names[i], o.origin]));
+    const lineOf = new Map(objects.map((o, i) => [names[i], o.line]));
+    const knownItems = [...known].map(([n, e]) => targetOf(dialect, n, e)).filter((t) => t !== undefined);
+    const declared = new Map(knownItems.map((t) => [`${t.type} ${qualifiedName(t)}`, t.exportName]));
+    const seen = new Map();
+    const where = (at) => (sources.length > 1 && at ? `${at}: ` : "");
+    const label = sources.length === 1 ? sources[0].origin : "the .sql files";
+    for (const [i, it] of items.entries()) {
+        const what = `${it.type} ${qualifiedName(it)}`;
+        const at = objects[i].origin;
+        const q = qualifiedName(it);
+        if (options.known?.has(it.exportName))
+            problems.push(`${where(at)}${q} is exported as ${it.exportName}, a name another declaration already has; rename that one`);
+        const other = declared.get(what);
+        if (other)
+            problems.push(`${where(at)}${q} is declared twice, here and as ${other}; leave it to one of them`);
+        const again = seen.get(what);
+        if (again)
+            problems.push(`${where(at)}${q} is declared twice, here and in ${again}; leave it to one of them`);
+        seen.set(what, at);
+    }
+    if (problems.length > 0)
+        throw new SqlFileError(label, problems);
+    const { order, bodies } = templates(dialect, items, [...items, ...knownItems]);
+    const built = new Map();
+    const failed = new Set();
+    const tagOf = dialect === "postgres" ? postgresTag : clickhouseTag;
+    for (const it of order) {
+        const body = bodies.get(it.exportName);
+        const values = body.refs.map((r) => built.get(r) ?? known.get(r));
+        const missing = body.refs.find((_, i) => values[i] === undefined);
+        if (missing !== undefined) {
+            failed.add(it.exportName);
+            // What references an object that failed is not reported again.
+            if (failed.has(missing))
+                continue;
+            problems.push(`${where(origin.get(it.exportName))}${qualifiedName(it)} and ${missing} reference each other, which no declaration can; break the cycle`);
+            continue;
+        }
+        try {
+            const entity = tagOf(it.type)(templateStrings(body.parts), ...values);
+            Object.defineProperty(entity, FROM_FILE, { value: origin.get(it.exportName), enumerable: false });
+            if (lineOf.get(it.exportName) !== undefined)
+                Object.defineProperty(entity, FROM_LINE, { value: lineOf.get(it.exportName), enumerable: false });
+            built.set(it.exportName, entity);
+        }
+        catch (e) {
+            failed.add(it.exportName);
+            problems.push(`${where(origin.get(it.exportName))}${qualifiedName(it)}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (problems.length > 0)
+        throw new SqlFileError(label, problems);
+    // In the files' order, not the dependency order.
+    return new Map(items.filter((it) => built.has(it.exportName)).map((it) => [it.exportName, built.get(it.exportName)]));
+}
+/**
+ * The objects read from `.sql` files that each other object names in its
+ * DDL as text, by export name: a tagged template cannot import a file's
+ * object, so it names it, and this is the edge the dependency order needs.
+ * Empty when no object came from a file.
+ */
+export function sqlFileReferences(dialect, objects) {
+    const fromFiles = [...objects].filter(([, e]) => sqlFileOf(e) !== undefined);
+    const out = new Map();
+    if (fromFiles.length === 0)
+        return out;
+    const targets = fromFiles.map(([n, e]) => targetOf(dialect, n, e)).filter((t) => t !== undefined);
+    for (const [name, entity] of objects) {
+        if (sqlFileOf(entity) !== undefined)
+            continue;
+        const item = targetOf(dialect, name, entity);
+        if (!item || !item.ddl)
+            continue;
+        const refs = templates(dialect, [item], targets).bodies.get(name)?.refs ?? [];
+        if (refs.length > 0)
+            out.set(name, [...new Set(refs)]);
+    }
+    return out;
+}

package/dist/sql-types-command.js

@@ -0,0 +1,97 @@
+/**
+ * `chant sql types [--output <path>] [--check]` (#3751): build the project the way
+ * `chant build` does, folded, and write the declarations
+ * {@link renderSqlTypes} renders from its entities, so a tag given its
+ * qualified name as the type argument has typed columns.
+ *
+ * The file goes to `<sourceDir>/sql-types.d.ts` (the project root when
+ * `sourceDir` is unset), where any tsconfig that includes the schema includes
+ * it too. `--output` puts it elsewhere, as a workspace `generated` entry's
+ * generator does. The command refuses to write beside a `sql-types.ts`: tsc
+ * resolves the `.ts` first and would drop the declarations. `chant build`
+ * never writes the file. `--check` renders the same text and compares it with
+ * the file instead of writing it: exit 1, naming the file, when they differ.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { renderSqlTypes, SQL_TYPES_FILE } from "./sql-types.js";
+const USAGE = "usage: chant sql types [--output <path>] [--check]";
+/** The `--output` value, or an error message. */
+function parseArgs(args) {
+    let output;
+    let check = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--output") {
+            output = args[++i];
+            if (!output)
+                return { error: "--output needs a path" };
+        }
+        else if (a === "--check")
+            check = true;
+        else if (a.startsWith("--output="))
+            output = a.slice("--output=".length);
+        else
+            return { error: `unknown argument ${a}` };
+    }
+    return output === undefined ? { check } : { output, check };
+}
+/** The file tsc would read instead of `path`: `sql-types.ts` beside `sql-types.d.ts`. */
+export function shadowingSource(path) {
+    if (!path.endsWith(".d.ts"))
+        return undefined;
+    const source = `${path.slice(0, -".d.ts".length)}.ts`;
+    return existsSync(source) ? source : undefined;
+}
+export async function runTypes(ctx) {
+    const args = parseArgs(ctx.rawArgs);
+    if ("error" in args) {
+        console.error(`${args.error}\n${USAGE}`);
+        return 1;
+    }
+    const cwd = process.cwd();
+    const { loadChantConfigUpward } = await import("@intentius/chant/config");
+    const { config, configPath } = await loadChantConfigUpward(cwd);
+    const projectDir = configPath ? dirname(configPath) : cwd;
+    const sourceDir = resolve(projectDir, config.sourceDir ?? ".");
+    const output = args.output !== undefined ? resolve(cwd, args.output) : join(sourceDir, SQL_TYPES_FILE);
+    const shadow = shadowingSource(output);
+    if (shadow) {
+        console.error(`chant sql types: ${relative(cwd, shadow) || basename(shadow)} sits beside ${relative(cwd, output) || basename(output)}, and tsc reads it instead of the declarations; rename one`);
+        return 1;
+    }
+    const { build } = await import("@intentius/chant/build");
+    const { resolveBuildModes, resolveProjectBuildOptions } = await import("@intentius/chant/cli/build-options");
+    const { loadPlugins, resolveProjectLexicons } = await import("@intentius/chant/cli/plugins");
+    const { sqlSerializer } = await import("./serializer.js");
+    const plugins = await loadPlugins(await resolveProjectLexicons(projectDir, { lexicon: "sql" }));
+    // The fold build's entities: what `chant build` declares, `.sql` files and composite members included.
+    const options = resolveProjectBuildOptions({ config, configDir: projectDir, plugins, modes: resolveBuildModes(config, { fold: true }) });
+    const result = await build(sourceDir, [sqlSerializer], undefined, options);
+    if (result.errors.length > 0) {
+        for (const e of result.errors)
+            console.error(e instanceof Error ? e.message : String(e));
+        console.error("chant sql types: the build failed, so nothing was written");
+        return 1;
+    }
+    const text = renderSqlTypes(result.entities, { projectDir, config: config });
+    const shown = relative(cwd, output);
+    const named = shown && !shown.startsWith("..") ? shown : output;
+    if (args.check) {
+        // Compares only; the file is never written.
+        const onDisk = existsSync(output) ? readFileSync(output, "utf8") : undefined;
+        if (onDisk === text) {
+            console.log(`${named} is current`);
+            return 0;
+        }
+        console.error(onDisk === undefined
+            ? `chant sql types: ${named} does not exist; run \`chant sql types\` to write it`
+            : `chant sql types: ${named} differs from what the build declares; run \`chant sql types\` to rewrite it`);
+        return 1;
+    }
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, text);
+    const count = (text.match(/^ {4}"/gm) ?? []).length;
+    console.log(`wrote ${named}: ${count} relation${count === 1 ? "" : "s"}`);
+    return 0;
+}

package/dist/sql-types.js

@@ -0,0 +1,323 @@
+/**
+ * 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 column that carries a clause chant does not read (#3872) keeps the type
+ * that was read, with `nullable` and `cmp` `never`.
+ *
+ * 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 { GENERATED_MARKER } from "@intentius/chant/discovery/files";
+import { getProvenance } from "@intentius/chant/provenance";
+import { isPostgresObject } from "./postgres/entities.js";
+import { isClickHouseObject, quoteIdentifier } from "./clickhouse/entities.js";
+import { quoteIdent } from "./postgres/keywords.js";
+import { getTypedSlots, relationKey } from "./core/typed.js";
+import { sqlSerializer } from "./serializer.js";
+import { sqlFileOf } from "./sql-files.js";
+import { filesDialect } from "./files/build-root.js";
+import { POSTGRES_ROW_TYPES } from "./postgres/row-types.js";
+import { clickhouseRowType } from "./clickhouse/row-types.js";
+import { typeFamily } from "./lint/post-synth/clickhouse-helpers.js";
+import { PINNED_MAJOR } from "./lint/post-synth/postgres-helpers.js";
+import { parseType, projectFromObjects, resolveType, typeIdentity } from "./lint/post-synth/postgres-names.js";
+/** 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, config) {
+    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, file, opts = {}) {
+    if (!existsSync(file))
+        return "missing";
+    let onDisk;
+    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 = {
+    postgres: "@intentius/chant-lexicon-sql/postgres",
+    clickhouse: "@intentius/chant-lexicon-sql/clickhouse",
+};
+const UNKNOWN_COLUMN = (name) => ({ name, sqlType: "unknown", ts: "unknown", nullable: "never" });
+/** The columns that carry a clause chant does not read (#3872). */
+const opaqueColumns = (o) => new Set((o.unparsed ?? []).flatMap((u) => (u.column !== undefined ? [u.column] : [])));
+/**
+ * A column with a clause chant does not read (#3872): its type is what was
+ * read, but whether it can be NULL and how it compares in a key are not
+ * told, so it fits every slot rather than a guessed one.
+ */
+const opaque = (c) => ({ name: c.name, sqlType: c.sqlType, ts: c.ts, nullable: "never" });
+const posix = (p) => p.split(sep).join("/");
+/** Where a declaration came from: its file relative to the project, and its export. */
+function originOf(entity, exportName, projectDir) {
+    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) => Object.keys(entity?.columns ?? {});
+/** Whether `expr` is the column `column` alone, bare or qualified (`o.user_id`). */
+function isBareColumn(expr, quoted) {
+    const unqualified = expr.trim().replace(/^(?:"(?:[^"]|"")+"|`(?:[^`]|``)+`|[A-Za-z_][\w$]*)\./, "");
+    return unqualified === quoted;
+}
+/** A view's column that passes one column through: that column's export and name. */
+function passthrough(o, name, quote) {
+    const edge = (o.lineage ?? []).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, t) {
+    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) => `${/[|&]/.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, text, depth = 0) {
+    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) => (t.array ? { sqlType: `${x.sqlType}[]`, ts: arrayOf(x.ts), notNull: x.notNull } : x);
+    if (r.kind === "builtin") {
+        const ts = POSTGRES_ROW_TYPES[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 ?? [];
+            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, 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 };
+}
+function postgresEntries(objects, major, entities, projectDir) {
+    const p = projectFromObjects(objects, major);
+    const done = new Map();
+    const entryOf = (exportName) => {
+        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;
+        if (o.type === "Postgres::Table") {
+            const t = o;
+            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();
+            for (const parent of [...(t.inherits ?? []), ...(t.partitionOf !== undefined ? [t.partitionOf] : [])]) {
+                const pt = typeof parent === "string" ? p.byExport.get(parent) : 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 ?? []);
+            const unread = opaqueColumns(o);
+            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;
+                const entry = { name, sqlType: ty.sqlType, ts: ty.ts, nullable: !notNull, cmp: typeIdentity(p, text) };
+                return unread.has(name) ? opaque(entry) : entry;
+            });
+        }
+        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();
+        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 = { key: relationKey(o), 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 !== undefined);
+}
+// ── ClickHouse ──────────────────────────────────────────────────────────
+const CH_RELATIONS = new Set(["ClickHouse::Table", "ClickHouse::View", "ClickHouse::MaterializedView", "ClickHouse::Dictionary"]);
+function chColumn(name, type, nullableModifier) {
+    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, entities, projectDir) {
+    const byExport = new Map(objects.map((o) => [o.export, o]));
+    const done = new Map();
+    const entryOf = (exportName) => {
+        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 ?? []).map((c) => [c.name, c]));
+        const unread = opaqueColumns(o);
+        const columns = runtimeColumns(entity).map((name) => {
+            const c = declared.get(name);
+            if (c)
+                return unread.has(name) ? opaque(chColumn(name, c.type, c.nullable)) : 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();
+        for (const s of getTypedSlots(entity))
+            if (s.kind === "sortKey")
+                slots.set(s.index, { type: "NotNullColumn", note: "a sort key element" });
+        const entry = { key: relationKey(o), 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 !== undefined);
+}
+// ── Rendering ───────────────────────────────────────────────────────────
+const propertyName = (name) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+function renderEntry(e, lines) {
+    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, config) {
+    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, opts = {}) {
+    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 = [];
+    if (sqlEntities.size > 0) {
+        const out = sqlSerializer.serialize(new Map(entities), undefined, { config });
+        const doc = JSON.parse(typeof out === "string" ? out : out.primary);
+        entries = dialect === "postgres" ? postgresEntries(doc.objects, doc.postgresMajor ?? PINNED_MAJOR, entities, projectDir) : clickhouseEntries(doc.objects, entities, projectDir);
+    }
+    const byKey = new Map();
+    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();
+    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`;
+}