@intentius/chant-lexicon-sql 0.124.11 → 0.124.13

package/src/postgres/parser.ts

@@ -35,11 +35,11 @@
  * `src/backend/parser/gram.y` at `REL_18_6` where a page is silent.
  */
 
-import { kw, SqlCursor, type Span } from "../core/cursor";
+import { kw, SqlCursor, type Span, type UnknownClause } from "../core/cursor";
 import { SqlSyntaxError, type Token } from "../core/tokens";
 import { keywordCategory } from "./keywords";
 
-export type { Span } from "../core/cursor";
+export type { Span, UnknownClause } from "../core/cursor";
 export { SqlSyntaxError };
 
 /** An identifier as Postgres reads it: an unquoted name folds to lower case, a quoted one is exact. */
@@ -116,6 +116,8 @@ export interface ColumnNode {
 
 export interface TableNode {
   statement: "table";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   persistence?: "temporary" | "unlogged";
   ifNotExists: boolean;
   name: NameNode;
@@ -141,6 +143,8 @@ export interface IndexElement {
 
 export interface IndexNode {
   statement: "index";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   unique: boolean;
   concurrently: boolean;
   ifNotExists: boolean;
@@ -158,6 +162,8 @@ export interface IndexNode {
 
 export interface ViewNode {
   statement: "view";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   materialized: boolean;
   orReplace: boolean;
   temporary: boolean;
@@ -176,6 +182,8 @@ export interface ViewNode {
 
 export interface SequenceNode {
   statement: "sequence";
+  /** Clauses the parser does not know (#3872), kept in the DDL as written; absent when there are none. */
+  unknown?: UnknownClause[];
   persistence?: "temporary" | "unlogged";
   ifNotExists: boolean;
   name: NameNode;
@@ -366,6 +374,18 @@ const COLUMN_CLAUSE = [
   "ENFORCED",
 ];
 
+/** A column's clause words, and its constraints' attributes: an unknown clause stops at the next (#3872). */
+const COLUMN_WORDS = [...COLUMN_CLAUSE, "REFERENCES", "ON", "MATCH", "NO", "WITH", "INCLUDE", "USING"];
+
+/** The clauses after a table's column list. */
+const TABLE_WORDS = ["INHERITS", "PARTITION", "USING", "WITH", "WITHOUT", "ON", "TABLESPACE", "FOR", "DEFAULT"];
+
+/** The clauses after an index's elements. */
+const INDEX_WORDS = ["INCLUDE", "NULLS", "WITH", "TABLESPACE", "WHERE"];
+
+/** The clauses before a view's AS. */
+const VIEW_WORDS = ["USING", "WITH", "TABLESPACE", "AS"];
+
 /** `LIKE source_table [ like_option ... ]`'s option words. */
 const LIKE_OPTIONS = ["COMMENTS", "COMPRESSION", "CONSTRAINTS", "DEFAULTS", "GENERATED", "IDENTITY", "INDEXES", "STATISTICS", "STORAGE", "ALL"];
 
@@ -653,7 +673,7 @@ class PgParser extends SqlCursor {
       if (this.accept("COMPRESSION")) col.compression = this.expr(COLUMN_CLAUSE);
       else if (this.accept("STORAGE")) col.storage = this.expr(COLUMN_CLAUSE);
       else if (this.accept("COLLATE")) col.collate = this.expr(COLUMN_CLAUSE);
-      else if (!this.columnConstraint(col)) break;
+      else if (!this.columnConstraint(col) && !this.unknownClause(COLUMN_WORDS, { inList: true, column: text || undefined })) break;
     }
     const after = this.peek();
     if (after && !(after.kind === "punct" && (after.text === "," || after.text === ")"))) this.fail("expected a column constraint, ',' or ')'");
@@ -991,7 +1011,7 @@ class PgParser extends SqlCursor {
         if (!(this.acceptSeq("PRESERVE", "ROWS") || this.acceptSeq("DELETE", "ROWS") || this.accept("DROP"))) this.fail("expected PRESERVE ROWS, DELETE ROWS or DROP");
         node.onCommit = this.span(from, []);
       } else if (this.accept("TABLESPACE")) node.tablespace = this.nameTok("a tablespace").span;
-      else break;
+      else if (!this.unknownClause(TABLE_WORDS)) break;
     }
     return node;
   }
@@ -1061,7 +1081,7 @@ class PgParser extends SqlCursor {
         node.with = this.reloptions();
       } else if (this.accept("TABLESPACE")) node.tablespace = this.nameTok("a tablespace").span;
       else if (this.accept("WHERE")) node.where = this.checkedExpr([], false);
-      else return node;
+      else if (!this.unknownClause(INDEX_WORDS)) return node;
     }
   }
 
@@ -1085,7 +1105,7 @@ class PgParser extends SqlCursor {
         this.p++;
         node.with = this.reloptions();
       } else if (materialized && this.accept("TABLESPACE")) node.tablespace = this.nameTok("a tablespace").span;
-      else break;
+      else if (!this.unknownClause(VIEW_WORDS)) break;
     }
     this.expect("AS");
     const tail = materialized
@@ -1131,7 +1151,7 @@ class PgParser extends SqlCursor {
       else if (this.acceptSeq("OWNED", "BY")) {
         if (this.accept("NONE")) node.options.push({ option: "OWNED BY", value: this.span(this.idx(-1), []) });
         else node.options.push({ option: "OWNED BY", value: this.qualifiedName("a column").span });
-      } else return node;
+      } else if (!this.unknownClause(STOP)) return node;
     }
   }
 
@@ -1575,7 +1595,10 @@ class PgParser extends SqlCursor {
     const out: StatementNode[] = [];
     while (this.peek() !== undefined) {
       if (this.acceptPunct(";")) continue;
-      out.push(this.parse());
+      const before = this.unknownClauses.length;
+      const node = this.parse();
+      if (this.unknownClauses.length > before) (node as { unknown?: UnknownClause[] }).unknown = this.unknownClauses.slice(before);
+      out.push(node);
       if (this.peek() !== undefined && !this.isPunct(";")) this.fail(`unexpected token after the ${describe(out[out.length - 1]!)}`);
     }
     if (out.length === 0) this.fail("expected a statement");

package/src/postgres/plan/diff.ts

@@ -197,7 +197,25 @@ function diffConstraints(key: string, before: PgDiffObject, after: PgDiffObject,
 const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
 const show = (v: unknown): string | undefined => (v === undefined ? undefined : typeof v === "string" ? v : JSON.stringify(v));
 
+/**
+ * The clauses chant does not read (#3872), compared as text: one the
+ * declaration has and the server does not, or has differently, is a change
+ * to review (SQLPG299); one only the server prints is a hint, since a
+ * default a newer server prints cannot be told from a clause removed.
+ */
+function diffUnparsed(key: string, before: PgDiffObject, after: PgDiffObject, out: PgChange[], hints: string[]): void {
+  const b = (before.fields.unparsed as Record<string, string> | undefined) ?? {};
+  const a = (after.fields.unparsed as Record<string, string> | undefined) ?? {};
+  for (const clause of Object.keys(a)) {
+    if (b[clause] !== a[clause]) out.push(change(key, `unparsed.${clause}`, "SQLPG299", b[clause], a[clause], { note: "chant does not read this clause; review the change" }));
+  }
+  for (const clause of Object.keys(b)) {
+    if (!(clause in a)) hints.push(`${key}: the current definition has ${clause} (${b[clause]}), a clause chant does not read and the declaration does not have; it is not compared`);
+  }
+}
+
 function diffObject(key: string, before: PgDiffObject, after: PgDiffObject, out: PgChange[], hints: string[], major: number): void {
+  diffUnparsed(key, before, after, out, hints);
   if (before.kind !== after.kind) {
     out.push(change(key, "kind", "SQLPG268", before.kind, after.kind));
     return;

package/src/postgres/plan/normalize.ts

@@ -797,6 +797,18 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
       break;
     }
   }
+  // Clauses the parser does not know (#3872): compared as text, by clause.
+  const unparsed = props.unparsed as Array<{ clause: string; text: string; column?: string }> | undefined;
+  if (unparsed && unparsed.length > 0) {
+    const out: Record<string, string> = {};
+    for (const u of unparsed) {
+      const base = u.column !== undefined ? `columns.${u.column}.${u.clause}` : u.clause;
+      let key = base;
+      for (let n = 2; key in out; n++) key = `${base}#${n}`;
+      out[key] = canonicalExpr(u.text) ?? u.text;
+    }
+    fields.unparsed = out;
+  }
   return { ...base, fields: Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && v !== false)), columns, constraints };
 }
 

