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

package/src/spec/postgres-catalog.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+import { CATALOG_SECTIONS, majorOf, parseCatalog, stringifyCatalog } from "./postgres-catalog";
+import { snapshotFile } from "./postgres-fetch";
+import { POSTGRES_PINS } from "./postgres-pin";
+
+const read = (major: number) => readFileSync(snapshotFile(major), "utf-8");
+
+describe.each(POSTGRES_PINS.map((p) => [p.major, p.version, p.digest] as const))("the %i snapshot", (major, version, digest) => {
+  const text = read(major);
+  const catalog = parseCatalog(text);
+
+  test("is the pinned version, read from the pinned image", () => {
+    expect(catalog.version).toBe(version);
+    expect(majorOf(catalog.version)).toBe(major);
+    expect(catalog.versionNum).toBe(Number(`${major}${version.split(".")[1]!.padStart(4, "0")}`));
+    expect(catalog.image).toBe(`postgres:${version}@${digest}`);
+  });
+
+  test("round-trips to the same bytes, one entry per line", () => {
+    expect(stringifyCatalog(catalog)).toBe(text);
+    expect(text.split("\n").length).toBeGreaterThan(3000);
+  });
+
+  test("has every section, sorted by name", () => {
+    for (const section of CATALOG_SECTIONS) expect(catalog[section].length).toBeGreaterThan(0);
+    const names = catalog.settings.map((s) => s.name);
+    expect(names).toEqual([...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
+    expect(catalog.settings.some((s) => s.name.startsWith("server_version"))).toBe(false);
+  });
+
+  test("records the storage parameters the server accepts", () => {
+    expect(catalog.storageParameters.table).toContain("fillfactor");
+    expect(catalog.storageParameters["index:gin"]).toContain("fastupdate");
+  });
+});
+
+describe("parseCatalog", () => {
+  test("refuses another dialect's catalog and a missing section", () => {
+    expect(() => parseCatalog('{"dialect":"clickhouse"}')).toThrow(/not a Postgres catalog/);
+    expect(() => parseCatalog('{"dialect":"postgres","version":"18.6"}')).toThrow(/section types/);
+  });
+});

package/src/spec/postgres-catalog.ts

@@ -0,0 +1,301 @@
+/**
+ * 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";
+
+/** Runs a SQL script whose last statement returns one JSON value. A server, or a stub in a test. */
+export interface PostgresReader {
+  query(sql: string): Promise<unknown>;
+}
+
+export interface TypeRow {
+  /** `pg_type.typname`: `int4`. */
+  name: string;
+  /** `format_type()`: `integer`. */
+  sqlName: string;
+  /** `typtype`: base `b`, domain `d`, enum `e`, multirange `m`, pseudo `p`, range `r`. */
+  kind: string;
+  category: string;
+  len: number;
+  byval: boolean;
+}
+
+export interface AccessMethodRow {
+  name: string;
+  /** `i` for an index access method, `t` for a table access method. */
+  type: string;
+  /** What `pg_indexam_has_property` reports for the method (`can_unique`, `can_include`...); index methods only. */
+  properties: string[] | null;
+}
+
+export interface OpClassRow {
+  am: string;
+  name: string;
+  inputType: string;
+  default: boolean;
+  family: string;
+}
+
+export interface FunctionRow {
+  name: string;
+  /** `prokind`s over the overloads, sorted: `f` function, `a` aggregate, `p` procedure, `w` window. */
+  kinds: string;
+  overloads: number;
+  /** `pg_*`, `binary_upgrade*`, `*support`, or only ever an aggregate's support function: not for a user to call. */
+  internal: boolean;
+}
+
+export interface OperatorRow {
+  name: string;
+  kinds: string;
+  overloads: number;
+}
+
+export interface SettingRow {
+  name: string;
+  /** `bool`, `integer`, `real`, `string` or `enum`. */
+  type: string;
+  context: string;
+  category: string;
+  unit: string | null;
+  /** The compiled default (`boot_val`). */
+  default: string | null;
+  min: string | null;
+  max: string | null;
+  enumvals: string[] | null;
+}
+
+export interface KeywordRow {
+  word: string;
+  /** `U` unreserved, `C` column name, `T` reserved as function or type name, `R` reserved. */
+  code: string;
+  description: string;
+}
+
+export interface ExtensionRow {
+  name: string;
+  defaultVersion: string;
+  description: string | null;
+}
+
+/** Storage parameter names the server accepts, by relation kind: `table`, `toast`, `view`, `materialized view`, `index:<method>`. */
+export type StorageParameters = Record<string, string[]>;
+
+export interface PostgresCatalog {
+  dialect: "postgres";
+  /** `server_version` without the build suffix: `18.6`. */
+  version: string;
+  /** `server_version_num`: `180006`. */
+  versionNum: number;
+  /** The image reference that server ran. */
+  image: string;
+  types: TypeRow[];
+  accessMethods: AccessMethodRow[];
+  opclasses: OpClassRow[];
+  functions: FunctionRow[];
+  operators: OperatorRow[];
+  settings: SettingRow[];
+  keywords: KeywordRow[];
+  extensions: ExtensionRow[];
+  storageParameters: StorageParameters;
+}
+
+/** The list sections, in the order the snapshot writes them; `storageParameters` follows. */
+export const CATALOG_SECTIONS = [
+  "types",
+  "accessMethods",
+  "opclasses",
+  "functions",
+  "operators",
+  "settings",
+  "keywords",
+  "extensions",
+] as const satisfies readonly (keyof PostgresCatalog)[];
+
+/** The major of a version string: `18.6` is 18. */
+export function majorOf(version: string): number {
+  return Number.parseInt(version, 10);
+}
+
+// ── Reading a server ─────────────────────────────────────────────────
+
+const C = `collate "C"`;
+const agg = (select: string, order: string) =>
+  `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(): string {
+  const index = { btree: "a", hash: "a", brin: "a", gin: "arr", gist: "r", spgist: "r" } as const;
+  const targets: Array<[string, string]> = [
+    ["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) as Array<[string, string]>).map(
+      ([am, col]): [string, string] => [`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: PostgresReader, image: string): Promise<PostgresCatalog> {
+  const q = async <T>(key: keyof typeof QUERIES): Promise<T> => (await reader.query(QUERIES[key])) as T;
+  const catalog: PostgresCatalog = {
+    dialect: "postgres",
+    version: await q<string>("version"),
+    versionNum: await q<number>("versionNum"),
+    image,
+    types: await q<TypeRow[]>("types"),
+    accessMethods: await q<AccessMethodRow[]>("accessMethods"),
+    opclasses: await q<OpClassRow[]>("opclasses"),
+    functions: await q<FunctionRow[]>("functions"),
+    operators: await q<OperatorRow[]>("operators"),
+    settings: await q<SettingRow[]>("settings"),
+    keywords: await q<KeywordRow[]>("keywords"),
+    extensions: await q<ExtensionRow[]>("extensions"),
+    storageParameters: {},
+  };
+  const probed = (await reader.query(storageProbe())) as Array<{ target: string; name: string }>;
+  for (const r of probed) (catalog.storageParameters[r.target] ??= []).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: PostgresCatalog): string {
+  const lines: string[] = ["{"];
+  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] as unknown[];
+    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: string): PostgresCatalog {
+  const value = JSON.parse(text) as Partial<PostgresCatalog>;
+  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 as PostgresCatalog;
+}

