@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.0

package/src/codegen/docs.ts

@@ -0,0 +1,225 @@
+/**
+ * Documentation generation for the sql lexicon: the generated reference pages
+ * from the core docs pipeline, plus the authored pages in docs/pages/.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { writeFileSync } from "fs";
+import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+import { renderClassifierPage } from "./classifier-page";
+import { renderPostgresClassifierPage } from "./postgres-classifier-page";
+
+const overview = `The sql lexicon declares database schema in TypeScript. It has two dialects,
+each a subpath of the one package: ClickHouse at
+\`@intentius/chant-lexicon-sql/clickhouse\` and Postgres at
+\`@intentius/chant-lexicon-sql/postgres\`. A declaration is the database's own
+\`CREATE\` statement in a tagged template, and an interpolated object or
+column stays a reference. Install it with
+\`npm install --save-dev @intentius/chant @intentius/chant-lexicon-sql\`; each
+dialect's Getting Started page runs the example the lexicon ships.
+
+\`\`\`ts
+import { database, table, view } from "@intentius/chant-lexicon-sql/clickhouse";
+
+export const analytics = database\`CREATE DATABASE analytics ENGINE = Atomic\`;
+
+export const events = table\`
+  CREATE TABLE \${analytics}.events (
+    user_id  UUID,
+    kind     LowCardinality(String),
+    ts       DateTime
+  )
+  ENGINE = MergeTree
+  ORDER BY (user_id, kind, ts)\`;
+\`\`\`
+
+\`\`\`ts
+import { schema, table, index } from "@intentius/chant-lexicon-sql/postgres";
+
+export const app = schema\`CREATE SCHEMA app\`;
+
+export const users = table\`
+  CREATE TABLE \${app}.users (
+    id    bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    email text NOT NULL UNIQUE
+  )\`;
+
+export const usersEmail = index\`
+  CREATE INDEX CONCURRENTLY users_email_lower_idx ON \${users} (lower(\${users.columns.email}))\`;
+\`\`\`
+
+## Spec-true per dialect
+
+Each dialect is true to its own database. For SQL the spec is the database's
+own DDL, so a ClickHouse declaration is a ClickHouse \`CREATE\` statement and a
+Postgres declaration a Postgres one. The names a declaration can use (engines,
+codecs and settings for ClickHouse; types, access methods, storage parameters
+and extensions for Postgres) are generated from a pinned server's own catalog:
+ClickHouse's \`system.*\` tables, and Postgres's \`pg_catalog\` at one pinned
+release of each supported major. There is no neutral schema model that the
+dialects are translated from.
+
+The reason is that the databases differ exactly where a schema tool does its
+work. ClickHouse has no foreign keys and no transactional DDL, and it cannot
+change a table's sort key, partition key or engine in place: the rows have to
+be copied into a new table. Postgres makes most changes in place and inside a
+transaction, and what a change costs there is the lock it takes: adding a
+column with a constant default is a catalog change, a type change that
+rewrites the table blocks every reader until it finishes, and an index built
+without \`CONCURRENTLY\` blocks every writer. A neutral model would have to hide
+those differences, so a plan could not say what a change will cost, or carry
+every dialect's features and check each one against the target anyway.
+
+So each dialect has its own types, parser, lint rules and post-synth checks,
+change classifier, applier, migration Op, composites and skills. What the two
+share is the way of working:
+
+| | ClickHouse | Postgres |
+|---|---|---|
+| Declaring | \`database\`, \`table\`, \`view\` | \`schema\`, \`table\`, \`index\`, \`view\`, \`sequence\`, \`type\`, \`domain\`, \`extension\` |
+| Types from | one pinned \`clickhouse-server\` release | one pinned \`postgres\` release per major, 14 to 18 |
+| Rule ids | SQLCH001-003, SQLCH101-120, SQLCH200-250 | SQLPG001-004, SQLPG101-118, SQLPG200-270 |
+| Change classes | metadata only, background rewrite, rebuild | metadata only, validates under a weaker lock, needs \`CONCURRENTLY\`, \`ACCESS EXCLUSIVE\` rewrite or scan, expand and contract |
+| Applier (\`ApplyOp\` target) | \`clickhouseApply\` (\`clickhouse\`) | \`postgresApply\` (\`postgres\`) |
+| What a plan refuses runs as | \`ClickHouseRebuildOp\` | \`PostgresMigrationOp\` |
+| Ownership marker | a trailer on the object's comment | a trailer on the object's comment |
+
+References, dependency order and column lineage work the same way in both, as
+do \`chant sql diff\` and \`chant sql plan\` (they read the build's
+\`dialect\`), import with \`chant import --from <env>\`, the \`-- previously:\`
+rename hint, and the comment trailer that marks what chant owns.
+
+One build holds one dialect. A project that declares both ClickHouse and
+Postgres objects fails the build naming one of each; a Postgres database and
+a ClickHouse database are two projects, which a workspace can hold as two
+members. \`sql.dialect\` in \`chant.config.ts\` says which dialect a project is
+when nothing declared says so, as for an import into an empty project.
+
+## Pages
+
+ClickHouse:
+
+- [Getting Started with ClickHouse](./getting-started/): declare a schema,
+  build it, apply it to a local server and plan a change against it.
+- [Declaring ClickHouse Tables and Views](./clickhouse-ddl/): databases,
+  tables, views and materialized views, and what each kind of interpolation
+  means.
+- [Importing a ClickHouse Server](./importing/): \`chant import --from <env>\`
+  from \`SHOW CREATE\`.
+- [Planning and the Change Classifier](./change-classifier/): every change
+  classified as metadata only, a background rewrite or a rebuild.
+- [Applying to a ClickHouse Server](./applying/): \`clickhouseApply\`, the
+  ownership marker, prune and the local server.
+- [Rebuilding a Table](./rebuild/): \`ClickHouseRebuildOp\` for the changes
+  ClickHouse cannot make in place.
+- [Where the ClickHouse Types Come From](./clickhouse-catalog/): the pinned
+  server and how to move the pin.
+
+Postgres:
+
+- [Getting Started with Postgres](./postgres-getting-started/): declare a
+  schema, apply it to a local server, add a column and an index, and see a
+  rename refused.
+- [Declaring Postgres Objects](./postgres-ddl/): the eight tags,
+  constraints, \`nextval(\${seq})\`, \`COMMENT ON\` and \`literal()\`.
+- [Importing a Postgres Server](./postgres-importing/): canonical text from
+  the catalog's printers, and the objects that belong to someone else.
+- [Postgres Locks and the Change Classifier](./postgres-change-classifier/):
+  every change classified by the lock it takes.
+- [Applying to a Postgres Server](./postgres-applying/): transactions,
+  \`CONCURRENTLY\`, timeouts, ownership, prune and the local server.
+- [Migrating a Column](./postgres-migration/): \`PostgresMigrationOp\`, the
+  expand-and-contract Op for a column rename or type change.
+- [Managed Providers](./postgres-providers/): \`sql.provider\`, SQLPG004, and
+  what each provider's data has not verified.
+- [The Postgres Pin and Supported Majors](./postgres-majors/): one pin per
+  major, \`sql.postgresMajor\`, and moving a pin.
+
+Both dialects:
+
+- [References and Lineage](./references-and-lineage/): how references become
+  dependency order and column-level lineage.
+- [Composites](./composites/): five ClickHouse and five Postgres composites.
+- [Lint Rules and Checks](./lint-rules/): every lint rule and post-synth
+  check.
+
+## Schema changes and \`chant migrate\`
+
+\`chant migrate\` translates a file from one lexicon's format into another's,
+such as a GitHub Actions workflow into GitLab CI. It does not run schema
+migrations, and the sql lexicon registers nothing for it. A schema change is a
+change to the declarations: \`chant sql diff\` or \`chant sql plan\` classifies
+it, the dialect's applier makes the changes it can make in place, and a change
+it cannot make runs as a gated migration Op: \`ClickHouseRebuildOp\` (see
+[Rebuilding a Table](./rebuild/)) or \`PostgresMigrationOp\` (see
+[Migrating a Column](./postgres-migration/)).
+`;
+
+const outputFormat = `A build writes two files, beside each other. Which pair depends on the
+dialect the project declares.
+
+- The primary output (the \`-o\` file, \`dist/schema.json\` by convention), one
+  JSON document. \`dialect\` is \`clickhouse\` or \`postgres\`. \`applyOrder\`
+  lists the export names in the order the objects have to be created.
+  \`objects\` holds one entry per declared object, in that order: its export
+  name (\`export\`), its type, its SQL name (\`sqlName\`), its parsed
+  definition, \`dependsOn\`, and its \`ddl\`. References are written as export
+  names and lineage as \`export.column\`.
+  - ClickHouse: the types are \`ClickHouse::Database\`, \`::Table\`, \`::View\`
+    and \`::MaterializedView\`, and the definition holds columns, engine, keys,
+    TTL, settings, indexes, projections and constraints, and for a view its
+    \`select\`, \`reads\`, \`to\` and \`lineage\`.
+  - Postgres: the document also carries \`postgresMajor\`, the major the
+    project targets (\`sql.postgresMajor\`, else 18, the newest pinned). The
+    types are \`Postgres::Schema\`, \`::Table\`, \`::Index\`, \`::View\`,
+    \`::MaterializedView\`, \`::Sequence\`, \`::Enum\`, \`::Domain\` and
+    \`::Extension\`. A table's definition holds its columns, primary key,
+    uniques, checks, foreign keys, exclusions and the rest of its clauses; a
+    view's its \`query\`, \`reads\` and \`lineage\`; an index's its table,
+    method and elements. \`dependsOn\` names the objects and the columns the
+    statement references.
+- \`clickhouse.sql\` or \`postgres.sql\`: every statement in \`applyOrder\`, each
+  ending in \`;\`, written byte for byte as declared, with a Postgres
+  template's \`COMMENT ON\` statements after its \`CREATE\`.
+
+The order follows the references: a table after its database or schema and the
+types and sequences it uses, a view after the tables it reads, an index after
+its table, a materialized view after its \`TO\` target. Ties go by export name,
+so the output does not depend on the order files were found in. A reference
+cycle fails the build and names the cycle.
+
+\`chant sql diff\`, \`chant sql plan\`, the post-synth checks and the appliers
+read the JSON document. Neither file carries chant's ownership marker: the
+applier adds it to each object's comment when it creates the object (see
+[Applying to a ClickHouse Server](../applying/) and
+[Applying to a Postgres Server](../postgres-applying/)).
+`;
+
+export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+  writeFileSync(join(pkgDir, "docs", "pages", "change-classifier.mdx"), renderClassifierPage());
+  writeFileSync(join(pkgDir, "docs", "pages", "postgres-change-classifier.mdx"), renderPostgresClassifierPage());
+
+  const config: DocsConfig = {
+    name: "sql",
+    displayName: "SQL",
+    description: "Database schema as typed declarations in each database's own DDL: ClickHouse and Postgres",
+    distDir: join(pkgDir, "dist"),
+    outDir: join(pkgDir, "docs"),
+    basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/sql/",
+    overview,
+    outputFormat,
+    serviceFromType: (type) => type.split("::")[0] ?? "SQL",
+    srcDir: join(pkgDir, "src"),
+    examplesDir: join(pkgDir, "examples"),
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (opts?.verbose) {
+    console.error(`Generated ${result.pages.size} documentation pages`);
+  }
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+import { generate, generatePostgres, writeGeneratedFiles } from "./generate";
+
+// `npm run generate -- --force` reads the pinned servers even when the snapshots match the pins;
+// `--major=18` limits the Postgres read to one major.
+const force = process.argv.includes("--force");
+const majors = process.argv
+  .filter((a) => a.startsWith("--major="))
+  .map((a) => Number.parseInt(a.slice("--major=".length), 10));
+const result = await generate({ verbose: true, force });
+const postgres = await generatePostgres({ force, ...(majors.length > 0 ? { majors } : {}) });
+for (const note of postgres.notes) console.error(`[sql] ${note}`);
+writeGeneratedFiles(result, undefined, postgres);

package/src/codegen/generate.ts

@@ -0,0 +1,126 @@
+/**
+ * The sql lexicon's generation pipeline.
+ *
+ * Two dialects. ClickHouse's "schema" is the catalog a pinned
+ * `clickhouse-server` reports from `system.*`, committed as
+ * `src/spec/clickhouse-catalog.snapshot.json` (chant #3195). `fetchSchemas`
+ * reads that snapshot, and starts the pinned server only on a pin move; see
+ * `src/spec/fetch.ts`.
+ *
+ * Outputs, under `src/generated/`:
+ *
+ * - `clickhouse-types.ts` (and `index.d.ts`, the packaged copy): unions of every
+ *   engine, type family, codec, skip index type, format and function name, and
+ *   the `MergeTreeSettings` / `QuerySettings` interfaces.
+ * - `clickhouse.ts`: the tables lint and the LSP read, with the hand-written
+ *   overlays (engine argument kinds, codec parameters) merged in.
+ * - `lexicon-sql.json`: the entity registry.
+ */
+
+import {
+  generatePipeline,
+  writeGeneratedArtifacts,
+  type GenerateOptions,
+  type GenerateResult,
+  type ParsedResult,
+} from "@intentius/chant/codegen/generate";
+import { NamingStrategy } from "@intentius/chant/codegen/naming";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { CATALOG_KEY, fetchSchemas } from "../spec/fetch";
+import { parseCatalog, type ClickHouseCatalog } from "../spec/catalog";
+import { renderClickHouseModule } from "./clickhouse-module";
+import { buildRegistry } from "./registry";
+import { fetchCatalogs, type FetchCatalogsOptions } from "../spec/postgres-fetch";
+import { renderPostgresModule, type RenderedPostgresModule } from "./postgres-module";
+
+export type { GenerateResult };
+
+export interface ClickHouseParsed extends ParsedResult {
+  typeName: string;
+  catalog: ClickHouseCatalog;
+}
+
+export async function generate(opts: GenerateOptions = {}): Promise<GenerateResult> {
+  let notes: string[] = [];
+  let tables = "";
+
+  const result = await generatePipeline<ClickHouseParsed>(
+    {
+      fetchSchemas: (fetchOpts) => fetchSchemas({ force: fetchOpts.force }),
+
+      parseSchema: (typeName, data) => {
+        if (typeName !== CATALOG_KEY) return null;
+        const catalog = parseCatalog(data.toString("utf-8"));
+        return {
+          typeName,
+          catalog,
+          propertyTypes: [{ name: "MergeTreeSettings" }, { name: "QuerySettings" }],
+          enums: [],
+        };
+      },
+
+      createNaming: (results) =>
+        new NamingStrategy(
+          results.map((r) => ({ typeName: r.typeName, propertyTypes: r.propertyTypes })),
+          {
+            priorityNames: {},
+            priorityAliases: {},
+            priorityPropertyAliases: {},
+            serviceAbbreviations: {},
+            shortName: (t) => t.split("::").pop()!,
+            serviceName: (t) => t.split("::")[0] ?? t,
+          },
+        ),
+
+      generateRegistry: () => buildRegistry(),
+
+      generateTypes: (results) => {
+        const catalog = results.find((r) => r.typeName === CATALOG_KEY)?.catalog;
+        if (!catalog) throw new Error("no ClickHouse catalog was parsed");
+        const rendered = renderClickHouseModule(catalog);
+        notes = rendered.notes;
+        tables = rendered.tables;
+        return rendered.declarations;
+      },
+
+      generateRuntimeIndex: () => tables,
+    },
+    opts,
+  );
+
+  if (result.warnings.length > 0) {
+    throw new Error(`sql generation failed:\n  ${result.warnings.map((w) => `${w.file}: ${w.error}`).join("\n  ")}`);
+  }
+  if (opts.verbose) for (const note of notes) console.error(`[sql] ${note}`);
+  return result;
+}
+
+export type PostgresGenerateOptions = Pick<FetchCatalogsOptions, "force" | "majors" | "log">;
+
+/**
+ * Generate the Postgres types: the union of the catalogs of every supported
+ * major (`src/spec/postgres-catalog-<major>.snapshot.json`), rendered with the
+ * overlays. A server is started only for a major whose pin moved, or with
+ * `force`; see `src/spec/postgres-fetch.ts`. The types stay internal to the
+ * package until the `/postgres` subpath has entities to export with them.
+ */
+export async function generatePostgres(opts: PostgresGenerateOptions = {}): Promise<RenderedPostgresModule> {
+  const catalogs = await fetchCatalogs(opts);
+  return renderPostgresModule(catalogs);
+}
+
+/** Write the generated files under `src/generated/`. */
+export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string, postgres?: RenderedPostgresModule): void {
+  const baseDir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  writeGeneratedArtifacts({
+    baseDir,
+    files: {
+      "lexicon-sql.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "clickhouse-types.ts": result.typesDTS,
+      "clickhouse.ts": result.indexTS,
+      ...(postgres ? { "postgres-types.ts": postgres.declarations, "postgres.ts": postgres.tables } : {}),
+    },
+  });
+}