package/src/postgres/plan/rules.ts

@@ -350,6 +350,13 @@ export const PG_CLASSIFIER_RULES = {
     "ALTER DEFAULT PRIVILEGES changes what objects created afterwards are given; objects that exist keep their privileges.",
     `${DOCS}/sql-alterdefaultprivileges.html`,
   ),
+  SQLPG299: rule(
+    "SQLPG299",
+    "expand",
+    "Change a clause chant does not read",
+    "chant's parser does not know this clause, so it cannot tell which lock the change takes or whether an in-place statement makes it; the plan refuses it rather than guess. Review it: make it by hand with the ALTER the server documents for the clause, or as expand and contract.",
+    `${DOCS}/sql-altertable.html`,
+  ),
   SQLPG270: rule("SQLPG270", "drop", "Drop an object", "The object and, for a table, a materialized view or a sequence, its data are gone.", `${DOCS}/sql-droptable.html`),
 } as const satisfies Record<string, PgClassifierRule>;
 

package/src/postgres/testdata/server-ddl-baseline.json

@@ -0,0 +1,38 @@
+{
+  "release": "REL_18_6",
+  "unknownClauses": [
+    "USING"
+  ],
+  "failures": [
+    "expected AS at 'USING'",
+    "expected IDENTITY (a generated column is GENERATED ALWAYS AS) at '('",
+    "expected NOT NULL, NULL or CHECK at 'REFERENCES'",
+    "expected NOT NULL, NULL or CHECK at 'generated'",
+    "expected RANGE or LIST or HASH at 'MAGIC'",
+    "expected a column constraint, ',' or ')' at 'NOT'",
+    "expected a column name ('with' is a reserved key word; quote it to use it as a name) at 'with'",
+    "expected a column type at ')'",
+    "expected a column type at ','",
+    "expected a partition bound value at ')'",
+    "expected a table name at '\\'",
+    "expected an expression at ')'",
+    "expected an index name ('ON' is a reserved key word; quote it to use it as a name) at 'ON'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'AS'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'TABLESPACE'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'USING'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'WITH'",
+    "expected the column list (CREATE TABLE ... AS is not declared here) at 'as'",
+    "expected the end of the default (a default cannot hold this operator unparenthesized) at 'IN'",
+    "schema elements inside CREATE SCHEMA are not declared here; declare each object on its own at 'CREATE'",
+    "schema elements inside CREATE SCHEMA are not declared here; declare each object on its own at 'create'",
+    "unexpected end of statement",
+    "unexpected token after the domain definition at 'ENFORCED'",
+    "unexpected token after the domain definition at 'NOT'",
+    "unexpected token after the domain definition at 'PRIMARY'",
+    "unexpected token after the domain definition at 'deferrable'",
+    "unexpected token after the domain definition at 'no'",
+    "unexpected token after the domain definition at 'unique'",
+    "unexpected token after the table definition at 'WITH'",
+    "unexpected token after the table definition at '\\'"
+  ]
+}

