@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/codegen/package.js

@@ -0,0 +1,28 @@
+/**
+ * sql lexicon packaging, delegating to core's packagePipeline.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+// src/codegen/package.ts -> src/
+const srcDir = dirname(moduleSourceDir(import.meta.url));
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: () => ({
+            name: "sql",
+            version: pkgJson.version ?? "0.0.1",
+            chantVersion: ">=0.1.0",
+            namespace: "SQL",
+            intrinsics: [],
+            pseudoParameters: {},
+        }),
+        srcDir,
+        // No skills yet; they arrive with chant #3211.
+        collectSkills: () => new Map(),
+        version: pkgJson.version ?? "0.0.1",
+    }, opts);
+}

package/dist/codegen/postgres-classifier-page.js

@@ -0,0 +1,95 @@
+/**
+ * `docs/pages/postgres-change-classifier.mdx`, written from the Postgres
+ * classifier's own rule table by `npm run docs`, so the page cannot disagree
+ * with the rules.
+ */
+import { PG_CHANGE_CLASSES, PG_CLASSIFIER_RULES } from "../postgres/plan/rules.js";
+const cell = (s) => s.replace(/\|/g, "\\|");
+export function renderPostgresClassifierPage() {
+    const rows = Object.values(PG_CLASSIFIER_RULES).map((r) => `| ${r.id} | ${PG_CHANGE_CLASSES.label[r.class]} | ${cell(r.title)} | ${cell(r.restriction)} [Postgres 18 docs](${r.cite}) |`);
+    return `---
+title: "Postgres Locks and the Change Classifier"
+label: "Locks and the Change Classifier"
+description: "How a Postgres schema change is classified by the lock it takes and whether it reads or rewrites the table, each with the documentation behind it"
+diataxis: reference
+group: "Postgres"
+order: 11
+---
+
+{/* Written by src/codegen/postgres-classifier-page.ts from src/postgres/plan/rules.ts. Edit the rules, then run npm run docs. */}
+
+Every change between two Postgres schemas is classified before anything runs, by the lock it takes and whether it reads or rewrites the table, as the Postgres 18 reference states them. Where 14 to 17 differ, the rule says so.
+
+| Class | Means | Disruption |
+|---|---|---|
+| create | a new object; nothing that exists changes | \`in-place\` |
+| metadata only | a catalog change under a brief lock; no row is read or written | \`in-place\` |
+| validates under a weaker lock | every row is read to check a constraint, under a lock weaker than ACCESS EXCLUSIVE | \`rolling\` |
+| needs CONCURRENTLY | an index build or drop that blocks writes unless it is CONCURRENTLY, which cannot run in a transaction block | \`rolling\` |
+| ACCESS EXCLUSIVE rewrite or scan | the table is rewritten or read in full while reads and writes wait | \`rolling\` |
+| expand and contract | no in-place change keeps old readers working; a plan refuses it | \`replace\` |
+| drop | the object, and a table's or sequence's data, is gone | \`destroy\` |
+
+The disruption column is what \`chant lifecycle plan\` reports for each update. A changed path alone cannot always say which rule applies (a column's type, a constraint, a view's query, an enum's labels), and those report \`unknown\` there; \`chant sql plan\` has both definitions and classifies them.
+
+\`\`\`bash
+chant sql diff base.json head.json     # two chant build outputs, offline
+chant sql plan prod schema.json        # a build output against the prod server
+\`\`\`
+
+Both read the build's \`dialect\` and exit 2 when a change can only be made as expand and contract. \`--json\` prints the changes, the hints, the refused changes and the migration Op suggestions as one document. \`chant sql diff\` compares a pull request's base and head builds with no server. \`chant sql plan\` reads the server \`sql.profiles.<env>\` binds (else \`POSTGRES_URL\`), in the profile's \`schemas\` when it lists them, otherwise in the default schema and every schema the build declares an object in. Where the normalization rules leave an expression different, it asks that server: the declared view, or the table's column types, defaults, generated expressions and checks, are created as temporary objects in a transaction that is always rolled back, and read back with the same printers, so a view's \`SELECT *\` and the server's added parentheses are not reported as changes.
+
+A clause chant's parser does not know ([Plain .sql Files](../sql-files/#clauses-chant-does-not-read)) is compared as text, and the rest of its object is planned as usual. A change to one is SQLPG299, refused for review with no migration Op suggested, since chant cannot tell which lock the change takes. A clause only the server prints is a hint, not a change.
+
+## Statements for a migration file
+
+\`chant sql diff base.json head.json --statements\` prints the statements that take the base schema to the head one, offline: each one the applier would send for the same change, after a comment naming its object, rule and class, and whether it has to run outside a transaction block. \`--json\` prints them as one document, which \`diffStatements(before, after)\` from \`@intentius/chant-lexicon-sql\` also returns, each statement with \`transactional\` set:
+
+\`\`\`sql
+-- users (app.users): SQLPG201 metadata
+ALTER TABLE app.users ADD COLUMN name text DEFAULT 'none' NOT NULL;
+
+-- usersEmail (app.users_email_idx): SQLPG240 concurrently, outside a transaction
+CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email);
+
+-- orders (app.orders): SQLPG205 made by PostgresMigrationOp, not a statement:
+--   export const { op } = PostgresMigrationOp({ name: "migrate-app-orders-reference", env: "<env>", table: "app.orders", column: "reference" });
+\`\`\`
+
+A column rename or a type change across kinds is never DDL: it is a step naming \`PostgresMigrationOp\`, one per column. Any other expand-and-contract change, and the refused table's other changes, which the applier also holds back, are a manual step. A column or object drop is a statement marked destructive. Statements use the default schema for a bare name, as the applier sets \`search_path\`. The command exits 2 when a step is not a statement. What the applier asks the server is left out: its normalization of expressions the rules leave different, and an extension's own comment.
+
+## Which major
+
+Two rules change class across the supported majors: a STORED generated column's expression (SQLPG212) is a rewrite from 17 and expand and contract before it, and a table's access method (SQLPG226) is a rewrite from 15 and expand and contract before it.
+
+- \`chant sql diff\` classifies for the major the builds recorded (\`postgresMajor\` in the build output): the newer build's, else the older build's, else \`sql.postgresMajor\`, else 18. A diff between two revisions does not depend on today's config.
+- \`chant sql plan\` classifies for the major the server runs (\`server_version_num\`), since the server is what takes the locks. When the build targets another major, the plan says so in a hint.
+
+## Identity and renames
+
+An object is identified by its export name between two builds, and by its schema-qualified name against a server, which has no export names. Tables, views, materialized views, sequences and indexes share one namespace per schema, types and domains another, and schemas and extensions are matched by name. Functions, procedures and aggregates share a namespace of their own and are told apart by their input parameter types, so an overload is another object; composite and range types share the types' namespace, collations have one of their own, a cast is named by its two types and an event trigger by its name in the database; a trigger is matched by its name on its table.
+
+A rename is declared where it happens. Before a CREATE, \`-- previously: <old name>\` says the object had another name; on a column's line, it says the column did:
+
+\`\`\`sql
+CREATE TABLE app.orders (
+  id   bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  memo text   -- previously: note
+)
+\`\`\`
+
+Without the hint, a column dropped and another added with the same type in the same place are reported as a drop and an add, with a hint asking whether it is a rename. A constraint left unnamed is matched by what it says, not by the name Postgres gave it, and an index on a table the same plan creates is part of the create.
+
+An object another tool keeps is never proposed for a drop: an ORM's or migration runner's revision table with its sequence and indexes, and, with \`sql.provider\` set, the provider's own schemas and extensions. The plan names each in a hint and leaves it alone. Any other object in the schemas the plan reads that the build does not declare is a drop (SQLPG270); the applier drops it only when told to prune and only when it carries this project's marker.
+
+## After the plan
+
+The plan only reports. [\`postgresApply\`](../postgres-applying/) makes every change that is not expand and contract, grouping the statements into transactions by class and running \`CONCURRENTLY\` builds outside them. A column rename (SQLPG205) or a type change across kinds (SQLPG208) runs as \`PostgresMigrationOp\`, and both commands print the declaration to start from for each such column (\`migrationOps\` in \`--json\`): see [Migrating a Column](../postgres-migration/). The other expand-and-contract changes (a NOT NULL column with no default, a view losing or reordering columns, partitioning, a rename of a table, an enum label removed) have no Op yet and are made by hand.
+
+## The rules
+
+| Id | Class | Change | Restriction |
+|---|---|---|---|
+${rows.join("\n")}
+`;
+}

