@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/spec/fetch.js

@@ -0,0 +1,90 @@
+/**
+ * Where generation gets the ClickHouse catalog.
+ *
+ * The committed snapshot, `clickhouse-catalog.snapshot.json`, is the source
+ * every ordinary run reads: a fresh clone, CI and `npm run prepack` generate
+ * from it with no Docker and no network. A server is read only when the
+ * snapshot cannot serve the pin:
+ *
+ * - the pin moved (`CLICKHOUSE_VERSION` differs from the snapshot's version),
+ * - `force` is set, or
+ * - `CHANT_SQL_CLICKHOUSE_URL` names a server to read instead of starting one.
+ *
+ * Reading a server means starting the pinned image in a throwaway container
+ * (or using the named one), checking that its `version()` is the pin, reading
+ * `system.*`, and rewriting the snapshot. A server at any other version is
+ * refused: a snapshot labelled with one pin and holding another's surface is
+ * the failure the pin exists to prevent.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { CLICKHOUSE_VERSION, clickhouseImage } from "./pin.js";
+import { parseCatalog, readCatalog, stringifyCatalog } from "./catalog.js";
+import { startScratchServer } from "../clickhouse/container.js";
+export const SNAPSHOT_FILE = join(moduleSourceDir(import.meta.url), "clickhouse-catalog.snapshot.json");
+/** The key the single catalog document is filed under in the pipeline's schema map. */
+export const CATALOG_KEY = "ClickHouse::Catalog";
+function readSnapshot(file) {
+    try {
+        return parseCatalog(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the pinned catalog from a server and refuse any other version. */
+export async function catalogFromServer(endpoint, image) {
+    const catalog = await readCatalog(endpoint, image);
+    if (catalog.version !== CLICKHOUSE_VERSION) {
+        throw new Error(`the server at ${endpoint.url} is ClickHouse ${catalog.version}, not the pinned ${CLICKHOUSE_VERSION}. ` +
+            "Point CHANT_SQL_CLICKHOUSE_URL at a server running the pin, or update CLICKHOUSE_IMAGE_DIGEST in src/spec/pin.ts " +
+            "together with CLICKHOUSE_VERSION.");
+    }
+    return catalog;
+}
+/**
+ * The catalog for the current pin: the snapshot when it matches, otherwise a
+ * fresh read that also rewrites the snapshot.
+ */
+export async function fetchCatalog(options = {}) {
+    const file = options.snapshotFile ?? SNAPSHOT_FILE;
+    const log = options.log ?? ((line) => console.error(line));
+    const serverUrl = options.serverUrl ?? process.env.CHANT_SQL_CLICKHOUSE_URL;
+    const snapshot = readSnapshot(file);
+    if (snapshot && snapshot.version === CLICKHOUSE_VERSION && !options.force && !serverUrl) {
+        log(`[sql] clickhouse catalog: committed snapshot at ${snapshot.version}`);
+        return snapshot;
+    }
+    const reason = !snapshot
+        ? "no readable snapshot"
+        : snapshot.version !== CLICKHOUSE_VERSION
+            ? `the pin moved from ${snapshot.version} to ${CLICKHOUSE_VERSION}`
+            : serverUrl
+                ? "CHANT_SQL_CLICKHOUSE_URL is set"
+                : "force";
+    let catalog;
+    if (serverUrl) {
+        log(`[sql] clickhouse catalog: reading ${serverUrl} (${reason})`);
+        catalog = await catalogFromServer({ url: serverUrl }, clickhouseImage());
+    }
+    else {
+        const image = clickhouseImage();
+        log(`[sql] clickhouse catalog: starting ${image} (${reason})`);
+        const server = await startScratchServer(image, { namePrefix: "chant-sql-catalog" });
+        try {
+            catalog = await catalogFromServer(server.endpoint, image);
+        }
+        finally {
+            await server.stop();
+        }
+    }
+    writeFileSync(file, stringifyCatalog(catalog));
+    log(`[sql] clickhouse catalog: wrote ${file}`);
+    return catalog;
+}
+/** The pipeline's `fetchSchemas`: one document, the catalog, keyed {@link CATALOG_KEY}. */
+export async function fetchSchemas(options = {}) {
+    const catalog = await fetchCatalog(options);
+    return new Map([[CATALOG_KEY, Buffer.from(stringifyCatalog(catalog), "utf-8")]]);
+}

package/dist/spec/pin.js

@@ -0,0 +1,42 @@
+/**
+ * The pinned ClickHouse server the ClickHouse dialect's types come from.
+ *
+ * ClickHouse publishes no schema for its DDL. The engine names, column type
+ * families, codecs, skip index types and both settings surfaces are read from a
+ * running server's `system.*` tables (chant #3195), so the pin is a server
+ * image, not a document.
+ *
+ * Pinned to an exact patch of the 26.8 LTS line. 26.3 LTS lacks the `syntax`
+ * column on `system.table_engines` and the `system.data_skipping_index_types`
+ * table the engine-argument and skip-index types are built from, and two
+ * patches of one line differ (26.8.5.13 and 26.8.15.10 differ by nine query
+ * settings), so a floating `26.8` tag would change generated output with no
+ * commit. The digest sits beside the tag so a re-pushed tag cannot change it
+ * unseen either: generation runs `image@digest` and refuses a server whose
+ * `version()` is not {@link CLICKHOUSE_VERSION}.
+ *
+ * Moving the pin: change both constants, then `chant dev generate` (or
+ * `npm run generate`). The committed snapshot no longer matches the pin, so
+ * generation starts the pinned server, rewrites
+ * `src/spec/clickhouse-catalog.snapshot.json`, and the pull request's diff of
+ * that file is the surface change. Read its `-` lines: a removed engine or
+ * function is what breaks a user's declarations.
+ */
+/** The pinned `clickhouse-server` release, as `SELECT version()` reports it. */
+export const CLICKHOUSE_VERSION = "26.8.15.10";
+/** The image digest of `clickhouse/clickhouse-server:<CLICKHOUSE_VERSION>`. Move it with the version. */
+export const CLICKHOUSE_IMAGE_DIGEST = "sha256:9716a352d25f538bd19d868b001141e7a60e4d035bc9b823658c6a071660aa61";
+/** The official server image. */
+export const CLICKHOUSE_IMAGE_REPOSITORY = "clickhouse/clickhouse-server";
+/** The full image reference generation runs: tag for the reader, digest for the runtime. */
+export function clickhouseImage() {
+    return `${CLICKHOUSE_IMAGE_REPOSITORY}:${CLICKHOUSE_VERSION}@${CLICKHOUSE_IMAGE_DIGEST}`;
+}
+/**
+ * ClickHouse tags its LTS releases `v<version>-lts` on GitHub. The upgrade
+ * tooling hands `replace` the raw tag; the constant holds the bare version,
+ * which is also the docker tag.
+ */
+export function versionFromReleaseTag(tag) {
+    return tag.replace(/^v/, "").replace(/-lts$/, "");
+}

package/dist/spec/postgres-catalog.js

@@ -0,0 +1,171 @@
+/**
+ * The Postgres catalog: what generation reads from one pinned server's
+ * catalog, in the shape the committed snapshot stores (one snapshot per major).
+ *
+ * Every section is sorted with an explicit `COLLATE "C"`, and the snapshot is
+ * written one entry per line, so a pin move is a line diff a reviewer can
+ * read. Nothing here depends on the host: `pg_settings.setting` and
+ * `reset_val` reflect the scratch server's configuration and are never read
+ * (`boot_val` is the compiled default), the Debian build suffix is stripped
+ * from `server_version`, and nothing is timestamped.
+ */
+import { STORAGE_PARAMETER_SEED } from "../postgres/overlays/storage.js";
+/** The list sections, in the order the snapshot writes them; `storageParameters` follows. */
+export const CATALOG_SECTIONS = [
+    "types",
+    "accessMethods",
+    "opclasses",
+    "functions",
+    "operators",
+    "settings",
+    "keywords",
+    "extensions",
+];
+/** The major of a version string: `18.6` is 18. */
+export function majorOf(version) {
+    return Number.parseInt(version, 10);
+}
+// ── Reading a server ─────────────────────────────────────────────────
+const C = `collate "C"`;
+const agg = (select, order) => `select coalesce(json_agg(t order by ${order}), '[]'::json) from (${select}) t;`;
+const AGG_SUPPORT_OIDS = `select unnest(array[aggtransfn::oid, aggfinalfn::oid, aggcombinefn::oid, aggserialfn::oid, aggdeserialfn::oid, aggmtransfn::oid, aggminvtransfn::oid, aggmfinalfn::oid]) as oid from pg_aggregate`;
+const QUERIES = {
+    version: `select to_json(split_part(current_setting('server_version'), ' ', 1));`,
+    versionNum: `select to_json(current_setting('server_version_num')::int);`,
+    // Non-array, non-composite types in pg_catalog. format_type() is the SQL
+    // spelling, so int4 is integer and bool is boolean.
+    types: agg(`select t.typname::text as name, format_type(t.oid, null) as "sqlName", t.typtype::text as kind,
+            t.typcategory::text as category, t.typlen::int as len, t.typbyval as byval
+       from pg_type t join pg_namespace n on n.oid = t.typnamespace
+      where n.nspname = 'pg_catalog' and t.typtype in ('b','d','e','m','p','r')
+        and not (t.typcategory = 'A' and t.typname like '\\_%')`, `t.name ${C}`),
+    accessMethods: agg(`select a.amname::text as name, a.amtype::text as type,
+       case when a.amtype = 'i' then (select json_agg(p order by p ${C}) from unnest(array['asc','desc','nulls_first','nulls_last','orderable','distance_orderable','returnable','search_array','search_nulls','clusterable','index_scan','bitmap_scan','backward_scan','can_order','can_unique','can_multi_col','can_exclude','can_include']) p where pg_indexam_has_property(a.oid, p)) end as properties
+       from pg_am a`, `t.name ${C}`),
+    opclasses: agg(`select am.amname::text as am, c.opcname::text as name, format_type(c.opcintype, null) as "inputType",
+            c.opcdefault as "default", f.opfname::text as family
+       from pg_opclass c join pg_am am on am.oid = c.opcmethod join pg_opfamily f on f.oid = c.opcfamily
+       join pg_namespace n on n.oid = c.opcnamespace where n.nspname = 'pg_catalog'`, `t.am ${C}, t.name ${C}, t."inputType" ${C}`),
+    // One row per name in pg_catalog. Type I/O functions are not callable in any useful way.
+    functions: agg(`select p.proname::text as name, string_agg(distinct p.prokind::text, '' order by p.prokind::text) as kinds, count(*)::int as overloads,
+            (p.proname like 'pg\\_%' or p.proname like 'binary\\_upgrade%' or p.proname like '%support'
+             or coalesce(bool_and(p.oid in (${AGG_SUPPORT_OIDS})), false)) as internal
+       from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+      where n.nspname = 'pg_catalog'
+        and p.oid not in (select unnest(array[typinput::oid, typoutput::oid, typreceive::oid, typsend::oid, typmodin::oid, typmodout::oid, typanalyze::oid, typsubscript::oid]) from pg_type)
+      group by p.proname`, `t.name ${C}`),
+    operators: agg(`select o.oprname::text as name, string_agg(distinct o.oprkind::text, '' order by o.oprkind::text) as kinds, count(*)::int as overloads
+       from pg_operator o join pg_namespace n on n.oid = o.oprnamespace where n.nspname = 'pg_catalog' group by o.oprname`, `t.name ${C}`),
+    settings: agg(`select name::text, vartype::text as type, context::text, category::text, unit::text, boot_val as "default", min_val as min, max_val as max, enumvals::text[] as enumvals
+       from pg_settings where name not like 'server\\_version%'`, `t.name ${C}`),
+    keywords: agg(`select word::text, catcode::text as code, catdesc::text as description from pg_get_keywords()`, `t.word ${C}, t.code ${C}`),
+    extensions: agg(`select name::text, default_version::text as "defaultVersion", comment::text as description from pg_available_extensions`, `t.name ${C}`),
+};
+/**
+ * Storage parameters (reloptions) are compiled into `reloptions.c`; no catalog
+ * lists them. Try every candidate on every relation kind and keep the names
+ * the server does not reject as unrecognized. Candidates are every
+ * `pg_settings` name plus the overlay's seed. An out-of-range value error
+ * counts as accepted.
+ */
+function storageProbe() {
+    const index = { btree: "a", hash: "a", brin: "a", gin: "arr", gist: "r", spgist: "r" };
+    const targets = [
+        ["table", "create table probe.x (a int) with (%C=1)"],
+        ["toast", "create table probe.x (a text) with (toast.%C=1)"],
+        ["view", "create view probe.x with (%C=1) as select 1 as a"],
+        ["materialized view", "create materialized view probe.x with (%C=1) as select 1 as a"],
+        ...Object.entries(index).map(([am, col]) => [`index:${am}`, `create index x on probe.base using ${am} (${col}) with (%C=1)`]),
+    ];
+    const cases = targets.map(([t, s]) => `('${t}', $q$${s}$q$)`).join(",\n");
+    return `
+drop schema if exists probe cascade; create schema probe;
+create table probe.base (a int, arr int[], r int4range);
+create temp table res (target text, cand text);
+do $do$
+declare t record; c record; msg text;
+begin
+  for t in select * from (values ${cases}) v(target, stmt) loop
+    for c in select distinct n as cand from (select name::text as n from pg_settings union select unnest(string_to_array($seed$${STORAGE_PARAMETER_SEED.join(",")}$seed$, ','))) s(n) loop
+      begin
+        execute replace(t.stmt, '%C', quote_ident(c.cand));
+        insert into res values (t.target, c.cand);
+        execute case when t.target like 'index%' then 'drop index probe.x'
+                     when t.target like 'mat%' then 'drop materialized view probe.x'
+                     when t.target = 'view' then 'drop view probe.x' else 'drop table probe.x' end;
+      exception when others then
+        get stacked diagnostics msg = message_text;
+        if msg not like 'unrecognized parameter%' and msg not like 'syntax error%' then
+          insert into res values (t.target, c.cand);
+        end if;
+      end;
+    end loop;
+  end loop;
+end $do$;
+drop schema probe cascade;
+${agg(`select target, cand as name from res`, `t.target ${C}, t.name ${C}`)}`;
+}
+/** Read the catalog from a server. The caller checks that its version is the pin. */
+export async function readCatalog(reader, image) {
+    var _a, _b;
+    const q = async (key) => (await reader.query(QUERIES[key]));
+    const catalog = {
+        dialect: "postgres",
+        version: await q("version"),
+        versionNum: await q("versionNum"),
+        image,
+        types: await q("types"),
+        accessMethods: await q("accessMethods"),
+        opclasses: await q("opclasses"),
+        functions: await q("functions"),
+        operators: await q("operators"),
+        settings: await q("settings"),
+        keywords: await q("keywords"),
+        extensions: await q("extensions"),
+        storageParameters: {},
+    };
+    const probed = (await reader.query(storageProbe()));
+    for (const r of probed)
+        ((_a = catalog.storageParameters)[_b = r.target] ?? (_a[_b] = [])).push(r.name);
+    return catalog;
+}
+// ── The snapshot's text form ─────────────────────────────────────────
+/** Write the catalog with one array entry per line, so a pin move is one changed line per changed entry. */
+export function stringifyCatalog(catalog) {
+    const lines = ["{"];
+    lines.push(`  "dialect": ${JSON.stringify(catalog.dialect)},`);
+    lines.push(`  "version": ${JSON.stringify(catalog.version)},`);
+    lines.push(`  "versionNum": ${catalog.versionNum},`);
+    lines.push(`  "image": ${JSON.stringify(catalog.image)},`);
+    for (const section of CATALOG_SECTIONS) {
+        const rows = catalog[section];
+        if (rows.length === 0) {
+            lines.push(`  ${JSON.stringify(section)}: [],`);
+            continue;
+        }
+        lines.push(`  ${JSON.stringify(section)}: [`);
+        rows.forEach((row, j) => lines.push(`    ${JSON.stringify(row)}${j === rows.length - 1 ? "" : ","}`));
+        lines.push("  ],");
+    }
+    const targets = Object.keys(catalog.storageParameters);
+    lines.push(`  "storageParameters": {`);
+    targets.forEach((t, j) => lines.push(`    ${JSON.stringify(t)}: ${JSON.stringify(catalog.storageParameters[t])}${j === targets.length - 1 ? "" : ","}`));
+    lines.push("  }", "}");
+    return `${lines.join("\n")}\n`;
+}
+/** Parse and shape-check a snapshot. Throws naming the first section that is missing or not a list. */
+export function parseCatalog(text) {
+    const value = JSON.parse(text);
+    if (value.dialect !== "postgres")
+        throw new Error(`not a Postgres catalog (dialect ${String(value.dialect)})`);
+    if (typeof value.version !== "string")
+        throw new Error("catalog has no version");
+    for (const section of CATALOG_SECTIONS) {
+        if (!Array.isArray(value[section]))
+            throw new Error(`catalog section ${section} is missing or not a list`);
+    }
+    if (typeof value.storageParameters !== "object" || value.storageParameters === null) {
+        throw new Error("catalog section storageParameters is missing");
+    }
+    return value;
+}

package/dist/spec/postgres-fetch.js

@@ -0,0 +1,91 @@
+/**
+ * Where generation gets the Postgres catalogs.
+ *
+ * The committed snapshots, `postgres-catalog-<major>.snapshot.json`, are the
+ * source every ordinary run reads: a fresh clone, CI and `npm run prepack`
+ * generate from them with no Docker and no network. A server is read, one per
+ * major, only when a snapshot cannot serve its pin:
+ *
+ * - the major's pin moved (its `version` in `postgres-pin.ts` differs from the
+ *   snapshot's) or the snapshot is missing or unreadable, or
+ * - `force` is set.
+ *
+ * Reading a server means starting that major's image by tag and digest in a
+ * throwaway container, checking that its `server_version` is the pin, reading
+ * the catalog, and rewriting the snapshot. A server at any other version is
+ * refused: a snapshot labelled with one pin and holding another's surface is
+ * the failure the pin exists to prevent.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { POSTGRES_PINS, postgresImage, postgresPin } from "./postgres-pin.js";
+import { parseCatalog, readCatalog, stringifyCatalog } from "./postgres-catalog.js";
+import { startScratchPostgres } from "../postgres/container.js";
+const specDir = moduleSourceDir(import.meta.url);
+/** The committed snapshot of one major. */
+export const snapshotFile = (major, dir = specDir) => join(dir, `postgres-catalog-${major}.snapshot.json`);
+function readSnapshot(file) {
+    try {
+        return parseCatalog(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read one pin's catalog from a server and refuse any other version. */
+export async function catalogFromServer(reader, pin, image) {
+    const catalog = await readCatalog(reader, image);
+    if (catalog.version !== pin.version) {
+        throw new Error(`the server for Postgres ${pin.major} is ${catalog.version}, not the pinned ${pin.version}. ` +
+            `Run the pinned image, or update the ${pin.major} line of src/spec/postgres-pin.ts: version and digest together.`);
+    }
+    return catalog;
+}
+const defaultStart = async (image) => {
+    const server = await startScratchPostgres(image, { namePrefix: "chant-sql-pg-catalog" });
+    return {
+        reader: { query: async (sql) => JSON.parse((await server.psql(sql)).trim()) },
+        stop: server.stop,
+    };
+};
+/**
+ * The catalogs for the current pins, oldest major first: each snapshot that
+ * matches its pin, and a fresh read (which rewrites the snapshot) for each
+ * that does not. Servers run one at a time.
+ */
+export async function fetchCatalogs(options = {}) {
+    const log = options.log ?? ((line) => console.error(line));
+    const start = options.startServer ?? defaultStart;
+    const wanted = options.majors ?? POSTGRES_PINS.map((p) => p.major);
+    const catalogs = [];
+    for (const pin of POSTGRES_PINS) {
+        const file = snapshotFile(pin.major, options.snapshotDir);
+        const snapshot = readSnapshot(file);
+        const read = wanted.includes(pin.major);
+        if (snapshot && snapshot.version === pin.version && !(options.force && read)) {
+            log(`[sql] postgres ${pin.major} catalog: committed snapshot at ${snapshot.version}`);
+            catalogs.push(snapshot);
+            continue;
+        }
+        const reason = !snapshot
+            ? "no readable snapshot"
+            : snapshot.version !== pin.version
+                ? `the pin moved from ${snapshot.version} to ${pin.version}`
+                : "force";
+        const image = postgresImage(pin.major);
+        log(`[sql] postgres ${pin.major} catalog: starting ${image} (${reason})`);
+        const server = await start(image);
+        let catalog;
+        try {
+            catalog = await catalogFromServer(server.reader, postgresPin(pin.major), image);
+        }
+        finally {
+            await server.stop();
+        }
+        writeFileSync(file, stringifyCatalog(catalog));
+        log(`[sql] postgres ${pin.major} catalog: wrote ${file}`);
+        catalogs.push(catalog);
+    }
+    return catalogs;
+}

package/dist/spec/postgres-pin.js

@@ -0,0 +1,82 @@
+/**
+ * The pinned Postgres servers the Postgres dialect's types come from.
+ *
+ * Postgres publishes no schema for its DDL either. Types, access methods,
+ * operator classes, settings, keywords, function names and extensions are read
+ * from a running server's catalog (chant #3277), so a pin is a server image.
+ * One snapshot per supported major, 14 to 18 (14 leaves community support in
+ * November 2026, and dropping it is deleting its entry and its snapshot), and
+ * the generated types are the union of the five with a `since` and an `until`
+ * major on every entry that is not in all of them.
+ *
+ * Each entry pins an exact minor by tag and by digest. The type surface does
+ * not move between minors (17.9 against 17.11 differs by one setting), but a
+ * floating `18` tag would change generated output with no commit, and a
+ * re-pushed tag must not change it unseen either: generation runs
+ * `image@digest` and refuses a server whose `server_version` is not the
+ * entry's version. The digest is the multi-arch manifest list's.
+ *
+ * Moving a pin: change that major's `version` and `digest` on its one line,
+ * then `chant dev generate` (or `npm run generate`). The committed snapshot no
+ * longer matches, so generation starts that image, rewrites
+ * `src/spec/postgres-catalog-<major>.snapshot.json`, and the pull request's
+ * diff of that file is the surface change. Read its `-` lines: a removed
+ * setting or function is what breaks declarations. Adding a major is one more
+ * line here and one more snapshot.
+ *
+ * The lines are written one per major, in this exact shape, because
+ * {@link postgresUpstreamPin} finds a major's version with a regular
+ * expression over its line.
+ */
+/** The official server image. */
+export const POSTGRES_IMAGE_REPOSITORY = "postgres";
+/** One pin per supported major, oldest first. */
+export const POSTGRES_PINS = [
+    { major: 14, version: "14.24", digest: "sha256:c2427de38f998489d36de7ca3553db2134872c400f2b08be4b824e5c50e4d619" },
+    { major: 15, version: "15.19", digest: "sha256:724292da1f2e50bdccfc3302ce75bbba7f4a6076701b588cc795fcac65683550" },
+    { major: 16, version: "16.15", digest: "sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54" },
+    { major: 17, version: "17.11", digest: "sha256:d74eeac9a635390a49bc21bd49fccd973de707e2a53a76ac49b552b8712ec46f" },
+    { major: 18, version: "18.6", digest: "sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722" },
+];
+/** The supported majors, oldest first. */
+export const POSTGRES_MAJORS = POSTGRES_PINS.map((p) => p.major);
+/** The latest supported major: the emulator image and the default for a project that names no version. */
+export const POSTGRES_LATEST_MAJOR = POSTGRES_MAJORS[POSTGRES_MAJORS.length - 1];
+export function postgresPin(major) {
+    const pin = POSTGRES_PINS.find((p) => p.major === major);
+    if (!pin)
+        throw new Error(`Postgres ${major} is not a supported major (${POSTGRES_MAJORS.join(", ")})`);
+    return pin;
+}
+/** The full image reference generation runs: tag for the reader, digest for the runtime. */
+export function postgresImage(major) {
+    const pin = postgresPin(major);
+    return `${POSTGRES_IMAGE_REPOSITORY}:${pin.version}@${pin.digest}`;
+}
+/**
+ * `postgres/postgres` publishes no GitHub releases, only tags: `REL_18_6`,
+ * `REL_18_BETA1`, `REL_18_RC1`, `REL9_6_24`, `Release_2_0`. A stable release
+ * maps to `18.6`; every other spelling is skipped.
+ */
+export function versionFromReleaseTag(tag) {
+    const m = /^REL_(\d+)_(\d+)$/.exec(tag);
+    return m ? `${m[1]}.${m[2]}` : null;
+}
+/**
+ * The upstream pin descriptor for one major's line in this file, labelled
+ * `postgres-<major>`. The sql plugin lists all five in `upstreamPins` beside
+ * ClickHouse's `upstreamPin`, so `chant dev pinned-upgrade` and the upgrade Op
+ * report each. Each tracks only its own major (`trackMajor`), so the 17 pin
+ * reports `17.12` and never `18.6`.
+ */
+export function postgresUpstreamPin(major) {
+    postgresPin(major);
+    return {
+        label: `postgres-${major}`,
+        file: "src/spec/postgres-pin.ts",
+        pattern: new RegExp(`\\{ major: ${major}, version: "([^"]+)"`),
+        replace: (v, line) => line.replace(/version: "[^"]+"/, `version: "${versionFromReleaseTag(v) ?? v}"`),
+        alsoMoves: `the digest on the same line of src/spec/postgres-pin.ts moves with the version: set version to the new minor, set digest to that tag's image digest (docker buildx imagetools inspect postgres:<version>), then run \`chant dev generate\` and read the diff of src/spec/postgres-catalog-${major}.snapshot.json. A git tag lands a few days before its image tag, so the report can name a version that has no image yet.`,
+        upstream: { owner: "postgres", repo: "postgres", kind: "tags", tagVersion: versionFromReleaseTag, trackMajor: true },
+    };
+}