package/src/codegen/package.ts

@@ -0,0 +1,36 @@
+/**
+ * sql lexicon packaging, delegating to core's packagePipeline.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { packagePipeline, type PackageOptions, type PackageResult } from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+
+export type { PackageOptions, PackageResult };
+
+// src/codegen/package.ts -> src/
+const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  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/src/codegen/postgres-classifier-page.ts

@@ -0,0 +1,81 @@
+/**
+ * `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";
+
+const cell = (s: string) => s.replace(/\|/g, "\\|");
+
+export function renderPostgresClassifierPage(): string {
+  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.
+
+## 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.
+
+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/src/codegen/postgres-module.test.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+import { renderPostgresModule } from "./postgres-module";
+import { parseCatalog, type PostgresCatalog } from "../spec/postgres-catalog";
+import { snapshotFile } from "../spec/postgres-fetch";
+import { POSTGRES_MAJORS } from "../spec/postgres-pin";
+import { availableAt } from "../postgres/catalog-types";
+
+const load = (): PostgresCatalog[] => POSTGRES_MAJORS.map((m) => parseCatalog(readFileSync(snapshotFile(m), "utf-8")));
+const rendered = renderPostgresModule(load());
+
+describe("the Postgres union", () => {
+  test("is byte-identical across runs", () => {
+    const again = renderPostgresModule(load());
+    expect(again.declarations).toBe(rendered.declarations);
+    expect(again.tables).toBe(rendered.tables);
+  });
+
+  test("lists the majors and the exact release each was read from", () => {
+    expect(rendered.declarations).toContain("export const POSTGRES_MAJORS = [14,15,16,17,18] as const;");
+    expect(rendered.declarations).toContain('"18":"18.6"');
+  });
+
+  test("marks what arrived in a later major with since", () => {
+    expect(rendered.declarations).toContain('"io_method": { since: 18 }');
+    expect(rendered.declarations).toContain('"regexp_count": { since: 15 }');
+    expect(rendered.declarations).toMatch(/\/\*\*[^\n]*@since 18 \*\/\n {2}io_method\?: /);
+  });
+
+  test("marks what a later major dropped with until, the last major that has it", () => {
+    expect(rendered.declarations).toContain('"close_lb": { until: 14 }');
+    expect(rendered.declarations).toContain('"old_snapshot_threshold": { until: 16 }');
+    expect(rendered.declarations).toMatch(/\/\*\*[^\n]*@until 16 \*\/\n {2}old_snapshot_threshold\?: /);
+  });
+
+  test("keeps an entry in every major free of a range", () => {
+    const ranges = rendered.declarations.slice(rendered.declarations.indexOf("export const VERSION_RANGES"));
+    expect(ranges).not.toContain('"btree"');
+    expect(ranges).not.toContain('"index:btree.fillfactor"');
+    expect(ranges).toContain('"view.security_invoker": { since: 15 }');
+  });
+
+  test("marks the enum members a setting gained", () => {
+    expect(rendered.declarations).toMatch(/"wal_compression": \{\n\s+"lz4": \{ since: 15 \}/);
+  });
+
+  test("types storage parameters from the overlay, with the major they arrived in", () => {
+    expect(rendered.declarations).toMatch(/export interface StorageParams_table \{[^}]*fillfactor\?: number;/);
+    expect(rendered.declarations).toMatch(/@since 15 \*\/\n {2}security_invoker\?: boolean;/);
+  });
+
+  test("merges the overlay into the column type table", () => {
+    expect(rendered.tables).toMatch(/"character varying": \{[^\n]*"parameters":\[\{"name":"length"/);
+    expect(rendered.tables).toContain('"aliases":["int","int4"]');
+  });
+
+  test("availableAt reads a range", () => {
+    expect(availableAt({ since: 15 }, 14)).toBe(false);
+    expect(availableAt({ since: 15, until: 16 }, 16)).toBe(true);
+    expect(availableAt({ until: 14 }, 15)).toBe(false);
+    expect(availableAt(undefined, 14)).toBe(true);
+  });
+});
+
+describe("the overlays are checked against the catalogs", () => {
+  test("a storage parameter the probe found with no overlay entry fails generation", () => {
+    const catalogs = load();
+    catalogs[4]!.storageParameters.table = [...catalogs[4]!.storageParameters.table!, "brand_new_parameter"];
+    expect(() => renderPostgresModule(catalogs)).toThrow(/storage parameter brand_new_parameter has no entry/);
+  });
+
+  test("a name in two majors but not the one between them cannot be a range", () => {
+    const catalogs = load();
+    catalogs[1]!.extensions = catalogs[1]!.extensions.filter((e) => e.name !== "pgcrypto");
+    expect(() => renderPostgresModule(catalogs)).toThrow(/extension pgcrypto is present in non-adjacent majors/);
+  });
+});