@intentius/chant-lexicon-sql 0.124.46 → 0.124.48

package/src/postgres/plan/diff.ts

@@ -215,7 +215,7 @@ function diffUnparsed(key: string, before: PgDiffObject, after: PgDiffObject, ou
 }
 
 /** The kinds (#3911) whose definition has no ALTER: a change is a drop and a create, or (an aggregate's) CREATE OR REPLACE. */
-const REPLACED_KINDS: ReadonlySet<string> = new Set(["composite", "range", "aggregate", "collation", "cast", "eventTrigger"]);
+const REPLACED_KINDS: ReadonlySet<string> = new Set(["composite", "range", "aggregate", "collation", "cast", "eventTrigger", "operator", "statistics"]);
 
 /** What each of {@link REPLACED_KINDS} compares besides its name and comment. */
 const DEFINITION: Readonly<Record<string, readonly string[]>> = {
@@ -225,8 +225,39 @@ const DEFINITION: Readonly<Record<string, readonly string[]>> = {
   collation: ["provider", "lcCollate", "lcCtype", "locale", "nondeterministic", "rules"],
   cast: ["castMethod", "function", "context"],
   eventTrigger: ["event", "tags", "function"],
+  operator: ["definition"],
+  statistics: ["table", "kinds", "targets"],
+};
+
+/** The kinds (#3911) the server alters in place, with the fields that cannot be altered (the object is dropped and created) and those that can. */
+const ALTERED_KINDS: Readonly<Record<string, { recreate: readonly string[]; inPlace: readonly string[] }>> = {
+  foreignDataWrapper: { recreate: [], inPlace: ["handler", "validator", "options"] },
+  foreignServer: { recreate: ["serverType", "wrapper"], inPlace: ["version", "options"] },
+  publication: { recreate: ["allTables"], inPlace: ["tables", "schemas", "publish", "viaRoot", "generatedColumns"] },
 };
 
+/**
+ * A foreign data wrapper's, foreign server's or publication's change: the
+ * comment and each field ALTER reaches in place (SQLPG303); a field it does
+ * not reach (a server's type and wrapper, a publication's FOR ALL TABLES) by
+ * dropping and creating the object (SQLPG300), refused while something
+ * depends on it (SQLPG301).
+ */
+function diffAltered(key: string, before: PgDiffObject, after: PgDiffObject, out: PgChange[]): void {
+  if (!same(before.fields.comment, after.fields.comment)) out.push(change(key, "comment", "SQLPG216", show(before.fields.comment), show(after.fields.comment)));
+  const { recreate, inPlace } = ALTERED_KINDS[after.kind]!;
+  const replaced = recreate.filter((k) => !same(before.fields[k], after.fields[k]));
+  if (replaced.length > 0) {
+    const was = replaced.map((k) => `${k} ${show(before.fields[k]) ?? "-"}`).join("; ");
+    const now = replaced.map((k) => `${k} ${show(after.fields[k]) ?? "-"}`).join("; ");
+    if (before.dependents && before.dependents.length > 0) {
+      out.push(change(key, replaced.join(", "), "SQLPG301", was, now, { note: `${before.dependents.join(", ")} depend${before.dependents.length === 1 ? "s" : ""} on it` }));
+    } else out.push(change(key, replaced.join(", "), "SQLPG300", was, now));
+    return;
+  }
+  for (const k of inPlace) if (!same(before.fields[k], after.fields[k])) out.push(change(key, k, "SQLPG303", show(before.fields[k]), show(after.fields[k])));
+}
+
 /**
  * A type's, aggregate's, collation's, cast's or event trigger's change: its
  * comment in place; its definition by CREATE OR REPLACE AGGREGATE where that
@@ -270,6 +301,10 @@ function diffObject(key: string, before: PgDiffObject, after: PgDiffObject, out:
     diffReplaced(key, before, after, out);
     return;
   }
+  if (after.kind in ALTERED_KINDS) {
+    diffAltered(key, before, after, out);
+    return;
+  }
   if (before.schema !== after.schema || before.name !== after.name) {
     out.push(change(key, "name", after.kind === "index" ? "SQLPG229" : "SQLPG228", qualified(before), qualified(after)));
   }

package/src/postgres/plan/normalize.ts

@@ -51,6 +51,7 @@ import { stripMarker } from "../../core/ownership";
 import { sequenceDefaults } from "../live/catalog";
 import type {
   AggregateArgDef,
+  OperatorProps,
   AggregateProps,
   CastProps,
   CheckDef,
@@ -59,6 +60,10 @@ import type {
   CompositeTypeProps,
   DomainProps,
   EventTriggerProps,
+  StatisticsProps,
+  ForeignDataWrapperProps,
+  ForeignServerProps,
+  PublicationProps,
   RangeTypeProps,
   EnumProps,
   ExclusionDef,
@@ -348,6 +353,11 @@ export type CanonicalKind =
   | "collation"
   | "cast"
   | "eventTrigger"
+  | "operator"
+  | "statistics"
+  | "foreignDataWrapper"
+  | "foreignServer"
+  | "publication"
   | "function"
   | "procedure"
   | "trigger"
@@ -393,6 +403,11 @@ const kindOf: Record<string, CanonicalKind> = {
   "Postgres::Collation": "collation",
   "Postgres::Cast": "cast",
   "Postgres::EventTrigger": "eventTrigger",
+  "Postgres::Operator": "operator",
+  "Postgres::Statistics": "statistics",
+  "Postgres::ForeignDataWrapper": "foreignDataWrapper",
+  "Postgres::ForeignServer": "foreignServer",
+  "Postgres::Publication": "publication",
   "Postgres::Extension": "extension",
   "Postgres::Function": "function",
   "Postgres::Procedure": "procedure",
@@ -617,7 +632,7 @@ function triggerFields(p: TriggerProps, defaultSchema: string, fields: Record<st
 // ── Types, aggregates, collations, casts, event triggers (#3911) ──────
 
 /** The kinds that live in no schema. */
-const UNPLACED: ReadonlySet<CanonicalKind> = new Set(["schema", "extension", "role", "cast", "eventTrigger"]);
+const UNPLACED: ReadonlySet<CanonicalKind> = new Set(["schema", "extension", "role", "cast", "eventTrigger", "foreignDataWrapper", "foreignServer", "publication"]);
 
 /**
  * A function named where an object calls it (an aggregate's SFUNC, a cast's
@@ -700,6 +715,80 @@ function collationFields(p: CollationProps, fields: Record<string, unknown>): vo
   fields.rules = o.rules;
 }
 
+/** An operator's identity among its overloads: its operand types, `(integer,integer)`, `NONE` for a missing side. */
+export function operatorSignature(p: Pick<OperatorProps, "leftArg" | "rightArg">, defaultSchema: string): string {
+  const side = (t: string | undefined) => (t === undefined ? "NONE" : canonicalArgType(t, defaultSchema));
+  return `(${side(p.leftArg)},${side(p.rightArg)})`;
+}
+
+/**
+ * An operator named where another object names it (a COMMUTATOR or NEGATOR):
+ * `OPERATOR(app.===)`, `app.===` or a bare symbol, which the server looks for
+ * in the new operator's own schema, as `schema.symbol`.
+ */
+export function canonicalOperatorRef(text: string, ownSchema: string): string {
+  const inner = text.trim().replace(/^OPERATOR\s*\(\s*(.*?)\s*\)$/is, "$1");
+  const m = /^("(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)\s*\.\s*(\S.*)$/s.exec(inner);
+  return `${quoteIdent(m ? identValue(m[1]!) : ownSchema)}.${(m ? m[2]! : inner).trim()}`;
+}
+
+/** An operator's definition as compared: each function and operator named canonically, a flag only when set. */
+function operatorOptions(p: OperatorProps, ownSchema: string, defaultSchema: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(p.options)) {
+    if (k === "function" || k === "restrict" || k === "join") out[k] = canonicalFunctionName(v, defaultSchema);
+    else if (k === "commutator" || k === "negator") out[k] = canonicalOperatorRef(v, ownSchema);
+    else if (k === "hashes" || k === "merges") {
+      if (isTrue(v)) out[k] = "true";
+    } else out[k] = defValue(v);
+  }
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+
+/** An `OPTIONS (...)` list as compared: by name, none as nothing. */
+function sortedOptions(options: Record<string, string> | undefined): Record<string, string> | undefined {
+  const entries = Object.entries(options ?? {}).sort(([a], [b]) => (a < b ? -1 : 1));
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+const STATISTICS_ALL = ["dependencies", "mcv", "ndistinct"];
+
+/**
+ * The kinds of statistics gathered, sorted. Left out, the server builds all
+ * three, except for a lone expression, which gets none of them (only the
+ * expression's own statistics); `pg_get_statisticsobjdef` prints the list only
+ * when it is not that default.
+ */
+export function statisticsKinds(kinds: readonly string[] | undefined, targets: readonly string[]): string[] | undefined {
+  if (kinds && kinds.length > 0) {
+    const sorted = [...new Set(kinds.map((k) => k.toLowerCase()))].sort();
+    return sorted.join() === STATISTICS_ALL.join() ? undefined : sorted;
+  }
+  const lone = targets.length === 1 && !/^"?[A-Za-z_][A-Za-z0-9_$]*"?$/.test(targets[0]!.trim());
+  return lone ? ["none"] : undefined;
+}
+
+/** Every action a publication publishes when `publish` is not given. */
+const PUBLISH_ALL = ["delete", "insert", "truncate", "update"];
+
+/** A publication as compared: its tables with their column lists and row filters, its schemas, and each option at its default left out. */
+function publicationFields(p: PublicationProps, defaultSchema: string, fields: Record<string, unknown>): void {
+  fields.allTables = p.allTables === true;
+  const tables = p.tables.map((t) => ({
+    table: canonicalName(t.tableName, defaultSchema),
+    ...(t.columns && t.columns.length > 0 ? { columns: [...t.columns].sort() } : {}),
+    ...(t.where ? { where: canonicalExpr(t.where) } : {}),
+  }));
+  fields.tables = tables.length > 0 ? tables.sort((a, b) => (a.table < b.table ? -1 : 1)) : undefined;
+  fields.schemas = p.schemas.length > 0 ? p.schemas.map((s) => quoteIdent(identValue(s))).sort() : undefined;
+  const o = p.options;
+  const publish = o.publish === undefined ? PUBLISH_ALL : [...new Set(defValue(o.publish).split(",").map((x) => x.trim().toLowerCase()).filter(Boolean))].sort();
+  fields.publish = publish.join() === PUBLISH_ALL.join() ? undefined : publish;
+  fields.viaRoot = isTrue(o.publish_via_partition_root);
+  const generated = o.publish_generated_columns === undefined ? "none" : defValue(o.publish_generated_columns);
+  fields.generatedColumns = generated === "none" ? undefined : generated;
+}
+
 /** A cast's name, `(source AS target)`, its types canonical. */
 export const castName = (p: Pick<CastProps, "sourceType" | "targetType">, defaultSchema: string): string =>
   `(${canonicalType(p.sourceType, defaultSchema)} AS ${canonicalType(p.targetType, defaultSchema)})`;
@@ -774,6 +863,38 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
       fields.function = canonicalFunctionName(p.functionName, defaultSchema);
       break;
     }
+    case "operator": {
+      const p = props as unknown as OperatorProps;
+      base.signature = operatorSignature(p, defaultSchema);
+      fields.definition = operatorOptions(p, base.schema!, defaultSchema);
+      break;
+    }
+    case "statistics": {
+      const p = props as unknown as StatisticsProps;
+      fields.table = canonicalName(p.tableName, defaultSchema);
+      const targets = p.targets.map((t) => canonicalExpr(t)!).sort();
+      fields.targets = targets;
+      fields.kinds = statisticsKinds(p.kinds, p.targets);
+      break;
+    }
+    case "foreignDataWrapper": {
+      const p = props as unknown as ForeignDataWrapperProps;
+      fields.handler = p.handlerName && !p.noHandler ? canonicalFunctionName(p.handlerName, defaultSchema) : undefined;
+      fields.validator = p.validatorName && !p.noValidator ? canonicalFunctionName(p.validatorName, defaultSchema) : undefined;
+      fields.options = sortedOptions(p.options);
+      break;
+    }
+    case "foreignServer": {
+      const p = props as unknown as ForeignServerProps;
+      fields.serverType = p.serverType;
+      fields.version = p.version;
+      fields.wrapper = quoteIdent(identValue(p.wrapperName));
+      fields.options = sortedOptions(p.options);
+      break;
+    }
+    case "publication":
+      publicationFields(props as unknown as PublicationProps, defaultSchema, fields);
+      break;
     case "function":
     case "procedure": {
       const p = props as unknown as RoutineProps;

package/src/postgres/plan/rules.ts

@@ -360,14 +360,14 @@ export const PG_CLASSIFIER_RULES = {
   SQLPG300: rule(
     "SQLPG300",
     "metadata",
-    "Drop and create a type, aggregate, collation, cast or event trigger",
-    "A composite or range type's definition, a collation's, a cast's and an event trigger's have no ALTER, and an aggregate's argument types, state type and final function cannot be replaced: the object is dropped and created in one transaction. Nothing on the server depends on it (a column, a view, a function or a cast would make the DROP fail); the locks are on its catalog rows only.",
+    "Drop and create a type, aggregate, collation, cast, event trigger, operator, statistics object, foreign server or publication",
+    "A composite or range type's definition, a collation's, a cast's, an event trigger's, an operator's function and operands and extended statistics' have no ALTER, an aggregate's argument types, state type and final function cannot be replaced, and neither can a foreign server's type or wrapper or a publication's FOR ALL TABLES: the object is dropped and created in one transaction. Nothing on the server depends on it (a column, a view, a function or a cast would make the DROP fail); the locks are on its catalog rows only. Dropped statistics are empty until the next ANALYZE, and a publication that is dropped stops its subscribers until it is created again.",
     `${DOCS}/sql-createtype.html`,
   ),
   SQLPG301: rule(
     "SQLPG301",
     "expand",
-    "Change a type, aggregate, collation or cast that other objects depend on",
+    "Change a type, aggregate, collation, cast, foreign server or publication that other objects depend on",
     "No ALTER makes the change, and DROP refuses while a column, a view, a function or another object depends on the object. Create the new definition under another name, move what depends on it, then drop the old.",
     `${DOCS}/sql-droptype.html`,
   ),
@@ -378,6 +378,13 @@ export const PG_CLASSIFIER_RULES = {
     "CREATE OR REPLACE AGGREGATE (14 and later) replaces the aggregate's functions and options in the catalog; no table is locked. Its argument types, its result and its kind (plain, ordered-set, hypothetical-set) have to stay the same, so a change of the state type or the final function is dropped and created instead (SQLPG300).",
     `${DOCS}/sql-createaggregate.html`,
   ),
+  SQLPG303: rule(
+    "SQLPG303",
+    "metadata",
+    "Alter a foreign data wrapper, foreign server or publication in place",
+    "ALTER FOREIGN DATA WRAPPER (handler, validator, options), ALTER SERVER (version, options) and ALTER PUBLICATION (SET options, ADD and DROP TABLE and TABLES IN SCHEMA) change the object's catalog rows under a brief lock; no table is rewritten. A publication's change reaches its subscribers as the walsender next reads it: a table added is not copied to a subscription until the subscriber runs REFRESH PUBLICATION.",
+    `${DOCS}/sql-alterpublication.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/plan/schema.ts

@@ -106,7 +106,7 @@ export function pgSchemaFromBuildFile(path: string, defaultSchema = "public"): P
  */
 export function pgNamespace(kind: string): string {
   if (kind === "schema" || kind === "extension" || kind === "trigger" || kind === "policy" || kind === "role") return kind;
-  if (kind === "collation" || kind === "cast" || kind === "eventTrigger") return kind;
+  if (kind === "collation" || kind === "cast" || kind === "eventTrigger" || kind === "operator" || kind === "statistics" || kind === "foreignDataWrapper" || kind === "foreignServer" || kind === "publication") return kind;
   if (kind === "grant" || kind === "defaultPrivileges") return "grant";
   if (kind === "enum" || kind === "domain" || kind === "composite" || kind === "range") return "type";
   if (kind === "function" || kind === "procedure" || kind === "aggregate") return "routine";

package/src/postgres/secret-options.ts

@@ -0,0 +1,10 @@
+/**
+ * Options that hold a credential. A foreign data wrapper's or server's
+ * `OPTIONS (...)` can carry any name, and a password in one would be written
+ * into a schema file by import and sent to every reader of the plan. The
+ * environment supplies credentials, in a user mapping (which is not declared)
+ * or its own secret store, as for a role's password (`./entities.ts`).
+ */
+
+/** Whether an option name reads as a credential: `password`, `sslpassword`, `secret_key`, `api_token`. */
+export const isSecretOption = (name: string): boolean => /pass(word|wd)?|secret|token|api[_-]?key|credential/i.test(name);

package/src/postgres/testing/roundtrip-schema.ts

@@ -5,7 +5,8 @@
  * sequence options, storage parameters, comments), an extension and the
  * domain over its type, a collation, composite and range types (and a
  * multirange column), plain and ordered-set aggregates, a cast and an event
- * trigger (#3911), a partitioned table and a partition, an ORM's
+ * trigger, an operator, extended statistics, a foreign data wrapper and server, and a
+ * publication (#3911), a partitioned table and a partition, an ORM's
  * revision table that import leaves out, and an object carrying chant's
  * ownership trailer.
  */
@@ -60,5 +61,16 @@ CREATE CAST (app.pair AS text) WITH FUNCTION app.pair_text(app.pair) AS ASSIGNME
 COMMENT ON CAST (app.pair AS text) IS 'a:b';
 CREATE FUNCTION app.audit() RETURNS event_trigger LANGUAGE plpgsql AS $$ BEGIN END $$;
 CREATE EVENT TRIGGER app_audit ON ddl_command_end WHEN TAG IN ('CREATE TABLE') EXECUTE FUNCTION app.audit();
+CREATE FUNCTION app.int_same(a integer, b integer) RETURNS boolean LANGUAGE sql IMMUTABLE AS $$ SELECT a = b $$;
+CREATE OPERATOR app.=== (FUNCTION = app.int_same, LEFTARG = integer, RIGHTARG = integer, COMMUTATOR = OPERATOR(app.===), RESTRICT = eqsel, JOIN = eqjoinsel, HASHES, MERGES);
+COMMENT ON OPERATOR app.===(integer, integer) IS 'Same value';
+CREATE STATISTICS app.orders_stats (dependencies) ON user_id, status FROM app.orders;
+COMMENT ON STATISTICS app.orders_stats IS 'Users and their order states';
+CREATE FOREIGN DATA WRAPPER app_fdw OPTIONS (debug 'true');
+COMMENT ON FOREIGN DATA WRAPPER app_fdw IS 'Remote tables';
+CREATE SERVER app_replica TYPE 'pg' VERSION '16' FOREIGN DATA WRAPPER app_fdw OPTIONS (host 'db.internal', port '5432');
+COMMENT ON SERVER app_replica IS 'The read replica';
+CREATE PUBLICATION app_pub FOR TABLE app.orders, app.users WITH (publish = 'insert, update');
+COMMENT ON PUBLICATION app_pub IS 'Order changes';
 CREATE TABLE public._prisma_migrations (id varchar(36) PRIMARY KEY, checksum varchar(64) NOT NULL);
 `;

package/src/postgres.ts

@@ -20,6 +20,11 @@ export {
   aggregate,
   trigger,
   eventTrigger,
+  operator,
+  statistics,
+  foreignDataWrapper,
+  foreignServer,
+  publication,
   collation,
   cast,
   policy,
@@ -49,6 +54,11 @@ export {
   type PostgresCollation,
   type PostgresCast,
   type PostgresEventTrigger,
+  type PostgresOperator,
+  type PostgresStatistics,
+  type PostgresForeignDataWrapper,
+  type PostgresForeignServer,
+  type PostgresPublication,
   type PostgresExtension,
   type PostgresFunction,
   type PostgresProcedure,
@@ -75,6 +85,12 @@ export {
   type CollationProps,
   type CastProps,
   type EventTriggerProps,
+  type OperatorProps,
+  type StatisticsProps,
+  type ForeignDataWrapperProps,
+  type ForeignServerProps,
+  type PublicationProps,
+  type PublicationTableDef,
   type DomainProps,
   type ExtensionProps,
   type RoutineProps,

package/src/serializer.ts

@@ -21,6 +21,11 @@
  * of each. Two databases of different dialects are two projects (two
  * workspace members, #3047 question 1).
  *
+ * A ClickHouse object that names a named collection (an engine's first
+ * argument, a table function's, a dictionary source's `NAME`) carries
+ * `namedCollections`, and the document lists every one the build names, so
+ * a plan can check each exists on the server (#4395).
+ *
  * A Postgres document also carries `postgresMajor`, the major the project
  * targets (`sql.postgresMajor`, else the newest pinned major). Post-synth
  * checks and the lock classifier read it; ClickHouse output has no such field.
@@ -43,6 +48,7 @@ import { sqlFileLineOf, sqlFileOf, sqlFileReferences } from "./sql-files";
 import { relative } from "node:path";
 import { getProvenance } from "@intentius/chant/provenance";
 import type { UnparsedClause } from "./core/interpolation";
+import { namedCollectionReferences, type CollectionReferrer } from "./clickhouse/named-collections";
 
 export { applyOrder } from "./core/references";
 
@@ -89,8 +95,9 @@ function objectJson(name: string, obj: ClickHouseObject, names: Map<Declarable,
     props.lineage = lineageJson(props.lineage as LineageEdge[], names);
   }
   const dependsOn = [...new Set([...obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined), ...extra])];
+  const collections = namedCollectionReferences(props as CollectionReferrer);
   return JSON.parse(
-    JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...props, dependsOn, ddl }),
+    JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...props, dependsOn, ...(collections.length > 0 ? { namedCollections: collections } : {}), ddl }),
   ) as Record<string, unknown>;
 }
 
@@ -170,10 +177,14 @@ export const sqlSerializer: Serializer = {
 
     const extra = sqlFileReferences("clickhouse", objects);
     const order = applyOrder(objects, names, extra);
+    const json = order.map((n) => objectJson(n, objects.get(n)!, names, extra.get(n)));
+    // The named collections the build references (#4395), each once, by name: a plan checks each exists.
+    const collections = [...new Set(json.flatMap((o) => (o.namedCollections as string[] | undefined) ?? []))].sort();
     const doc = {
       dialect: "clickhouse",
       applyOrder: order,
-      objects: order.map((n) => objectJson(n, objects.get(n)!, names, extra.get(n))),
+      ...(collections.length > 0 ? { namedCollections: collections } : {}),
+      objects: json,
     };
     const ddl = order
       .map((n) => `${(objects.get(n)!.props as { ddl: string }).ddl};`)

package/src/skills/chant-sql-postgres-migration.md

@@ -114,12 +114,12 @@ or set `replicationLag: false` to run without the check.
 The Plan phase refuses, naming each object and what to do, a table or column with:
 
 - something on the column it does not carry over: an exclusion constraint, a constraint trigger, a materialized view, a rule, a trigger, a policy, a statistics object, a generated column computed from it, an INVALID index, or a view the build does not declare;
-- on a partitioned table, an index, key or foreign key on the column, or the column in the partition key (chant #3333);
+- on a partitioned table, a key or foreign key on the column, or the column in the partition key;
 - a partition (run the Op on its partitioned table) or an inheritance tree (chant #3333);
 - a generated column itself, which the applier changes in place;
 - no primary key;
-- a rename combined with a type change: run the Op twice, the rename first (chant #3331);
-- a rename of a column with a default, an identity or a serial sequence: drop the default, rename, declare it again (chant #3331);
+- a rename combined with a type change, unless the Op gives `reverse` (the old column's value from the new one); with a default, a serial or an identity as well, run the Op twice, the rename first;
+- a rename of a column with a default, an identity or a serial sequence, unless the Op gives `defaultAtContract: true` (the default lands on the new column at the contract; an explicit NULL into the new name gets the default until then);
 - a column a logical replication publication sends; a column list that leaves it out does not stop the Op (chant #3332);
 - a column that needs no migration, where the message says to use the applier.
 

package/src/skills/chant-sql-postgres.md

@@ -42,6 +42,11 @@ The export name (`users`) is the object's identity in chant. The name in the SQL
 | `aggregate` | `CREATE AGGREGATE` | `Postgres::Aggregate` |
 | `trigger` | `CREATE TRIGGER` | `Postgres::Trigger` |
 | `eventTrigger` | `CREATE EVENT TRIGGER` | `Postgres::EventTrigger` |
+| `operator` | `CREATE OPERATOR` | `Postgres::Operator` |
+| `statistics` | `CREATE STATISTICS` | `Postgres::Statistics` |
+| `foreignDataWrapper` | `CREATE FOREIGN DATA WRAPPER` | `Postgres::ForeignDataWrapper` |
+| `foreignServer` | `CREATE SERVER` | `Postgres::ForeignServer` |
+| `publication` | `CREATE PUBLICATION` | `Postgres::Publication` |
 | `collation` | `CREATE COLLATION` | `Postgres::Collation` |
 | `cast` | `CREATE CAST` | `Postgres::Cast` |
 | `policy` | `CREATE POLICY` | `Postgres::Policy` |
@@ -189,4 +194,4 @@ chant build src --lexicon sql -o dist/schema.json
 
 ## Not covered
 
-`ALTER` (other than a table's row-level security), role memberships, rules, operators, extended statistics, foreign data objects, publications and subscriptions, text search objects and base types are not declared with the tags. An aggregate is identified by its argument types; a cast is named `(source AS target)` and an event trigger lives in no schema. A definition change to a composite or range type, collation, cast or event trigger is a drop and a create, refused while something depends on it. Planning a schema change (`chant sql diff`, `chant sql plan`, the lock classes) is the `chant-sql-postgres-plan` skill. Apply and the expand-and-contract migration Op have their own skills, which arrive with the code they describe.
+`ALTER` (other than a table's row-level security), role memberships, rules, operator classes and families, foreign tables, user mappings, subscriptions, text search objects and base types are not declared with the tags. Import names an object of such a kind and stops; `docs/pages/object-coverage.mdx` lists every `CREATE` command and why. An aggregate is identified by its argument types; a cast is named `(source AS target)` and an event trigger lives in no schema. A definition change to a composite or range type, collation, cast or event trigger is a drop and a create, refused while something depends on it. Planning a schema change (`chant sql diff`, `chant sql plan`, the lock classes) is the `chant-sql-postgres-plan` skill. Apply and the expand-and-contract migration Op have their own skills, which arrive with the code they describe.

package/src/skills/chant-sql.md

@@ -114,6 +114,7 @@ When chant interprets a composite's factory at build time, each field records th
 | SQLCH002 | lint | a `Nullable` column in the sort key or primary key, which ClickHouse refuses without `allow_nullable_key` |
 | SQLCH003 | lint | `${events.kind}` where `${events.columns.kind}` was meant |
 | SQLCH101 | build | an engine the pinned ClickHouse server does not have |
+| SQLCH128 | build | a literal credential in an integration engine's or table function's arguments; name a named collection instead |
 
 ## Commands
 
@@ -126,6 +127,6 @@ chant build src --lexicon sql -o dist/schema.json
 
 ## Not covered
 
-`CREATE TABLE ... AS` and `CREATE TABLE ... AS SELECT` are not declared with the tags. Dictionaries, functions, named collections and access control are not modelled. A second dialect is not supported.
+`CREATE TABLE ... AS` and `CREATE TABLE ... AS SELECT` are not declared with the tags. A named collection is never declared: name one in an integration engine, a table function or a dictionary `SOURCE` (`ENGINE = S3(lake_creds, format = 'Parquet')`), and `chant sql plan` checks that the server has it. A second dialect is not supported.
 
 Note that `chant migrate` does not run schema migrations. Schema changes go through `chant sql plan`, apply and the rebuild Op, described in the `chant-sql-plan` and `chant-sql-rebuild` skills.

package/src/sql-types-command.ts

@@ -18,6 +18,12 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import type { CommandGroupContext } from "@intentius/chant/cli/command-group";
 import { renderSqlTypes, SQL_TYPES_FILE } from "./sql-types";
 
+export interface ProjectLocation {
+  config: Awaited<ReturnType<typeof import("@intentius/chant/config").loadChantConfigUpward>>["config"];
+  projectDir: string;
+  sourceDir: string;
+}
+
 const USAGE = "usage: chant sql types [--output <path>] [--check]";
 
 /** The `--output` value, or an error message. */
@@ -43,37 +49,53 @@ export function shadowingSource(path: string): string | undefined {
   return existsSync(source) ? source : undefined;
 }
 
-export async function runTypes(ctx: CommandGroupContext): Promise<number> {
-  const args = parseArgs(ctx.rawArgs);
-  if ("error" in args) {
-    console.error(`${args.error}\n${USAGE}`);
-    return 1;
-  }
-  const cwd = process.cwd();
+/** The project the working directory belongs to: its config, its root and its source directory. */
+export async function loadProject(cwd: string): Promise<ProjectLocation> {
   const { loadChantConfigUpward } = await import("@intentius/chant/config");
   const { config, configPath } = await loadChantConfigUpward(cwd);
   const projectDir = configPath ? dirname(configPath) : cwd;
-  const sourceDir = resolve(projectDir, config.sourceDir ?? ".");
-  const output = args.output !== undefined ? resolve(cwd, args.output) : join(sourceDir, SQL_TYPES_FILE);
-  const shadow = shadowingSource(output);
-  if (shadow) {
-    console.error(`chant sql types: ${relative(cwd, shadow) || basename(shadow)} sits beside ${relative(cwd, output) || basename(output)}, and tsc reads it instead of the declarations; rename one`);
-    return 1;
-  }
+  return { config, projectDir, sourceDir: resolve(projectDir, config.sourceDir ?? ".") };
+}
 
+/**
+ * The fold build's entities: what `chant build` declares, `.sql` files and
+ * composite members included. Prints the build's errors and returns
+ * undefined when it fails.
+ */
+export async function buildFolded(project: ProjectLocation, command: string, consequence: string) {
+  const { config, projectDir, sourceDir } = project;
   const { build } = await import("@intentius/chant/build");
   const { resolveBuildModes, resolveProjectBuildOptions } = await import("@intentius/chant/cli/build-options");
   const { loadPlugins, resolveProjectLexicons } = await import("@intentius/chant/cli/plugins");
   const { sqlSerializer } = await import("./serializer");
   const plugins = await loadPlugins(await resolveProjectLexicons(projectDir, { lexicon: "sql" }));
-  // The fold build's entities: what `chant build` declares, `.sql` files and composite members included.
   const options = resolveProjectBuildOptions({ config, configDir: projectDir, plugins, modes: resolveBuildModes(config, { fold: true }) });
   const result = await build(sourceDir, [sqlSerializer], undefined, options);
   if (result.errors.length > 0) {
     for (const e of result.errors) console.error(e instanceof Error ? e.message : String(e));
-    console.error("chant sql types: the build failed, so nothing was written");
+    console.error(`${command}: the build failed, so ${consequence}`);
+    return undefined;
+  }
+  return result;
+}
+
+export async function runTypes(ctx: CommandGroupContext): Promise<number> {
+  const args = parseArgs(ctx.rawArgs);
+  if ("error" in args) {
+    console.error(`${args.error}\n${USAGE}`);
     return 1;
   }
+  const cwd = process.cwd();
+  const { config, projectDir, sourceDir } = await loadProject(cwd);
+  const output = args.output !== undefined ? resolve(cwd, args.output) : join(sourceDir, SQL_TYPES_FILE);
+  const shadow = shadowingSource(output);
+  if (shadow) {
+    console.error(`chant sql types: ${relative(cwd, shadow) || basename(shadow)} sits beside ${relative(cwd, output) || basename(output)}, and tsc reads it instead of the declarations; rename one`);
+    return 1;
+  }
+
+  const result = await buildFolded({ config, projectDir, sourceDir }, "chant sql types", "nothing was written");
+  if (!result) return 1;
   const text = renderSqlTypes(result.entities, { projectDir, config: config as unknown as Record<string, unknown> });
   const shown = relative(cwd, output);
   const named = shown && !shown.startsWith("..") ? shown : output;

package/src/sql-types.ts

@@ -133,7 +133,7 @@ function originOf(entity: Declarable, exportName: string, projectDir: string): s
 }
 
 /** The names a relation's `.columns` record holds at run time, in order. */
-const runtimeColumns = (entity: Declarable | undefined): string[] => Object.keys((entity as { columns?: object } | undefined)?.columns ?? {});
+export const runtimeColumns = (entity: Declarable | undefined): string[] => Object.keys((entity as { columns?: object } | undefined)?.columns ?? {});
 
 /** Whether `expr` is the column `column` alone, bare or qualified (`o.user_id`). */
 function isBareColumn(expr: string, quoted: string): boolean {
@@ -148,7 +148,7 @@ interface LineageJson {
 }
 
 /** A view's column that passes one column through: that column's export and name. */
-function passthrough(o: OutputObject, name: string, quote: (c: string) => string): { export: string; column: string } | undefined {
+export function passthrough(o: OutputObject, name: string, quote: (c: string) => string): { export: string; column: string } | undefined {
   const edge = ((o.lineage as LineageJson[] | undefined) ?? []).find((e) => e.output === name);
   const ref = edge?.from.length === 1 ? edge.from[0] : undefined;
   if (!edge || !ref) return undefined;
@@ -177,7 +177,7 @@ function spell(canonical: string, t: ParsedType): string {
 const arrayOf = (ts: string): string => `${/[|&]/.test(ts) && !/^\{.*\}$/s.test(ts) ? `(${ts})` : ts}[]`;
 
 /** A Postgres type's spelling, row type, and whether the type itself forbids NULL (a serial, a NOT NULL domain). */
-function pgType(p: PgProject, text: string | undefined, depth = 0): { sqlType: string; ts: string; notNull: boolean } {
+export function pgType(p: PgProject, text: string | undefined, depth = 0): { sqlType: string; ts: string; notNull: boolean } {
   const t = parseType(text);
   if (!t || depth > 5) return { sqlType: text?.trim() || "unknown", ts: "unknown", notNull: false };
   const r = resolveType(p, t, { serial: true });
@@ -320,7 +320,7 @@ function renderEntry(e: RelationEntry, lines: string[]): void {
 }
 
 /** The dialect a build's entities declare, else the config's, else ClickHouse. */
-function dialectOf(entities: ReadonlyMap<string, Declarable>, config: Record<string, unknown>): SqlDialect {
+export function dialectOf(entities: ReadonlyMap<string, Declarable>, config: Record<string, unknown>): SqlDialect {
   try {
     return filesDialect(entities, config);
   } catch {
@@ -328,6 +328,12 @@ function dialectOf(entities: ReadonlyMap<string, Declarable>, config: Record<str
   }
 }
 
+/** The build's sql output as `chant build` writes it: the objects, and the Postgres major they were built for. */
+export function serializedObjects(entities: ReadonlyMap<string, Declarable>, config: Record<string, unknown>): { objects: OutputObject[]; postgresMajor?: number } {
+  const out = sqlSerializer.serialize(new Map(entities), undefined, { config }) as SerializerResult | string;
+  return JSON.parse(typeof out === "string" ? out : out.primary) as { objects: OutputObject[]; postgresMajor?: number };
+}
+
 /**
  * The `sql-types.d.ts` for a build's entities: one module that augments the
  * dialect's `SqlSchema` with each table, view and dictionary, in key order.
@@ -340,8 +346,7 @@ export function renderSqlTypes(entities: ReadonlyMap<string, Declarable>, opts:
   const sqlEntities = new Map([...entities].filter(([, e]) => isPostgresObject(e) || isClickHouseObject(e)));
   let entries: RelationEntry[] = [];
   if (sqlEntities.size > 0) {
-    const out = sqlSerializer.serialize(new Map(entities), undefined, { config }) as SerializerResult | string;
-    const doc = JSON.parse(typeof out === "string" ? out : out.primary) as { objects: OutputObject[]; postgresMajor?: number };
+    const doc = serializedObjects(entities, config);
     entries = dialect === "postgres" ? postgresEntries(doc.objects, doc.postgresMajor ?? PINNED_MAJOR, entities, projectDir) : clickhouseEntries(doc.objects, entities, projectDir);
   }
   const byKey = new Map<string, RelationEntry>();