package/src/postgres.ts

@@ -105,3 +105,15 @@ export {
 } from "./postgres/migrate/op";
 export { POSTGRES_RECEIPTS_TABLE } from "./postgres/migrate/receipts";
 export * from "./composites/postgres";
+
+// The build's Postgres objects as typed values, for a project's own
+// `lint.policies` (#3870); also at `@intentius/chant-lexicon-sql/read`.
+export {
+  readPostgres,
+  canonicalPostgresType,
+  type PostgresRead,
+  type PostgresTableInfo,
+  type PostgresColumnInfo,
+  type PostgresIndexInfo,
+  type PostgresViewInfo,
+} from "./read/postgres";

package/src/read/clickhouse.ts

@@ -0,0 +1,137 @@
+/**
+ * The ClickHouse half of the public read API (`../read.ts`): the build's
+ * tables, columns, sort keys, skip indexes, engines and views as typed values,
+ * built from the serialized output. The lexicon's post-synth checks read the
+ * same values (`../lint/post-synth/clickhouse-helpers.ts`).
+ */
+
+import { relationKey } from "../core/typed";
+import type { ColumnDef } from "../clickhouse/entities";
+import { bareName, baseEngineName, isMergeTree, isNullableType, keyElements, typeFamily, unwrapType } from "../clickhouse/expressions";
+import { dialectObjects, type ClickHouseTableJson, type ClickHouseViewJson, type SqlObjectJson, type SqlReadSource } from "./objects";
+
+/** A column of a ClickHouse table or view, as declared, with what follows from the declaration. */
+export interface ClickHouseColumnInfo extends ColumnDef {
+  /** Whether the column can hold NULL: its type is `Nullable(...)` (inside `LowCardinality` too), or it is declared `NULL`. */
+  nullable: boolean;
+  /** `LowCardinality(...)`. */
+  lowCardinality: boolean;
+  /** The type without its `Nullable` and `LowCardinality` wrappers, as written: `DateTime64(3, 'UTC')`. */
+  baseType?: string;
+  /** The type family's canonical name, as the pinned server's catalog has it: `BIGINT UNSIGNED` is `UInt64`, `DateTime64(3)` is `DateTime64`. */
+  family?: string;
+  /** A bare element of the table's sort key (`ORDER BY`). */
+  inSortKey: boolean;
+}
+
+/** A ClickHouse table, as declared: its columns, engine, keys and skip indexes. */
+export interface ClickHouseTableInfo extends Omit<ClickHouseTableJson, "columns"> {
+  /** `database.name` when the DDL qualifies it, else the name: the table's key in `SqlSchema`. */
+  qualifiedName: string;
+  columns: ClickHouseColumnInfo[];
+  /** The engine without a `Replicated` prefix: `ReplicatedReplacingMergeTree` is `ReplacingMergeTree`. */
+  engineFamily?: string;
+  /** A MergeTree family engine, replicated or not. */
+  mergeTree: boolean;
+  /** The `ORDER BY` elements, as written, without `ASC`/`DESC`; empty for `tuple()` or none. */
+  sortKey: string[];
+  /** The `PRIMARY KEY` elements, else the sort key's, which is what ClickHouse uses when none is written. */
+  primaryKeyElements: string[];
+  /** The column named `name`, if the table declares one. */
+  column(name: string): ClickHouseColumnInfo | undefined;
+}
+
+/** A view or materialized view, with the names of its output columns. */
+export interface ClickHouseViewInfo extends Omit<ClickHouseViewJson, "columns"> {
+  qualifiedName: string;
+  materialized: boolean;
+  columns: ClickHouseColumnInfo[];
+  /** The declared columns, else the outputs of the query's select list. */
+  outputs: string[];
+}
+
+/** What a ClickHouse build declares. */
+export interface ClickHouseRead {
+  dialect: "clickhouse";
+  tables: ClickHouseTableInfo[];
+  views: ClickHouseViewInfo[];
+  /** Every serialized object, databases, dictionaries, users and grants included, in apply order. */
+  objects: SqlObjectJson[];
+  /** A table by export name, `database.name`, or name. */
+  table(ref: string): ClickHouseTableInfo | undefined;
+}
+
+function columnInfo(c: ColumnDef, sortKey: ReadonlySet<string>): ClickHouseColumnInfo {
+  const inner = /^LowCardinality\s*\(/i.test((c.type ?? "").trim());
+  const nullable = c.nullable === true || isNullableType(c.type) || (inner && isNullableType(unwrapLowCardinality(c.type!)));
+  return {
+    ...c,
+    nullable,
+    lowCardinality: inner,
+    ...(c.type !== undefined ? { baseType: unwrapType(c.type), family: typeFamily(c.type) } : {}),
+    inSortKey: sortKey.has(c.name),
+  };
+}
+
+function unwrapLowCardinality(type: string): string {
+  return type.trim().replace(/^LowCardinality\s*\(([\s\S]*)\)$/i, "$1").trim();
+}
+
+function build(objects: SqlObjectJson[]): ClickHouseRead {
+  const tables = objects
+    .filter((o) => o.type === "ClickHouse::Table")
+    .map((o): ClickHouseTableInfo => {
+      const t = o as unknown as ClickHouseTableJson;
+      const sortKey = t.orderBy ? keyElements(t.orderBy) : [];
+      const bare = new Set(sortKey.map(bareName).filter((n): n is string => n !== undefined));
+      const columns = (t.columns ?? []).map((c) => columnInfo(c, bare));
+      return {
+        ...t,
+        qualifiedName: relationKey(t),
+        columns,
+        ...(t.engine ? { engineFamily: baseEngineName(t.engine) } : {}),
+        mergeTree: isMergeTree(t.engine),
+        sortKey,
+        primaryKeyElements: t.primaryKey ? keyElements(t.primaryKey) : sortKey,
+        column: (name) => columns.find((c) => c.name === name),
+      };
+    });
+  const views = objects
+    .filter((o) => o.type === "ClickHouse::View" || o.type === "ClickHouse::MaterializedView")
+    .map((o): ClickHouseViewInfo => {
+      const v = o as unknown as ClickHouseViewJson;
+      const columns = (v.columns ?? []).map((c) => columnInfo(c, new Set()));
+      return {
+        ...v,
+        qualifiedName: relationKey(v),
+        materialized: v.type === "ClickHouse::MaterializedView",
+        columns,
+        outputs: columns.length > 0 ? columns.map((c) => c.name) : (v.lineage ?? []).map((e) => e.output),
+      };
+    });
+  return {
+    dialect: "clickhouse",
+    tables,
+    views,
+    objects,
+    table: (ref) => tables.find((t) => t.export === ref) ?? tables.find((t) => t.qualifiedName === ref) ?? tables.find((t) => t.name === ref),
+  };
+}
+
+const cache = new WeakMap<object, ClickHouseRead>();
+
+/**
+ * What a ClickHouse build declares, read from a post-synth context's `docs`
+ * (a `lint.policies` check's `ctx`), or from the serialized output document
+ * itself. Empty when the build has no ClickHouse output. The result is cached
+ * per context; treat it as read-only.
+ */
+export function readClickHouse(source: SqlReadSource | { dialect: string; objects: unknown[] }): ClickHouseRead {
+  if ("objects" in source) return build(source.dialect === "clickhouse" ? (source.objects as SqlObjectJson[]) : []);
+  const key = source.docs;
+  const hit = key ? cache.get(key) : undefined;
+  if (hit) return hit;
+  const read = build(dialectObjects(source, "clickhouse"));
+  if (key) cache.set(key, read);
+  return read;
+}

package/src/read/objects.ts

@@ -0,0 +1,137 @@
+/**
+ * The sql build output as the serializer writes it (`../serializer.ts`): one
+ * JSON document per build with `dialect`, `applyOrder` and `objects`, each
+ * object its entity's props with the template source dropped, the DDL moved
+ * to the end, and every reference to another declared object written as that
+ * object's export name.
+ *
+ * This is the one place that finds those documents in a post-synth context.
+ * The public read API (`../read.ts`) and the lexicon's own post-synth checks
+ * (`../lint/post-synth/sql-helpers.ts`) both start here.
+ */
+
+import type { OutputDoc } from "@intentius/chant/lint/post-synth";
+import type * as ch from "../clickhouse/entities";
+import type * as pg from "../postgres/entities";
+
+/** What a reader takes: a post-synth context, or anything else carrying its `docs`. */
+export interface SqlReadSource {
+  readonly docs?: readonly OutputDoc[];
+}
+
+/** One build output document, as the serializer writes it. */
+export interface SqlOutputDocument {
+  dialect: "clickhouse" | "postgres";
+  /** Postgres only: the major the build targets (`sql.postgresMajor`, else the newest pinned). */
+  postgresMajor?: number;
+  applyOrder?: string[];
+  objects: SqlObjectJson[];
+}
+
+/** A reference to another declared object: its export name, or null when it is not one the build declares. */
+export type RefJson = string | null;
+
+/** The fields every serialized object has. */
+export interface SqlObjectBase {
+  /** The export name of the declaration. */
+  export: string;
+  /** The entity type: `Postgres::Table`, `ClickHouse::MaterializedView`, ... */
+  type: string;
+  /** The object's name in the database, unquoted. */
+  name: string;
+  /** The name it is referred to by in SQL: `name`, or `schema.name` / `database.name`. */
+  sqlName?: string;
+  /** The export names it must be created after. */
+  dependsOn?: string[];
+  /** The statements as they will be sent. */
+  ddl?: string;
+}
+
+/** Any serialized object: the common fields, and the rest of its props as written. */
+export interface SqlObjectJson extends SqlObjectBase {
+  [key: string]: unknown;
+}
+
+type Serialized<P> = Omit<P, "source" | "ddl"> & Omit<SqlObjectBase, "type"> & { sqlName: string; dependsOn: string[]; ddl: string };
+
+/** A lineage edge as written: the output column, its expression, and the `export.column` names it reads. */
+export interface LineageJson {
+  output: string;
+  expr: string;
+  from: Array<string | null>;
+}
+
+// ── Postgres ──────────────────────────────────────────────────────────
+
+export interface PostgresForeignKeyJson extends Omit<pg.ForeignKeyDef, "references"> {
+  /** The referenced table's export name, or null when the build does not declare it. */
+  references: RefJson;
+}
+
+export interface PostgresTableJson
+  extends Omit<Serialized<pg.TableProps>, "partitionOf" | "ofType" | "inherits" | "foreignKeys"> {
+  type: "Postgres::Table";
+  partitionOf?: RefJson;
+  ofType?: RefJson;
+  inherits: RefJson[];
+  foreignKeys: PostgresForeignKeyJson[];
+}
+
+export interface PostgresIndexJson extends Omit<Serialized<pg.IndexProps>, "table"> {
+  type: "Postgres::Index";
+  /** The indexed table's export name, or null when the build does not declare it. */
+  table: RefJson;
+}
+
+export interface PostgresViewJson extends Omit<Serialized<pg.ViewProps>, "reads" | "lineage"> {
+  type: "Postgres::View" | "Postgres::MaterializedView";
+  reads: RefJson[];
+  lineage: LineageJson[];
+}
+
+// ── ClickHouse ────────────────────────────────────────────────────────
+
+export interface ClickHouseTableJson extends Serialized<ch.TableProps> {
+  type: "ClickHouse::Table";
+}
+
+export interface ClickHouseViewJson extends Omit<Serialized<ch.ViewProps>, "to" | "reads" | "lineage"> {
+  type: "ClickHouse::View" | "ClickHouse::MaterializedView";
+  /** A materialized view's target: its export name when declared, else the name as written. */
+  to?: RefJson;
+  reads: RefJson[];
+  lineage: LineageJson[];
+}
+
+// ── Finding the documents ─────────────────────────────────────────────
+
+/** True for a value shaped like the serializer's document. */
+export function isSqlOutputDocument(value: unknown): value is SqlOutputDocument {
+  const v = value as { dialect?: unknown; objects?: unknown } | null;
+  return v !== null && typeof v === "object" && (v.dialect === "clickhouse" || v.dialect === "postgres") && Array.isArray(v.objects);
+}
+
+/** Every sql output document in the context, in output order. */
+export function sqlDocuments(source: SqlReadSource): SqlOutputDocument[] {
+  const out: SqlOutputDocument[] = [];
+  for (const doc of source.docs ?? []) {
+    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
+    if (isSqlOutputDocument(doc.value)) out.push(doc.value);
+  }
+  return out;
+}
+
+/** Every serialized object of one dialect, across the context's sql documents. */
+export function dialectObjects(source: SqlReadSource, dialect: SqlOutputDocument["dialect"]): SqlObjectJson[] {
+  const out: SqlObjectJson[] = [];
+  for (const doc of sqlDocuments(source)) if (doc.dialect === dialect) out.push(...doc.objects);
+  return out;
+}
+
+/** The Postgres major the build output records, else `fallback`. */
+export function recordedPostgresMajor(source: SqlReadSource, fallback: number): number {
+  for (const doc of sqlDocuments(source)) {
+    if (doc.dialect === "postgres" && typeof doc.postgresMajor === "number") return doc.postgresMajor;
+  }
+  return fallback;
+}