package/src/spec/postgres-fetch.test.ts

@@ -0,0 +1,75 @@
+import { copyFileSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { fetchCatalogs, snapshotFile, type FetchCatalogsOptions } from "./postgres-fetch";
+import { POSTGRES_PINS } from "./postgres-pin";
+
+let dir: string;
+const quiet = () => undefined;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "chant-sql-pgfetch-"));
+  for (const p of POSTGRES_PINS) copyFileSync(snapshotFile(p.major), snapshotFile(p.major, dir));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+/** A server stand-in that reports `version` and returns no rows for the rest. */
+function stub(version: string, log: string[]): NonNullable<FetchCatalogsOptions["startServer"]> {
+  return async (image) => {
+    log.push(`start ${image}`);
+    return {
+      reader: {
+        query: async (sql) => {
+          if (sql.includes("server_version'), ' ', 1")) return version;
+          if (sql.includes("server_version_num")) return 0;
+          return sql.includes("drop schema") ? [] : [];
+        },
+      },
+      stop: async () => {
+        log.push("stop");
+      },
+    };
+  };
+}
+
+describe("where generation gets the Postgres catalogs", () => {
+  test("snapshots at their pins are read as they are, and no server is started", async () => {
+    const log: string[] = [];
+    const catalogs = await fetchCatalogs({ snapshotDir: dir, log: quiet, startServer: stub("1.0", log) });
+    expect(catalogs.map((c) => c.version)).toEqual(POSTGRES_PINS.map((p) => p.version));
+    expect(log).toEqual([]);
+  });
+
+  test("a snapshot behind its pin starts that major's image only, and refuses a server at another version", async () => {
+    const file = snapshotFile(17, dir);
+    const stale = readFileSync(file, "utf-8").replace('"version": "17.11"', '"version": "17.9"');
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(file, stale);
+    const log: string[] = [];
+    await expect(fetchCatalogs({ snapshotDir: dir, log: quiet, startServer: stub("17.9", log) })).rejects.toThrow(
+      /Postgres 17 is 17\.9, not the pinned 17\.11/,
+    );
+    expect(log).toEqual([expect.stringMatching(/^start postgres:17\.11@sha256:/), "stop"]);
+    expect(readFileSync(file, "utf-8")).toBe(stale);
+  });
+
+  test("a server at the pin rewrites the snapshot", async () => {
+    const file = snapshotFile(16, dir);
+    rmSync(file);
+    const log: string[] = [];
+    const catalogs = await fetchCatalogs({ snapshotDir: dir, majors: [16], log: quiet, startServer: stub("16.15", log) });
+    expect(catalogs.find((c) => c.version === "16.15")?.types).toEqual([]);
+    expect(readFileSync(file, "utf-8")).toContain('"version": "16.15"');
+    expect(log).toHaveLength(2);
+  });
+
+  test("force reads only the majors named", async () => {
+    const log: string[] = [];
+    await expect(
+      fetchCatalogs({ snapshotDir: dir, force: true, majors: [18], log: quiet, startServer: stub("18.6", log) }),
+    ).resolves.toHaveLength(5);
+    expect(log).toEqual([expect.stringContaining("postgres:18.6@"), "stop"]);
+    expect(readdirSync(dir)).toHaveLength(5);
+  });
+});