package/dist/codegen/postgres-module.js

@@ -0,0 +1,418 @@
+/**
+ * Render the Postgres dialect's generated surface from the catalogs of every
+ * supported major:
+ *
+ * - `src/generated/postgres-types.ts`: string-literal unions of every named
+ *   thing in any major's catalog, the `Settings` and `StorageParams_*`
+ *   interfaces, and the `VERSION_RANGES` table saying which entries are not in
+ *   all majors.
+ * - `src/generated/postgres.ts`: the tables lint and the LSP read (settings,
+ *   storage parameters, column types), with the overlays merged in.
+ *
+ * The overlays are checked against the catalogs in both directions. An overlay
+ * key no major has, or a storage parameter the probe found with no overlay
+ * entry, is an error: a pin move that changes the grammar has to change the
+ * overlay in the same commit.
+ *
+ * Output depends only on the catalogs and the overlays: every map is walked
+ * in sorted order (by code unit, not locale), so two runs are byte-identical.
+ */
+import { COLUMN_TYPE_PARAMETERS, SERIAL_TYPES, TYPE_SPELLINGS } from "../postgres/overlays/types.js";
+import { STORAGE_PARAMETER_TYPES } from "../postgres/overlays/storage.js";
+import { CONSTRAINTS } from "../postgres/overlays/constraints.js";
+import { COLUMN_CLAUSES } from "../postgres/overlays/columns.js";
+import { PARTITIONING } from "../postgres/overlays/partitioning.js";
+import { INDEX_CLAUSES } from "../postgres/overlays/indexes.js";
+import { RELATION_CLAUSES, SEQUENCE_CLAUSES, VIEW_CLAUSES } from "../postgres/overlays/relations.js";
+import { TYPE_DDL } from "../postgres/overlays/type-ddl.js";
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const sorted = (xs) => [...new Set(xs)].sort(compare);
+const lit = (names) => names.length > 0 ? names.map((n) => JSON.stringify(n)).join(" | ") : "never";
+const key = (name) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+const doc = (text) => text.replace(/\*\//g, "*\\/");
+const identifier = (name) => name.replace(/[^A-Za-z0-9]+/g, "_");
+/**
+ * Merge `pick(catalog)` across the majors by `keyOf`. `since` and `until` are
+ * set when the name is missing from the oldest or the newest major. A name
+ * with a gap (in 14, gone in 15, back in 16) is an error: a range cannot say it.
+ */
+function union(what, catalogs, pick, keyOf, errors) {
+    const byName = new Map();
+    catalogs.forEach((c, index) => {
+        for (const row of pick(c)) {
+            const k = keyOf(row);
+            const list = byName.get(k);
+            if (list)
+                list.push({ index, row });
+            else
+                byName.set(k, [{ index, row }]);
+        }
+    });
+    const last = catalogs.length - 1;
+    const out = [];
+    for (const name of sorted(byName.keys())) {
+        const present = byName.get(name);
+        const first = present[0].index;
+        const end = present[present.length - 1].index;
+        if (end - first + 1 !== present.length) {
+            errors.push(`${what} ${name} is present in non-adjacent majors (${present.map((p) => majorOfIndex(catalogs, p.index)).join(", ")})`);
+        }
+        out.push({
+            name,
+            latest: present[present.length - 1].row,
+            rows: present.map((p) => p.row),
+            range: {
+                ...(first > 0 ? { since: majorOfIndex(catalogs, first) } : {}),
+                ...(end < last ? { until: majorOfIndex(catalogs, end) } : {}),
+            },
+        });
+    }
+    return out;
+}
+const majorOfIndex = (catalogs, i) => Number.parseInt(catalogs[i].version, 10);
+const bounded = (r) => r.since !== undefined || r.until !== undefined;
+/** ` | @since 15 | @until 17` */
+function rangeTags(r) {
+    return [...(r.since !== undefined ? [`@since ${r.since}`] : []), ...(r.until !== undefined ? [`@until ${r.until}`] : [])];
+}
+function settingTsType(rows) {
+    const parts = new Set();
+    for (const s of rows) {
+        if (s.enumvals)
+            for (const v of s.enumvals)
+                parts.add(JSON.stringify(v));
+        else
+            parts.add({ bool: "boolean", integer: "number", real: "number", string: "string" }[s.type] ?? "string");
+    }
+    // `string` absorbs literals; a union of the two is the same type and noisier.
+    return parts.has("string") ? "string" : [...parts].sort(compare).join(" | ");
+}
+function storageTsType(t) {
+    if (t.kind === "boolean")
+        return "boolean";
+    if (t.kind === "enum")
+        return lit(t.values);
+    return "number";
+}
+function checkClauses(file, table, majors, errors) {
+    const lo = majors[0];
+    const hi = majors[majors.length - 1];
+    for (const [name, clause] of Object.entries(table)) {
+        for (const bound of [clause.since, clause.until]) {
+            if (bound !== undefined && (bound < lo || bound > hi)) {
+                errors.push(`overlays/${file}: ${name} has a bound ${bound} outside the supported majors ${lo}..${hi}`);
+            }
+        }
+    }
+}
+export function renderPostgresModule(catalogs) {
+    if (catalogs.length === 0)
+        throw new Error("no Postgres catalog was read");
+    const errors = [];
+    const notes = [];
+    const majors = catalogs.map((c) => Number.parseInt(c.version, 10));
+    // ── Union of every section ─────────────────────────────────────────
+    const types = union("type", catalogs, (c) => c.types.filter((t) => t.kind !== "p"), (t) => t.name, errors);
+    const accessMethods = union("access method", catalogs, (c) => c.accessMethods, (a) => a.name, errors);
+    const opclasses = union("operator class", catalogs, (c) => c.opclasses, (o) => `${o.am}.${o.name}`, errors);
+    const functions = union("function", catalogs, (c) => c.functions.filter((f) => !f.internal), (f) => f.name, errors);
+    const settings = union("setting", catalogs, (c) => c.settings, (s) => s.name, errors);
+    const keywords = union("keyword", catalogs, (c) => c.keywords, (k) => `${k.code}:${k.word}`, errors);
+    const extensions = union("extension", catalogs, (c) => c.extensions, (e) => e.name, errors);
+    const storage = union("storage parameter", catalogs, (c) => Object.entries(c.storageParameters).flatMap(([target, names]) => names.map((name) => ({ target, name }))), (p) => `${p.target}.${p.name}`, errors);
+    // ── Cross-checks of the overlays against the catalogs ──────────────
+    const sqlNames = new Set(types.map((t) => t.latest.sqlName));
+    for (const name of Object.keys(COLUMN_TYPE_PARAMETERS)) {
+        if (!sqlNames.has(name))
+            errors.push(`overlays/types.ts: type ${name} is not in any catalog`);
+    }
+    for (const [spelling, canonical] of [...Object.entries(TYPE_SPELLINGS), ...Object.entries(SERIAL_TYPES)]) {
+        if (!sqlNames.has(canonical))
+            errors.push(`overlays/types.ts: ${spelling} stands for ${canonical}, which is not in any catalog`);
+    }
+    const probed = new Set(storage.map((p) => p.latest.name));
+    for (const name of Object.keys(STORAGE_PARAMETER_TYPES)) {
+        if (!probed.has(name))
+            errors.push(`overlays/storage.ts: storage parameter ${name} was not accepted by any server`);
+    }
+    for (const name of probed) {
+        if (!STORAGE_PARAMETER_TYPES[name])
+            errors.push(`overlays/storage.ts: storage parameter ${name} has no entry`);
+    }
+    const indexMethods = new Set(accessMethods.filter((a) => a.latest.type === "i").map((a) => a.name));
+    for (const v of CONSTRAINTS.exclude.args.find((a) => a.name === "using")?.values ?? []) {
+        if (!indexMethods.has(v))
+            errors.push(`overlays/constraints.ts: exclusion method ${v} is not an index access method`);
+    }
+    for (const [file, table] of [
+        ["constraints.ts", CONSTRAINTS],
+        ["columns.ts", COLUMN_CLAUSES],
+        ["partitioning.ts", PARTITIONING],
+        ["indexes.ts", INDEX_CLAUSES],
+        ["relations.ts", { ...RELATION_CLAUSES, ...VIEW_CLAUSES, ...SEQUENCE_CLAUSES }],
+        ["type-ddl.ts", TYPE_DDL],
+    ]) {
+        checkClauses(file, table, majors, errors);
+    }
+    if (errors.length > 0) {
+        throw new Error(`The Postgres overlays disagree with the catalogs at ${catalogs.map((c) => c.version).join(", ")}:\n  ${errors.join("\n  ")}\n` +
+            "Update src/postgres/overlays/ for these pins.");
+    }
+    // ── Ranges ─────────────────────────────────────────────────────────
+    const ranges = {};
+    const addRanges = (section, entries) => {
+        const out = {};
+        for (const e of entries)
+            if (bounded(e.range))
+                out[e.name] = e.range;
+        ranges[section] = out;
+    };
+    addRanges("types", types);
+    addRanges("accessMethods", accessMethods);
+    addRanges("opclasses", opclasses);
+    addRanges("functions", functions);
+    addRanges("settings", settings);
+    addRanges("extensions", extensions);
+    addRanges("storageParameters", storage);
+    for (const code of ["R", "T", "C", "U"]) {
+        addRanges(`keywords${code}`, keywords.filter((k) => k.latest.code === code).map((k) => ({ name: k.latest.word, range: k.range })));
+    }
+    // Enum members that are not in every major a setting is in: `wal_compression` gains `lz4` in 15.
+    const settingValues = {};
+    for (const s of settings) {
+        const members = union(`setting ${s.name} value`, catalogs, (c) => c.settings.find((x) => x.name === s.name)?.enumvals ?? [], (v) => v, errors);
+        const own = {};
+        for (const m of members) {
+            // Relative to the majors that have the setting at all, not to all majors.
+            const since = m.range.since !== undefined && m.range.since > (s.range.since ?? majors[0]) ? m.range.since : undefined;
+            const lastOfSetting = s.range.until ?? majors[majors.length - 1];
+            const until = m.range.until !== undefined && m.range.until < lastOfSetting ? m.range.until : undefined;
+            if (since !== undefined || until !== undefined) {
+                own[m.name] = { ...(since !== undefined ? { since } : {}), ...(until !== undefined ? { until } : {}) };
+            }
+        }
+        if (Object.keys(own).length > 0)
+            settingValues[s.name] = own;
+    }
+    if (errors.length > 0)
+        throw new Error(`Postgres setting values: ${errors.join("; ")}`);
+    const rangeLiteral = (r) => `{ ${[...(r.since !== undefined ? [`since: ${r.since}`] : []), ...(r.until !== undefined ? [`until: ${r.until}`] : [])].join(", ")} }`;
+    const rangesTable = [
+        `export const VERSION_RANGES = {`,
+        ...Object.entries(ranges).flatMap(([section, entries]) => Object.keys(entries).length === 0
+            ? [`  ${section}: {},`]
+            : [
+                `  ${section}: {`,
+                ...Object.entries(entries).map(([name, r]) => `    ${JSON.stringify(name)}: ${rangeLiteral(r)},`),
+                `  },`,
+            ]),
+        `  settingValues: {`,
+        ...Object.entries(settingValues).flatMap(([name, members]) => [
+            `    ${JSON.stringify(name)}: {`,
+            ...Object.entries(members).map(([m, r]) => `      ${JSON.stringify(m)}: ${rangeLiteral(r)},`),
+            `    },`,
+        ]),
+        `  },`,
+        `} as const satisfies Record<string, Record<string, VersionRange | Record<string, VersionRange>>>;`,
+    ];
+    // ── Declarations ───────────────────────────────────────────────────
+    const aliases = types.filter((t) => t.latest.sqlName !== t.latest.name).map((t) => [t.latest.name, t.latest.sqlName]);
+    const keywordNames = (code) => keywords.filter((k) => k.latest.code === code).map((k) => k.latest.word);
+    const byAm = new Map();
+    for (const o of opclasses) {
+        const list = byAm.get(o.latest.am);
+        if (list)
+            list.push(o.latest.name);
+        else
+            byAm.set(o.latest.am, [o.latest.name]);
+    }
+    const settingLines = [];
+    for (const s of settings) {
+        const tags = [doc(s.latest.category), `@context ${s.latest.context}`];
+        if (s.latest.unit)
+            tags.push(`@unit ${s.latest.unit}`);
+        if (s.latest.default !== null)
+            tags.push(`@default ${doc(JSON.stringify(s.latest.default))}`);
+        tags.push(...rangeTags(s.range));
+        settingLines.push(`  /** ${tags.join(" | ")} */`, `  ${key(s.name)}?: ${settingTsType(s.rows)};`);
+    }
+    const storageTargets = sorted(storage.map((p) => p.latest.target));
+    const storageInterfaces = storageTargets.flatMap((target) => [
+        `export interface StorageParams_${identifier(target)} {`,
+        ...storage
+            .filter((p) => p.latest.target === target)
+            .flatMap((p) => {
+            const tags = rangeTags(p.range);
+            return [
+                ...(tags.length > 0 ? [`  /** ${tags.join(" | ")} */`] : []),
+                `  ${key(p.latest.name)}?: ${storageTsType(STORAGE_PARAMETER_TYPES[p.latest.name])};`,
+            ];
+        }),
+        "}",
+        "",
+    ]);
+    const header = (what) => [
+        `// Generated by \`npm run generate\` from the Postgres catalogs at ${catalogs.map((c) => c.version).join(", ")}`,
+        `// (src/spec/postgres-catalog-<major>.snapshot.json) and the overlays in src/postgres/overlays/. Do not edit.`,
+        `// ${what}`,
+        "",
+    ];
+    const declarations = [
+        ...header("The type surface: the union of every supported major, with a range on each name that is not in all of them."),
+        `import type { VersionRange } from "../postgres/catalog-types.js";`,
+        "",
+        `/** The supported majors, oldest first. */`,
+        `export const POSTGRES_MAJORS = ${JSON.stringify(majors)} as const;`,
+        `export type PostgresMajor = (typeof POSTGRES_MAJORS)[number];`,
+        `/** The exact release each major's catalog was read from. */`,
+        `export const POSTGRES_VERSIONS = ${JSON.stringify(Object.fromEntries(catalogs.map((c, i) => [majors[i], c.version])))} as const;`,
+        "",
+        `export type TypeName = ${lit(types.map((t) => t.name))};`,
+        `export type TypeSqlName = ${lit(sorted(types.map((t) => t.latest.sqlName)))};`,
+        `export const TYPE_ALIASES = ${JSON.stringify(Object.fromEntries(aliases))} as const;`,
+        "",
+        `export type IndexAccessMethod = ${lit(accessMethods.filter((a) => a.latest.type === "i").map((a) => a.name))};`,
+        `export type TableAccessMethod = ${lit(accessMethods.filter((a) => a.latest.type === "t").map((a) => a.name))};`,
+        ...[...byAm].map(([am, names]) => `export type OpClass_${identifier(am)} = ${lit(names)};`),
+        "",
+        `export type ReservedKeyword = ${lit(keywordNames("R"))};`,
+        `export type ReservedAsFunctionKeyword = ${lit(keywordNames("T"))};`,
+        `export type ColumnNameKeyword = ${lit(keywordNames("C"))};`,
+        `export type UnreservedKeyword = ${lit(keywordNames("U"))};`,
+        "",
+        `export type AggregateFunctionName = ${lit(functions.filter((f) => f.latest.kinds.includes("a")).map((f) => f.name))};`,
+        `export type ScalarFunctionName = ${lit(functions.filter((f) => f.latest.kinds.includes("f")).map((f) => f.name))};`,
+        `export type ExtensionName = ${lit(extensions.map((e) => e.name))};`,
+        "",
+        `/** Server settings, \`SET\` and \`postgresql.conf\` names, from \`pg_settings\`. */`,
+        `export interface Settings {`,
+        ...settingLines,
+        `}`,
+        "",
+        ...storageInterfaces,
+        `/** The names that are not in every supported major, with the major they arrived in and the last that has them. */`,
+        ...rangesTable,
+        "",
+    ].join("\n");
+    const settingTable = [
+        `export const SETTINGS: Readonly<Record<keyof Settings, SettingSpec>> = {`,
+        ...settings.map((s) => {
+            const r = s.latest;
+            const spec = {
+                type: r.type,
+                context: r.context,
+                category: r.category,
+                ...(r.unit ? { unit: r.unit } : {}),
+                ...(r.default !== null ? { default: r.default } : {}),
+                ...(r.min !== null ? { min: r.min } : {}),
+                ...(r.max !== null ? { max: r.max } : {}),
+            };
+            return `  ${key(s.name)}: ${JSON.stringify(spec)},`;
+        }),
+        "};",
+    ];
+    const storageNames = sorted(storage.map((p) => p.latest.name));
+    const storageTable = [
+        `export const STORAGE_PARAMETERS: Readonly<Record<string, StorageParameterSpec>> = {`,
+        ...storageNames.map((name) => {
+            const targets = sorted(storage.filter((p) => p.latest.name === name).map((p) => p.latest.target));
+            return `  ${key(name)}: ${JSON.stringify({ type: STORAGE_PARAMETER_TYPES[name], targets })},`;
+        }),
+        "};",
+    ];
+    const spellingsOf = new Map();
+    const spell = (canonical, alias) => spellingsOf.set(canonical, [...(spellingsOf.get(canonical) ?? []), alias]);
+    for (const [a, canonical] of Object.entries(TYPE_SPELLINGS))
+        spell(canonical, a);
+    for (const t of types)
+        if (t.latest.sqlName !== t.latest.name)
+            spell(t.latest.sqlName, t.latest.name);
+    const canonicalTypes = new Map();
+    for (const t of types)
+        canonicalTypes.set(t.latest.sqlName, t.latest);
+    const typeTable = [
+        `export const COLUMN_TYPES: Readonly<Record<TypeSqlName, ColumnTypeSpec>> = {`,
+        ...[...canonicalTypes.keys()].sort(compare).map((name) => {
+            const t = canonicalTypes.get(name);
+            const spec = {
+                ...(t.name !== name ? { catalogName: t.name } : {}),
+                category: t.category,
+                aliases: sorted(spellingsOf.get(name) ?? []),
+                parameters: COLUMN_TYPE_PARAMETERS[name] ?? [],
+            };
+            return `  ${key(name)}: ${JSON.stringify(spec)},`;
+        }),
+        "};",
+    ];
+    // The parser's ColId rule and identifier quoting read the latest major's key words (#3279).
+    const keywordTable = [
+        `/** Every key word at the latest pinned major, by its \`pg_get_keywords()\` category: U unreserved, C column name, T type or function name, R reserved. */`,
+        `export const KEYWORDS: Readonly<Record<string, "U" | "C" | "T" | "R">> = {`,
+        ...keywords
+            .filter((k) => k.range.until === undefined)
+            .map((k) => k.latest)
+            .sort((a, b) => compare(a.word, b.word))
+            .map((k) => `  ${key(k.word)}: ${JSON.stringify(k.code)},`),
+        "};",
+    ];
+    // Names lint checks a declaration against, each with the majors that have it
+    // (`true`: every supported major). Read straight off the catalogs, internal
+    // functions included: a column default may call `pg_current_xact_id()`.
+    const presence = (lists) => {
+        const out = new Map();
+        lists.forEach((names, i) => {
+            for (const n of new Set(names))
+                out.set(n, [...(out.get(n) ?? []), majors[i]]);
+        });
+        return out;
+    };
+    const majorsLiteral = (ms) => (ms.length === majors.length ? "true" : JSON.stringify(ms));
+    const presenceTable = (m, indent) => sorted(m.keys()).map((n) => `${indent}${JSON.stringify(n)}: ${majorsLiteral(m.get(n))},`);
+    const functionTable = [
+        `/** Every function, aggregate and procedure name in \`pg_proc\`, to the majors that have it (\`true\`: all of them). */`,
+        `export const FUNCTIONS: Readonly<Record<string, true | readonly number[]>> = {`,
+        ...presenceTable(presence(catalogs.map((c) => c.functions.map((f) => f.name))), "  "),
+        "};",
+    ];
+    const methodTable = [
+        `/** The index access methods, to the majors that have each (\`true\`: all of them). */`,
+        `export const INDEX_ACCESS_METHODS: Readonly<Record<string, true | readonly number[]>> = {`,
+        ...presenceTable(presence(catalogs.map((c) => c.accessMethods.filter((a) => a.type === "i").map((a) => a.name))), "  "),
+        "};",
+    ];
+    const opclassAms = sorted(catalogs.flatMap((c) => c.opclasses.map((o) => o.am)));
+    const opclassTable = [
+        `/** The operator classes of each index access method, to the majors that have each (\`true\`: all of them). */`,
+        `export const OPERATOR_CLASSES: Readonly<Record<string, Readonly<Record<string, true | readonly number[]>>>> = {`,
+        ...opclassAms.flatMap((am) => [
+            `  ${key(am)}: {`,
+            ...presenceTable(presence(catalogs.map((c) => c.opclasses.filter((o) => o.am === am).map((o) => o.name))), "    "),
+            "  },",
+        ]),
+        "};",
+    ];
+    const tables = [
+        ...header("The tables lint and the LSP read, typed by ./postgres-types."),
+        `import type { ColumnTypeSpec, SettingSpec, StorageParameterSpec } from "../postgres/catalog-types.js";`,
+        `import type { Settings, TypeSqlName } from "./postgres-types";`,
+        "",
+        `export * from "./postgres-types";`,
+        "",
+        ...settingTable,
+        "",
+        ...storageTable,
+        "",
+        ...typeTable,
+        "",
+        ...keywordTable,
+        "",
+        ...functionTable,
+        "",
+        ...methodTable,
+        "",
+        ...opclassTable,
+        "",
+    ].join("\n");
+    notes.push(`postgres: ${types.length} types, ${functions.length} functions, ${settings.length} settings, ${storage.length} storage parameters across ${catalogs.length} majors`);
+    return { declarations, tables, notes };
+}

package/dist/codegen/registry.js

@@ -0,0 +1,52 @@
+/**
+ * The entity registry, `lexicon-sql.json`: one entry per entity kind, which the
+ * LSP completes and hovers from and `dist/meta.json` packages.
+ *
+ * The entities are hand-written: their shape is the DDL a tag parses, not a
+ * schema document. Each is keyed by the kind's name and points at the entity
+ * type the tag gives it. ClickHouse's kinds came first and keep their bare
+ * names; Postgres's carry the dialect in the name, since both have a table
+ * and a view.
+ */
+import { CLICKHOUSE_ENTITY_TYPES } from "../clickhouse/entities.js";
+import { POSTGRES_ENTITY_TYPES } from "../postgres/entity-types.js";
+const KINDS = {
+    Database: CLICKHOUSE_ENTITY_TYPES.database,
+    Table: CLICKHOUSE_ENTITY_TYPES.table,
+    View: CLICKHOUSE_ENTITY_TYPES.view,
+    MaterializedView: CLICKHOUSE_ENTITY_TYPES.materializedView,
+    Dictionary: CLICKHOUSE_ENTITY_TYPES.dictionary,
+    Function: CLICKHOUSE_ENTITY_TYPES.function,
+    User: CLICKHOUSE_ENTITY_TYPES.user,
+    Role: CLICKHOUSE_ENTITY_TYPES.role,
+    RowPolicy: CLICKHOUSE_ENTITY_TYPES.rowPolicy,
+    Grant: CLICKHOUSE_ENTITY_TYPES.grant,
+    Quota: CLICKHOUSE_ENTITY_TYPES.quota,
+    SettingsProfile: CLICKHOUSE_ENTITY_TYPES.settingsProfile,
+    PostgresSchema: POSTGRES_ENTITY_TYPES.schema,
+    PostgresTable: POSTGRES_ENTITY_TYPES.table,
+    PostgresIndex: POSTGRES_ENTITY_TYPES.index,
+    PostgresView: POSTGRES_ENTITY_TYPES.view,
+    PostgresMaterializedView: POSTGRES_ENTITY_TYPES.materializedView,
+    PostgresSequence: POSTGRES_ENTITY_TYPES.sequence,
+    PostgresEnum: POSTGRES_ENTITY_TYPES.enum,
+    PostgresCompositeType: POSTGRES_ENTITY_TYPES.composite,
+    PostgresRangeType: POSTGRES_ENTITY_TYPES.range,
+    PostgresDomain: POSTGRES_ENTITY_TYPES.domain,
+    PostgresAggregate: POSTGRES_ENTITY_TYPES.aggregate,
+    PostgresCollation: POSTGRES_ENTITY_TYPES.collation,
+    PostgresCast: POSTGRES_ENTITY_TYPES.cast,
+    PostgresEventTrigger: POSTGRES_ENTITY_TYPES.eventTrigger,
+    PostgresExtension: POSTGRES_ENTITY_TYPES.extension,
+    PostgresFunction: POSTGRES_ENTITY_TYPES.function,
+    PostgresProcedure: POSTGRES_ENTITY_TYPES.procedure,
+    PostgresTrigger: POSTGRES_ENTITY_TYPES.trigger,
+    PostgresPolicy: POSTGRES_ENTITY_TYPES.policy,
+    PostgresRole: POSTGRES_ENTITY_TYPES.role,
+    PostgresGrant: POSTGRES_ENTITY_TYPES.grant,
+    PostgresDefaultPrivileges: POSTGRES_ENTITY_TYPES.defaultPrivileges,
+};
+export function buildRegistry() {
+    const registry = Object.fromEntries(Object.entries(KINDS).map(([name, resourceType]) => [name, { resourceType, kind: "resource", lexicon: "sql" }]));
+    return `${JSON.stringify(registry, null, 2)}\n`;
+}

package/dist/composites/audit-log-table.js

@@ -0,0 +1,35 @@
+/**
+ * `AuditLogTable`: an append-only audit log partitioned by month.
+ *
+ * The parent is `PARTITION BY RANGE (<timestamp>)`, and its primary key
+ * includes the timestamp, which Postgres requires of every unique key on a
+ * partitioned table. The composite declares a default partition so no insert
+ * is refused before a month's partition exists; a partition per month is
+ * created ahead of time by whatever the project uses for partition upkeep (a
+ * `FOR VALUES FROM ('2026-10-01') TO ('2026-11-01')` partition of the parent
+ * is one more `table` call). An index on `(<actor>, <timestamp>)` serves the
+ * question an audit log is asked most: what did this actor do, and when.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { index, table } from "../postgres/entities.js";
+/** An append-only audit log partitioned by month on its timestamp, with a default partition and an index by actor. */
+export const AuditLogTable = Composite((props) => {
+    const schema = props.schema ?? "public";
+    const ts = props.timestamp ?? "occurred_at";
+    const actor = props.actor ?? "actor";
+    const log = table `
+    CREATE TABLE ${schema}.${props.name} (
+      id bigint GENERATED ALWAYS AS IDENTITY,
+      ${ts} timestamptz NOT NULL DEFAULT now(),
+      ${actor} text NOT NULL,
+      action text NOT NULL,
+      subject text,
+      details jsonb NOT NULL DEFAULT '{}',
+      PRIMARY KEY (id, ${ts})
+    ) PARTITION BY RANGE (${ts})`;
+    const fallback = table `
+    CREATE TABLE ${schema}.${`${props.name}_default`} PARTITION OF ${log} DEFAULT`;
+    const byActor = index `
+    CREATE INDEX ${`${props.name}_actor_idx`} ON ${log} (${actor}, ${ts} DESC)`;
+    return { table: log, defaultPartition: fallback, actorIndex: byActor };
+}, "AuditLogTable");