@intentius/chant-lexicon-sql 0.124.12 → 0.124.13

package/src/lint/post-synth/sql-helpers.ts

@@ -1,41 +1,26 @@
 /**
  * Reading the sql lexicon's build output in a post-synth check: the JSON
- * document the serializer writes (`dialect`, `applyOrder`, `objects`).
+ * document the serializer writes (`dialect`, `applyOrder`, `objects`). The
+ * documents are found by `../../read/objects.ts`, the same path the public
+ * read API (`@intentius/chant-lexicon-sql/read`) takes.
  */
 
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { dialectObjects, recordedPostgresMajor, type SqlObjectJson } from "../../read/objects";
 
-export interface OutputObject {
-  export: string;
-  type: string;
-  name: string;
+export interface OutputObject extends SqlObjectJson {
   database?: string;
   engine?: { name: string; args?: string[] };
-  [key: string]: unknown;
 }
 
 /** Every schema object in the build's sql output, ClickHouse dialect. */
 export function clickhouseObjects(ctx: PostSynthContext): OutputObject[] {
-  const out: OutputObject[] = [];
-  for (const doc of ctx.docs ?? []) {
-    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
-    const value = doc.value as { dialect?: unknown; objects?: unknown };
-    if (value?.dialect !== "clickhouse" || !Array.isArray(value.objects)) continue;
-    out.push(...(value.objects as OutputObject[]));
-  }
-  return out;
+  return dialectObjects(ctx, "clickhouse") as OutputObject[];
 }
 
 /** Every schema object in the build's sql output, Postgres dialect. */
 export function postgresObjects(ctx: PostSynthContext): OutputObject[] {
-  const out: OutputObject[] = [];
-  for (const doc of ctx.docs ?? []) {
-    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
-    const value = doc.value as { dialect?: unknown; objects?: unknown };
-    if (value?.dialect !== "postgres" || !Array.isArray(value.objects)) continue;
-    out.push(...(value.objects as OutputObject[]));
-  }
-  return out;
+  return dialectObjects(ctx, "postgres") as OutputObject[];
 }
 
 /**
@@ -44,10 +29,5 @@ export function postgresObjects(ctx: PostSynthContext): OutputObject[] {
  * output that carries none.
  */
 export function postgresMajorOf(ctx: PostSynthContext, fallback: number): number {
-  for (const doc of ctx.docs ?? []) {
-    if (doc.error || doc.lexicon !== "sql" || doc.format !== "json") continue;
-    const value = doc.value as { dialect?: unknown; postgresMajor?: unknown };
-    if (value?.dialect === "postgres" && typeof value.postgresMajor === "number") return value.postgresMajor;
-  }
-  return fallback;
+  return recordedPostgresMajor(ctx, fallback);
 }

package/src/lint/post-synth/sqlch102.ts

@@ -1,5 +1,4 @@
-import { checkOf, isTable, keyElements } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, keyElements, tablesOf } from "./clickhouse-helpers";
 
 /**
  * SQLCH102: a PRIMARY KEY that is not a prefix of ORDER BY.
@@ -9,7 +8,7 @@ import { clickhouseObjects } from "./sql-helpers";
  * the table at CREATE.
  */
 export const sqlch102 = checkOf({ id: "SQLCH102", description: "A PRIMARY KEY is not a prefix of ORDER BY" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (!t.primaryKey || !t.orderBy) continue;
     const pk = keyElements(t.primaryKey).map((e) => e.replace(/\s+/g, ""));
     const ob = keyElements(t.orderBy).map((e) => e.replace(/\s+/g, ""));

package/src/lint/post-synth/sqlch103.ts

@@ -1,5 +1,4 @@
-import { baseEngineName, checkOf, columnByName, engineArguments, isNullableType, isTable, typeFamily } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { baseEngineName, checkOf, columnByName, engineArguments, isNullableType, tablesOf, typeFamily } from "./clickhouse-helpers";
 
 const VERSION_TYPES = new Set(["UInt8", "UInt16", "UInt32", "UInt64", "UInt128", "UInt256", "Date", "DateTime", "DateTime64"]);
 
@@ -25,7 +24,7 @@ const SPECIAL: Record<string, Array<{ role: string; index: number; accepts: (fam
  * .../collapsingmergetree, .../versionedcollapsingmergetree (sign: Int8).
  */
 export const sqlch103 = checkOf({ id: "SQLCH103", description: "An engine's version, sign or is_deleted column has an unsupported type" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (!t.engine) continue;
     const roles = SPECIAL[baseEngineName(t.engine)];
     if (!roles) continue;

package/src/lint/post-synth/sqlch104.ts

@@ -1,5 +1,4 @@
-import { baseEngineName, checkOf, engineArguments, isTable, splitTop } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { baseEngineName, checkOf, engineArguments, splitTop, tablesOf } from "./clickhouse-helpers";
 
 /** The engine arguments that name columns, by base engine. */
 function columnArguments(engine: string, args: string[]): string[] {
@@ -26,7 +25,7 @@ function columnArguments(engine: string, args: string[]): string[] {
  * sign, version, is_deleted and summed columns are columns of the table).
  */
 export const sqlch104 = checkOf({ id: "SQLCH104", description: "A MergeTree engine argument names a column the table does not declare" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (!t.engine || t.columns.length === 0) continue;
     const declared = new Set(t.columns.map((c) => c.name));
     for (const arg of columnArguments(baseEngineName(t.engine), engineArguments(t.engine))) {

package/src/lint/post-synth/sqlch105.ts

@@ -1,5 +1,4 @@
-import { bareName, checkOf, isTable, keyElements } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { bareName, checkOf, keyElements, tablesOf } from "./clickhouse-helpers";
 
 /**
  * SQLCH105: ORDER BY, PRIMARY KEY, PARTITION BY or SAMPLE BY lists a bare
@@ -10,7 +9,7 @@ import { clickhouseObjects } from "./sql-helpers";
  * judged; an expression is left to the server.
  */
 export const sqlch105 = checkOf({ id: "SQLCH105", description: "A table key clause names a column the table does not declare" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (t.columns.length === 0) continue;
     const declared = new Set(t.columns.map((c) => c.name));
     const clauses: Array<[string, string | undefined]> = [

package/src/lint/post-synth/sqlch106.ts

@@ -1,5 +1,4 @@
-import { checkOf, isTable, mentionedNames } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, mentionedNames, tablesOf } from "./clickhouse-helpers";
 
 /**
  * SQLCH106: a data skipping index expression mentions a column the table does
@@ -11,7 +10,7 @@ import { clickhouseObjects } from "./sql-helpers";
  * SQL parser would guess.
  */
 export const sqlch106 = checkOf({ id: "SQLCH106", description: "A skip index expression names a column the table does not declare" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (t.columns.length === 0) continue;
     const declared = new Set(t.columns.map((c) => c.name));
     for (const index of t.indexes ?? []) {

package/src/lint/post-synth/sqlch107.ts

@@ -1,5 +1,4 @@
-import { bareName, checkOf, isTable, splitTop, typeFamily } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { bareName, checkOf, splitTop, tablesOf, typeFamily } from "./clickhouse-helpers";
 
 const DATE_TYPES = new Set(["Date", "Date32", "DateTime", "DateTime64"]);
 const TTL_ACTION = /\s+(DELETE|TO\s+DISK|TO\s+VOLUME|RECOMPRESS|GROUP\s+BY|WHERE)\b[\s\S]*$/i;
@@ -13,7 +12,7 @@ const TTL_ACTION = /\s+(DELETE|TO\s+DISK|TO\s+VOLUME|RECOMPRESS|GROUP\s+BY|WHERE
  * a function call is left to the server.
  */
 export const sqlch107 = checkOf({ id: "SQLCH107", description: "A TTL expression is built on a column that is not a Date or DateTime" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     const ttls: Array<{ where: string; expr: string }> = [];
     if (t.ttl) for (const clause of splitTop(t.ttl)) ttls.push({ where: "table TTL", expr: clause.replace(TTL_ACTION, "") });
     for (const c of t.columns) if (c.ttl) ttls.push({ where: `column ${c.name} TTL`, expr: c.ttl.replace(TTL_ACTION, "") });

package/src/lint/post-synth/sqlch111.ts

@@ -1,5 +1,4 @@
-import { checkOf, isTable, splitTop } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, splitTop, tablesOf } from "./clickhouse-helpers";
 
 const MAX_VALUES = 100;
 
@@ -23,7 +22,7 @@ function allowedValues(expr: string): { column: string; count: number } | undefi
  * https://clickhouse.com/docs/best-practices/select-data-types.
  */
 export const sqlch111 = checkOf({ id: "SQLCH111", description: "A String column limited to a few values is not LowCardinality" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     for (const c of t.constraints ?? []) {
       if (c.kind !== "CHECK") continue;
       const found = allowedValues(c.expr);

package/src/lint/post-synth/sqlch112.ts

@@ -1,5 +1,4 @@
-import { checkOf, isTable, typeFamily } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, tablesOf, typeFamily } from "./clickhouse-helpers";
 
 const FINE_FUNCTIONS =
   /\b(toStartOfSecond|toStartOfMinute|toStartOfFiveMinutes?|toStartOfTenMinutes|toStartOfFifteenMinutes|toStartOfHour|toRelativeSecondNum|toRelativeMinuteNum|toRelativeHourNum|toUnixTimestamp|toYYYYMMDDhhmmss|toStartOfInterval)\s*\(/;
@@ -15,7 +14,7 @@ const FINE_FUNCTIONS =
  * the sub-day truncation functions.
  */
 export const sqlch112 = checkOf({ id: "SQLCH112", description: "A PARTITION BY expression is finer than a day" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     const expr = t.partitionBy?.trim();
     if (!expr) continue;
     const col = t.columns.find((c) => c.name === expr.replace(/^\(|\)$/g, "").trim());

package/src/lint/post-synth/sqlch113.ts

@@ -1,5 +1,4 @@
-import { checkOf, isMergeTree, isTable } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, isMergeTree, tablesOf } from "./clickhouse-helpers";
 
 /**
  * SQLCH113: a MergeTree table with neither ORDER BY nor PRIMARY KEY.
@@ -9,7 +8,7 @@ import { clickhouseObjects } from "./sql-helpers";
  * `ORDER BY tuple()` to have none). The server refuses the CREATE.
  */
 export const sqlch113 = checkOf({ id: "SQLCH113", description: "A MergeTree table declares no sort key" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (!isMergeTree(t.engine) || t.orderBy || t.primaryKey) continue;
     report({
       severity: "error",

package/src/lint/post-synth/sqlch114.ts

@@ -1,6 +1,5 @@
 import { CODECS } from "../../generated/clickhouse";
-import { checkOf, codecNames, isTable } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, codecNames, tablesOf } from "./clickhouse-helpers";
 
 /**
  * SQLCH114: a column CODEC names a codec the pinned server does not have.
@@ -10,7 +9,7 @@ import { clickhouseObjects } from "./sql-helpers";
  */
 export const sqlch114 = checkOf({ id: "SQLCH114", description: "A column codec is not one the pinned server has" }, (ctx, report) => {
   const known = new Set(Object.keys(CODECS).map((n) => n.toLowerCase()));
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     for (const c of t.columns) {
       if (!c.codec) continue;
       for (const name of codecNames(c.codec)) {

package/src/lint/post-synth/sqlch115.ts

@@ -1,6 +1,5 @@
 import { CODECS } from "../../generated/clickhouse";
-import { checkOf, codecNames, isTable } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, codecNames, tablesOf } from "./clickhouse-helpers";
 
 const SENSITIVE = /(^|_)(password|passwd|pwd|secret|api_?key|access_?key|private_?key|token|ssn|social_?security|credit_?card|card_?number|iban)(_|$)/i;
 
@@ -17,7 +16,7 @@ const SENSITIVE = /(^|_)(password|passwd|pwd|secret|api_?key|access_?key|private
  */
 export const sqlch115 = checkOf({ id: "SQLCH115", description: "A secret- or PII-named column carries no comment, TTL or encryption" }, (ctx, report) => {
   const encryption = new Set(Object.entries(CODECS).filter(([, s]) => s.encryption).map(([n]) => n.toLowerCase()));
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     for (const c of t.columns) {
       if (!SENSITIVE.test(c.name) || c.comment || c.ttl || t.ttl) continue;
       if (c.codec && codecNames(c.codec).some((n) => encryption.has(n.toLowerCase()))) continue;

package/src/lint/post-synth/sqlch120.ts

@@ -1,5 +1,4 @@
-import { checkOf, isTable } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, tablesOf } from "./clickhouse-helpers";
 
 /**
  * SQLCH120: a MergeTree engine written with the legacy positional arguments.
@@ -10,7 +9,7 @@ import { clickhouseObjects } from "./sql-helpers";
  * syntax is a bare `MergeTree` with ORDER BY, PARTITION BY and SETTINGS.
  */
 export const sqlch120 = checkOf({ id: "SQLCH120", description: "A MergeTree engine uses the deprecated positional arguments" }, (ctx, report) => {
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     if (t.engine?.name !== "MergeTree" || (t.engine.args ?? []).length === 0) continue;
     report({
       severity: "warning",

package/src/lint/post-synth/sqlch125.ts

@@ -1,6 +1,5 @@
 import { CODECS, CLICKHOUSE_VERSION } from "../../generated/clickhouse";
-import { checkOf, isTable, splitTop } from "./clickhouse-helpers";
-import { clickhouseObjects } from "./sql-helpers";
+import { checkOf, splitTop, tablesOf } from "./clickhouse-helpers";
 
 type Param = { name: string; kind: string; optional?: boolean; range?: readonly [number, number]; values?: readonly string[] };
 
@@ -17,7 +16,7 @@ const NUMBER = /^-?\d+(\.\d+)?$/;
  */
 export const sqlch125 = checkOf({ id: "SQLCH125", description: "A codec parameter is outside what the codec takes" }, (ctx, report) => {
   const codecs = CODECS as Record<string, { parameters: readonly Param[] | "unknown" } | undefined>;
-  for (const t of clickhouseObjects(ctx).filter(isTable)) {
+  for (const t of tablesOf(ctx)) {
     for (const c of t.columns) {
       if (!c.codec) continue;
       for (const part of splitTop(c.codec)) {

package/src/postgres/apply/statements.ts

@@ -789,6 +789,8 @@ export function refusalDetail(changes: readonly PgChange[], name: string, declar
       ? `Run it as the expand-and-contract migration Op: ${ops.join(", ")} from @intentius/chant-lexicon-sql/postgres (add the new column, write both, backfill, switch readers, then drop the old).` +
         (ops.length < changes.length ? " The other changes have no migration Op yet: make them by hand as expand and contract." : "")
       : "No migration Op makes this change yet: make it by hand as expand and contract (add the new, write both, backfill, move readers, then drop the old).";
+  // A clause chant does not read (#3872) is refused for review: what the change takes is not known.
+  if (changes.every((c) => c.rule === "SQLPG299")) return `${name} needs review, since chant does not read the clause, so nothing was sent for it. ${lines.join(" ")}`;
   return `${name} needs expand and contract, which no in-place statement makes, so nothing was sent for it. ${lines.join(" ")} ${instead}`;
 }
 

package/src/postgres/entities.ts

@@ -58,7 +58,7 @@ import { setInterpolationFields } from "@intentius/chant/provenance";
 import { isTrivia, POSTGRES_LEXICAL, SqlSyntaxError, untokenize, type Token } from "./tokens";
 import { identValue, parseStatements, type ColumnNode, type CommentNode, type ConstraintNode, type GrantNode, type NameNode, type RowSecurityNode, type Span, type StatementNode } from "./parser";
 import { keywordCategory, quoteIdent } from "./keywords";
-import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxError, type TemplateCtx, type TemplateDialect } from "../core/interpolation";
+import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxError, unparsedClauses, type TemplateCtx, type TemplateDialect, type UnparsedClause } from "../core/interpolation";
 import { SqlObject, isColumnRefOf, isSqlObjectOf, makeSqlEntity } from "../core/entity";
 import type { LineageEdge } from "../core/references";
 import { SqlLiteral, SqlTemplateError, describeValue as describe, stripUnset, templateParts } from "../core/template";
@@ -66,6 +66,7 @@ import { setTypedSlots, type ColumnsIn, type Named, type RowIn, type SlotsIn, ty
 
 export { SQL_LEXICON } from "../core/entity";
 export type { LineageEdge } from "../core/references";
+export type { UnparsedClause } from "../core/interpolation";
 export { SqlLiteral, SqlTemplateError } from "../core/template";
 export { quoteIdent } from "./keywords";
 export type { AnyColumn, Column, ColumnTraits, KeyColumn, Named, NotNullColumn, UncheckedColumn, Unnamed } from "../core/typed";
@@ -155,6 +156,11 @@ interface CommonProps {
   ddl: string;
   /** The template's raw parts, as written, for a source round trip. */
   source: { strings: string[] };
+  /**
+   * Clauses chant's parser does not know (#3872), kept in `ddl` as written
+   * and left to the catalog checks and the server. Absent when there are none.
+   */
+  unparsed?: UnparsedClause[];
 }
 
 export interface SchemaProps extends Omit<CommonProps, "schema"> {
@@ -1182,7 +1188,9 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
   const source = { strings: rawParts };
   const dependsOn = [...new Set([...values, ...(joined?.refs ?? [])].filter((v) => isPostgresObject(v) || isColumnRef(v)))];
   const slots: TypedSlot[] = [];
+  const unparsed = unparsedClauses(ctx, nodes.flatMap((n) => ("unknown" in n && n.unknown ? n.unknown : [])));
   const make = <T extends PostgresObject>(type: PostgresEntityType, q: { schema?: string; name: string }, props: object, columnNames?: readonly string[]): T => {
+    if (unparsed) (props as { unparsed?: UnparsedClause[] }).unparsed = unparsed;
     const entity = makeSqlEntity(PostgresObject.prototype as PostgresObject, type, sqlNameOf(q), props, columnNames, dependsOn) as T;
     const fed = ctx.fed.map((paths) => [...paths].sort());
     if (!joined) setInterpolationFields(entity, fed);

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";