package/src/spec/postgres-fetch.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { POSTGRES_PINS, postgresImage, postgresPin, type PostgresPin } from "./postgres-pin";
+import { parseCatalog, readCatalog, stringifyCatalog, type PostgresCatalog, type PostgresReader } from "./postgres-catalog";
+import { startScratchPostgres } from "../postgres/container";
+
+const specDir = dirname(fileURLToPath(import.meta.url));
+
+/** The committed snapshot of one major. */
+export const snapshotFile = (major: number, dir: string = specDir): string =>
+  join(dir, `postgres-catalog-${major}.snapshot.json`);
+
+export interface FetchCatalogsOptions {
+  /** Read a server even when the snapshot matches the pin. */
+  force?: boolean;
+  /** Only these majors (the default is all). */
+  majors?: readonly number[];
+  /** The directory holding the snapshots. Tests point it elsewhere. */
+  snapshotDir?: string;
+  /** Start the server for a major. Tests stub it; the default runs the pinned image. */
+  startServer?: (image: string) => Promise<{ reader: PostgresReader; stop(): Promise<void> }>;
+  /** Log a line saying which route was taken. */
+  log?: (line: string) => void;
+}
+
+function readSnapshot(file: string): PostgresCatalog | undefined {
+  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: PostgresReader, pin: PostgresPin, image: string): Promise<PostgresCatalog> {
+  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: NonNullable<FetchCatalogsOptions["startServer"]> = async (image) => {
+  const server = await startScratchPostgres(image, { namePrefix: "chant-sql-pg-catalog" });
+  return {
+    reader: { query: async (sql) => JSON.parse((await server.psql(sql)).trim()) as unknown },
+    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: FetchCatalogsOptions = {}): Promise<PostgresCatalog[]> {
+  const log = options.log ?? ((line: string) => console.error(line));
+  const start = options.startServer ?? defaultStart;
+  const wanted = options.majors ?? POSTGRES_PINS.map((p) => p.major);
+  const catalogs: PostgresCatalog[] = [];
+  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: PostgresCatalog;
+    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/src/spec/postgres-pin.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "vitest";
+import {
+  POSTGRES_LATEST_MAJOR,
+  POSTGRES_MAJORS,
+  POSTGRES_PINS,
+  postgresImage,
+  postgresUpstreamPin,
+  versionFromReleaseTag,
+} from "./postgres-pin";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pinFile = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "postgres-pin.ts"), "utf-8");
+
+describe("the Postgres pins", () => {
+  test("one pin per supported major, 14 to 18, each an exact minor with an image digest", () => {
+    expect(POSTGRES_MAJORS).toEqual([14, 15, 16, 17, 18]);
+    expect(POSTGRES_LATEST_MAJOR).toBe(18);
+    expect(POSTGRES_PINS.map((p) => p.version)).toEqual(["14.24", "15.19", "16.15", "17.11", "18.6"]);
+    for (const p of POSTGRES_PINS) {
+      expect(p.version.startsWith(`${p.major}.`)).toBe(true);
+      expect(p.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    }
+  });
+
+  test("the image is the tag and the digest together", () => {
+    expect(postgresImage(18)).toBe(
+      "postgres:18.6@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722",
+    );
+    expect(() => postgresImage(13)).toThrow(/not a supported major/);
+  });
+});
+
+describe("the upstream pins", () => {
+  test("a git tag maps to the version; betas, release candidates and old spellings are skipped", () => {
+    expect(versionFromReleaseTag("REL_18_6")).toBe("18.6");
+    expect(versionFromReleaseTag("REL_17_11")).toBe("17.11");
+    for (const tag of ["REL_18_BETA1", "REL_18_RC1", "REL9_6_24", "Release_2_0"]) {
+      expect(versionFromReleaseTag(tag)).toBeNull();
+    }
+  });
+
+  test.each(POSTGRES_PINS.map((p) => [p.major, p.version] as const))("the %i pin finds its own line and writes the new version back", (major, version) => {
+    const pin = postgresUpstreamPin(major);
+    const line = pinFile.split("\n").find((l) => pin.pattern.test(l));
+    expect(line).toBeDefined();
+    expect(pin.pattern.exec(line!)?.[1]).toBe(version);
+    const next = pin.replace("REL_99_9", line!);
+    expect(next).toContain('version: "99.9"');
+    expect(next).toContain(`major: ${major},`);
+    expect(next).toContain("digest:");
+    expect(pin.upstream).toMatchObject({ owner: "postgres", repo: "postgres", kind: "tags", trackMajor: true });
+    expect(pin.upstream.tagVersion?.("REL_18_6")).toBe("18.6");
+    expect(pin.alsoMoves).toContain(`postgres-catalog-${major}.snapshot.json`);
+  });
+
+  test("no pattern matches another major's line", () => {
+    for (const p of POSTGRES_PINS) {
+      const matching = pinFile.split("\n").filter((l) => postgresUpstreamPin(p.major).pattern.test(l));
+      expect(matching).toHaveLength(1);
+    }
+  });
+});