@intentius/chant-lexicon-sql 0.124.18 → 0.124.19

package/src/coverage.ts

@@ -1,4 +1,17 @@
 /**
+ * Coverage, two ways.
+ *
+ * Which kinds of object each dialect declares (#3911): every `CREATE` command
+ * a pinned server has (`./coverage/<dialect>-commands.json`, written by
+ * `scripts/sql-create-commands.ts` from the server's own sources) has a row
+ * in `./coverage/<dialect>.json` marking it declared, refused with a reason,
+ * or out of scope. A command with several forms that differ in what chant can
+ * hold (`CREATE TYPE ... AS ENUM` and `CREATE TYPE ... AS RANGE`) has a row
+ * per form. Import refuses an object of a refused kind by that row's `kind`
+ * (`./core/undeclarable.ts`), and the docs page is rendered from the rows
+ * (`./codegen/coverage-page.ts`). To declare a kind, flip its row to
+ * `declared` with the `entity` that holds it, and drop the reason.
+ *
  * How much of the pinned ClickHouse catalog the dialect types beyond its name.
  *
  * Every engine, type family, codec, skip index type and setting at the pin is
@@ -9,6 +22,135 @@
  */
 
 import { CODECS, SKIP_INDEX_TYPES, TABLE_ENGINES, CLICKHOUSE_VERSION } from "./generated/clickhouse";
+import { POSTGRES_PINS } from "./spec/postgres-pin";
+import type { SqlDialect } from "./dialects";
+import postgresKinds from "./coverage/postgres.json" with { type: "json" };
+import clickhouseKinds from "./coverage/clickhouse.json" with { type: "json" };
+import postgresCommands from "./coverage/postgres-commands.json" with { type: "json" };
+import clickhouseCommands from "./coverage/clickhouse-commands.json" with { type: "json" };
+
+// ── Object kinds ───────────────────────────────────────────────────────
+
+/** `declared`: a tag holds it. `refused`: import names it and stops. `out-of-scope`: the environment's, never imported. */
+export type KindStatus = "declared" | "refused" | "out-of-scope";
+
+/** One row of a dialect's coverage table: a `CREATE` command, or one form of it. */
+export interface KindRow {
+  /** The command as the server's reference names it: `CREATE TYPE`. */
+  command: string;
+  /** The form of the command the row is about, when the command has forms chant treats apart: `AS RANGE`. */
+  form?: string;
+  /**
+   * How a statement of the command is told to be this form: a regular
+   * expression, case-insensitive, over the statement with its comments and
+   * string literals taken out. The command's row without one is the rest.
+   */
+  match?: string;
+  /** The object kind, unique in the dialect, as messages name it: `range type`. */
+  kind: string;
+  status: KindStatus;
+  /** The entity type that declares it, when declared. */
+  entity?: string;
+  /** Why it is refused or out of scope. */
+  reason?: string;
+  /** Anything else a reader should know. */
+  note?: string;
+}
+
+/** Each dialect's coverage table. */
+export const KIND_COVERAGE: Record<SqlDialect, readonly KindRow[]> = {
+  postgres: postgresKinds.kinds as KindRow[],
+  clickhouse: clickhouseKinds.kinds as KindRow[],
+};
+
+/** The `CREATE` commands each pinned server has: per Postgres major, and the pinned ClickHouse release. */
+export const PINNED_COMMANDS: Record<SqlDialect, ReadonlyArray<{ version: string; commands: readonly string[] }>> = {
+  postgres: Object.values(postgresCommands.majors),
+  clickhouse: [{ version: clickhouseCommands.version, commands: clickhouseCommands.commands }],
+};
+
+/** A dialect's row for `kind`; throws for a kind the table does not have, so a probe cannot name one that is not there. */
+export function kindRow(dialect: SqlDialect, kind: string): KindRow {
+  const row = KIND_COVERAGE[dialect].find((r) => r.kind === kind);
+  if (!row) throw new Error(`no ${dialect} coverage row for the kind "${kind}" (src/coverage/${dialect}.json)`);
+  return row;
+}
+
+/**
+ * What is wrong with a dialect's coverage table, against its pinned servers'
+ * commands: a command a pinned server has and no row covers, a row for a
+ * command no pinned server has, a kind named twice, a declared row with no
+ * entity, a refused or out-of-scope row with no reason. Empty when complete.
+ */
+export function kindCoverageProblems(dialect: SqlDialect, opts: { pins?: ReadonlyArray<{ version: string; commands: readonly string[] }>; rows?: readonly KindRow[] } = {}): string[] {
+  const rows = opts.rows ?? KIND_COVERAGE[dialect];
+  const pins = opts.pins ?? PINNED_COMMANDS[dialect];
+  const problems: string[] = [];
+  const covered = new Set(rows.map((r) => r.command));
+  const listed = new Set(pins.flatMap((p) => p.commands));
+  for (const p of pins) {
+    for (const c of p.commands) if (!covered.has(c)) problems.push(`${dialect} ${p.version} has ${c}, and no row in src/coverage/${dialect}.json covers it`);
+  }
+  for (const c of covered) if (!listed.has(c)) problems.push(`src/coverage/${dialect}.json has a row for ${c}, which no pinned ${dialect} server has`);
+  const seen = new Set<string>();
+  for (const r of rows) {
+    if (seen.has(r.kind)) problems.push(`the kind "${r.kind}" has two rows`);
+    seen.add(r.kind);
+    if (!["declared", "refused", "out-of-scope"].includes(r.status)) problems.push(`${r.kind}: status "${r.status}" is not declared, refused or out-of-scope`);
+    if (r.status === "declared" && !r.entity) problems.push(`${r.kind} is declared, and names no entity type`);
+    if (r.status !== "declared" && !r.reason) problems.push(`${r.kind} is ${r.status}, and gives no reason`);
+  }
+  return problems;
+}
+
+/** A statement's words, upper case, with comments and string literals (quoted and dollar-quoted) taken out. */
+function bareStatement(sql: string): string {
+  return sql
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)?\$[\s\S]*?\$\1\$/g, " '' ")
+    .replace(/'(?:[^'\\]|''|\\.)*'/g, " '' ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toUpperCase();
+}
+
+/** Words a `CREATE` can carry before the command's own: `CREATE OR REPLACE TRUSTED PROCEDURAL LANGUAGE`, `CREATE DEFAULT CONVERSION`. */
+const MODIFIERS = new Set(["OR", "REPLACE", "TRUSTED", "PROCEDURAL", "DEFAULT", "UNIQUE", "UNLOGGED", "RECURSIVE", "CONSTRAINT", "GLOBAL", "LOCAL", "TEMP", "TEMPORARY"]);
+
+/**
+ * The coverage row a `CREATE` statement is of, by its command (the longest
+ * that its words start with) and, among the command's forms, the first whose
+ * `match` it matches; undefined for a statement no row covers.
+ */
+export function statementKind(dialect: SqlDialect, sql: string): KindRow | undefined {
+  const bare = bareStatement(sql);
+  const words = bare.split(/[\s(]+/);
+  if (words[0] !== "CREATE") return undefined;
+  const rest = words.slice(1).filter((w, i, all) => !MODIFIERS.has(w) || all.slice(0, i).some((x) => !MODIFIERS.has(x)));
+  const rows = KIND_COVERAGE[dialect];
+  let command: string | undefined;
+  for (const r of rows) {
+    const cmd = r.command.split(" ").slice(1);
+    if (cmd.every((w, i) => rest[i] === w) && (!command || cmd.length > command.split(" ").length - 1)) command = r.command;
+  }
+  if (!command) return undefined;
+  const forms = rows.filter((r) => r.command === command);
+  return forms.find((r) => r.match !== undefined && new RegExp(r.match, "i").test(bare)) ?? forms.find((r) => r.match === undefined);
+}
+
+/** Whether the commands file was written for the pinned servers: a list for each pinned version, and for no other. */
+export function pinnedCommandsCurrent(dialect: SqlDialect): string[] {
+  const have = PINNED_COMMANDS[dialect].map((p) => p.version);
+  const want = dialect === "postgres" ? POSTGRES_PINS.map((p) => p.version) : [CLICKHOUSE_VERSION];
+  const run = `run npx tsx scripts/sql-create-commands.ts ${dialect}`;
+  return [
+    ...want.filter((v) => !have.includes(v)).map((v) => `${dialect} ${v} is pinned, and src/coverage/${dialect}-commands.json has no command list for it: ${run}`),
+    ...have.filter((v) => !want.includes(v)).map((v) => `src/coverage/${dialect}-commands.json lists ${dialect} ${v}, which is no longer pinned: ${run}`),
+  ];
+}
+
+// ── ClickHouse argument typing ─────────────────────────────────────────
 
 export interface CoverageSection {
   section: string;

package/src/files/clickhouse.ts

@@ -20,7 +20,7 @@ import { isAccessStatement, parseAccess, type AccessNode } from "../clickhouse/a
 import type { Token } from "../clickhouse/tokens";
 import { CLICKHOUSE_TAG_OF } from "../clickhouse/import/generator";
 import { describeStatement, type ImportedObject } from "../clickhouse/import/ir";
-import { fileUnparsed, firstLine, lineAt, quoteBare, splitTokens, tokensText, type FileLine, type ReadOptions } from "./common";
+import { fileUnparsed, firstLine, lineAt, quoteBare, splitTokens, tokensText, undeclarableStatement, type FileLine, type ReadOptions } from "./common";
 import { templateSafe, templateStrings } from "./postgres";
 
 type Tag = (strings: TemplateStringsArray, ...values: unknown[]) => Declarable;
@@ -87,6 +87,11 @@ export function readClickHouse(ddl: string, options: ReadOptions, problems: stri
   for (const stmt of splitTokens(tokenizeText(ddl, 0), isTrivia)) {
     let sql = tokensText(stmt);
     const line = lineAt(ddl, stmt[0]!.start);
+    const undeclarable = undeclarableStatement("clickhouse", sql);
+    if (undeclarable) {
+      (options.undeclarable ?? problems).push(undeclarable);
+      continue;
+    }
     if (isAccessStatement(sql)) {
       try {
         const read = readAccess(sql, options);

package/src/files/common.ts

@@ -2,6 +2,8 @@
 
 import type { Token } from "../core/tokens";
 import type { UnknownClause } from "../core/cursor";
+import type { SqlDialect } from "../dialects";
+import { statementKind } from "../coverage";
 
 export interface ReadOptions {
   /** Names the DDL in errors: a file's path, a command. */
@@ -11,6 +13,22 @@ export interface ReadOptions {
    * unqualified, as an ORM does when the schema comes from its connection.
    */
   schema?: string;
+  /**
+   * Where a statement of a kind chant cannot declare goes (#3911), as a line
+   * naming it, instead of among the problems: `chant import
+   * --parser-option skipUndeclarable` lists them as warnings.
+   */
+  undeclarable?: string[];
+}
+
+/**
+ * A `CREATE` of a kind the coverage table does not mark declared, as the line
+ * that names it with why, or undefined for any other statement.
+ */
+export function undeclarableStatement(dialect: SqlDialect, sql: string): string | undefined {
+  const row = statementKind(dialect, sql);
+  if (!row || row.status === "declared") return undefined;
+  return `${row.kind}: chant cannot declare it (${row.reason ?? row.status}): ${firstLine(sql)}`;
 }
 
 /** A file of DDL with statements that declare nothing chant can hold: each problem names its statement. */

package/src/files/postgres.ts

@@ -26,7 +26,7 @@ import * as tags from "../postgres/entities";
 import { POSTGRES_ENTITY_TYPES, type PostgresEntityType } from "../postgres/entity-types";
 import { POSTGRES_TAG_OF } from "../postgres/import/generator";
 import type { ImportedPgObject } from "../postgres/import/ir";
-import { fileUnparsed, firstLine, lineAt, quoteBare, splitTokens, tokensText, type FileLine, type ReadOptions } from "./common";
+import { fileUnparsed, firstLine, lineAt, quoteBare, splitTokens, tokensText, undeclarableStatement, type FileLine, type ReadOptions } from "./common";
 
 type Tag = (strings: TemplateStringsArray, ...values: unknown[]) => Declarable;
 
@@ -91,6 +91,11 @@ export function readPostgres(ddl: string, options: ReadOptions, problems: string
       problems.push(`not a statement that declares an object: ${firstLine(sql)}`);
       continue;
     }
+    const undeclarable = undeclarableStatement("postgres", sql);
+    if (undeclarable) {
+      (options.undeclarable ?? problems).push(undeclarable);
+      continue;
+    }
     try {
       const tokens = tokenizeText(sql, 0);
       for (const node of parseStatements(tokens)) parsed.push({ tokens, node, line: lineAt(ddl, stmt[0]!.start) });

package/src/import-parser.ts

@@ -9,7 +9,9 @@
  * anything else is ClickHouse.
  *
  * A statement that declares nothing, or does not parse, is an error naming
- * it (`./sql-files.ts`); none is left out. A clause the parser does not know
+ * it (`./sql-files.ts`); none is left out. So is a `CREATE` of a kind chant
+ * cannot declare (#3911, `./coverage.ts`): `--parser-option
+ * skipUndeclarable` imports the rest and lists those as warnings. A clause the parser does not know
  * (#3872) is kept in the template as written.
  */
 
@@ -52,13 +54,19 @@ export function dialectOption(options: ParserOptions | undefined): SqlDialect |
 }
 
 export class SqlFileParser implements TemplateParser {
-  constructor(private readonly dialect?: SqlDialect) {}
+  constructor(
+    private readonly dialect?: SqlDialect,
+    private readonly options: { skipUndeclarable?: boolean } = {},
+  ) {}
 
   parse(content: string): TemplateIR {
     const dialect = this.dialect ?? guessDialect(content);
     const problems: string[] = [];
-    const ir = dialect === "postgres" ? pgObjectsToIR(readPostgres(content, { origin: "the DDL" }, problems)) : chObjectsToIR(readClickHouse(content, { origin: "the DDL" }, problems));
+    const skipped: string[] = [];
+    const read = { origin: "the DDL", ...(this.options.skipUndeclarable ? { undeclarable: skipped } : {}) };
+    const ir = dialect === "postgres" ? pgObjectsToIR(readPostgres(content, read, problems)) : chObjectsToIR(readClickHouse(content, read, problems));
     if (problems.length > 0) throw new SqlFileError(`the ${dialect === "postgres" ? "Postgres" : "ClickHouse"} DDL`, problems);
-    return ir;
+    if (skipped.length === 0) return ir;
+    return { ...ir, warnings: [...(ir.warnings ?? []), ...skipped.map((s) => `left out (skipUndeclarable): ${s}`)] };
   }
 }

package/src/plugin.ts

@@ -159,7 +159,7 @@ export const sqlPlugin: LexiconPlugin = {
 
   /** `chant import schema.sql`: a file of Postgres or ClickHouse DDL (`./import-parser.ts`). */
   templateParser(options) {
-    return new SqlFileParser(dialectOption(options));
+    return new SqlFileParser(dialectOption(options), { skipUndeclarable: options?.skipUndeclarable === true });
   },
 
   parserOptions() {
@@ -169,6 +169,11 @@ export const sqlPlugin: LexiconPlugin = {
         type: "string" as const,
         description: "the DDL's dialect, clickhouse or postgres; read off its statements when omitted",
       },
+      {
+        name: "skipUndeclarable",
+        type: "boolean" as const,
+        description: "import the rest of the file, and list each CREATE of a kind chant cannot declare (an aggregate, a cast, a quota) as a warning instead of failing",
+      },
     ];
   },
 

package/src/postgres/import/live-export.ts

@@ -17,6 +17,12 @@
  *   declarations: the GRANT and REVOKE statements that take a new object's
  *   privileges to what the server holds. Roles are the environment's and are
  *   not imported.
+ * - An object of a kind no declaration holds (an aggregate, a cast, a
+ *   composite type, an event trigger, ...; `../live/undeclarable.ts`) fails
+ *   the import, which names every one of them (#3911). `skipUndeclarable`
+ *   (`--skip-undeclarable`) imports the rest and lists them as warnings. A
+ *   selector or `owned` import asks for objects chant can hold, so it does
+ *   not look.
  */
 
 import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
@@ -25,6 +31,9 @@ import { markProviderOwned, readLiveSchema } from "../live/catalog";
 import { objectsToIR, type ImportedPgObject } from "./ir";
 import { isChantManaged } from "../../core/ownership";
 import { importedAccess } from "../access/import";
+import { readUndeclarable } from "../live/undeclarable";
+import { describeUndeclarable, refuseUndeclarable, type UndeclarableObject } from "../../core/undeclarable";
+import { isProviderOwned, providerData } from "../providers";
 
 export interface ExportOptions extends Omit<BindOptions, "environment"> {
   environment: string;
@@ -33,20 +42,33 @@ export interface ExportOptions extends Omit<BindOptions, "environment"> {
   selector?: ResourceSelector;
   owned?: boolean;
   verbatim?: boolean;
+  /** Import what can be declared, and list the objects of kinds no declaration holds as warnings instead of failing (#3911). */
+  skipUndeclarable?: boolean;
 }
 
 export async function exportResources(options: ExportOptions): Promise<ExportedTemplate> {
   const { target, client } = await bindPostgres(options);
   let live;
   let access: ImportedPgObject[] = [];
+  // A selector or an owned import asks only for what chant can hold.
+  const checked = !options.selector && !options.owned;
+  let undeclarable: { objects: UndeclarableObject[]; unread: string[] } = { objects: [], unread: [] };
   try {
+    if (checked) undeclarable = await readUndeclarable(client, { schemas: target.schemas });
     live = markProviderOwned(await readLiveSchema(client, { schemas: target.schemas, access: target.access === true }), target.provider);
     // Where the profile manages access, the privileges on what is imported, and the default privileges, as grant declarations.
     if (target.access === true && !options.selector) access = await importedAccess(client, live.filter((o) => !o.foreign && !o.unsupported && (!options.owned || isChantManaged(o.comment))), target.schemas);
   } finally {
     await client.end();
   }
-  const warnings: string[] = [];
+  const warnings: string[] = undeclarable.unread.map((u) => `the server was not checked for objects of one kind chant cannot declare, so some may be left out: ${u}`);
+  // A managed provider's own (in its schemas, or owned by its roles) is the provider's, as for the objects read below.
+  const provider = target.provider;
+  const providers = (o: UndeclarableObject) =>
+    provider !== undefined &&
+    ((o.schema !== undefined && isProviderOwned(provider, { kind: "schema", name: o.schema })) || (o.owner !== undefined && isProviderOwned(provider, { kind: "role", name: o.owner })));
+  for (const o of undeclarable.objects.filter(providers)) warnings.push(`${describeUndeclarable(o)} is kept by ${providerData(provider!).label}; left out`);
+  refuseUndeclarable("postgres", undeclarable.objects.filter((o) => !providers(o)), options.skipUndeclarable, warnings);
   const objects: ImportedPgObject[] = [];
   for (const o of live) {
     if (options.owned && !isChantManaged(o.comment)) continue;
@@ -54,7 +76,8 @@ export async function exportResources(options: ExportOptions): Promise<ExportedT
     const name = options.selector?.name;
     if (name !== undefined && name !== o.name && name !== `${o.schema}.${o.name}`) continue;
     if (o.unsupported) {
-      warnings.push(`${o.schema ? `${o.schema}.` : ""}${o.name}${o.signature ?? ""} is left out: ${o.unsupported}`);
+      // When checked, it is among the undeclarable objects above.
+      if (!checked) warnings.push(`${o.schema ? `${o.schema}.` : ""}${o.name}${o.signature ?? ""} is left out: ${o.unsupported}`);
       continue;
     }
     if (o.foreign) {

package/src/postgres/live/catalog.ts

@@ -18,7 +18,7 @@
  * - objects an extension owns (`pg_depend.deptype = 'e'`): the extension
  *   declares them, so the extension is what is imported;
  * - `plpgsql`, installed in every database;
- * - aggregates, and a trigger the server makes for itself (a foreign key's)
+ * - a trigger the server makes for itself (a foreign key's)
  *   or clones onto a partition from its parent's;
  * - a routine with a SQL-standard body (`RETURN`, `BEGIN ATOMIC`): read, but
  *   marked `unsupported`, since the server prints it rewritten and a
@@ -32,6 +32,10 @@
  *   progress (`../migrate/names.ts`, `../migrate/carry.ts`), so a table reads
  *   as it was before the migration until its switch, and as declared after it.
  *
+ * Objects of the kinds no declaration holds (aggregates, casts, collations,
+ * composite and range types, event triggers, ...) are not read here: import
+ * finds them with `./undeclarable.ts` and refuses them by name (#3911).
+ *
  * Objects another tool owns, an ORM's or a migration runner's revision table
  * ({@link FOREIGN_TABLES}), are read and marked with the tool, so import
  * leaves them out with a warning and observation reports them foreign, never
@@ -112,7 +116,7 @@ const commentOn = (what: string, comment: unknown): string[] => {
 };
 
 /** The scope as a predicate on a schema name column, with its parameter. */
-function scopeSql(column: string, scope: SchemaScope): { sql: string; params: unknown[] } {
+export function scopeSql(column: string, scope: SchemaScope): { sql: string; params: unknown[] } {
   if (scope.schemas) return { sql: `${column} = ANY($1::text[])`, params: [[...scope.schemas]] };
   return {
     sql: `${column} NOT IN ('pg_catalog', 'information_schema', 'pg_toast') AND ${column} NOT LIKE 'pg\\_temp\\_%' AND ${column} NOT LIKE 'pg\\_toast\\_temp\\_%'`,
@@ -121,7 +125,7 @@ function scopeSql(column: string, scope: SchemaScope): { sql: string; params: un
 }
 
 /** `NOT <object is owned by an extension>`, for an object of catalog `catalog` with oid column `oid`. */
-const notExtensionOwned = (catalog: string, oid: string): string =>
+export const notExtensionOwned = (catalog: string, oid: string): string =>
   `NOT EXISTS (SELECT 1 FROM pg_catalog.pg_depend d WHERE d.classid = 'pg_catalog.${catalog}'::pg_catalog.regclass AND d.objid = ${oid} AND d.deptype = 'e')`;
 
 /** A collation name as a clause, `pg_catalog` names unqualified. */

package/src/postgres/live/undeclarable.e2e.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Import against a real Postgres server never leaves an object out without a
+ * word (#3911): a database holding a composite type, an aggregate, a
+ * collation, a cast and an event trigger beside a table fails the import,
+ * which names all five; with `skipUndeclarable` the table is imported and
+ * the five are warnings. What an extension brings (hstore's casts and
+ * operators) is the extension's, and is not refused.
+ *
+ * Needs Docker; skips cleanly without it. One throwaway `postgres` container
+ * at the pin, removed afterwards even on failure.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../testing/server";
+import { exportResources } from "../import/live-export";
+import { UndeclarableObjectsError } from "../../core/undeclarable";
+
+const enabled = await dockerAvailable();
+let server: TestPostgres | undefined;
+
+const SEED = `
+CREATE EXTENSION hstore WITH SCHEMA public;
+CREATE SCHEMA app;
+CREATE TABLE app.users (id bigint PRIMARY KEY, name text);
+CREATE TYPE app.pair AS (a integer, b text);
+CREATE FUNCTION app.add2(integer, integer) RETURNS integer LANGUAGE sql AS $$ SELECT $1 + $2 $$;
+CREATE AGGREGATE app.total(integer) (sfunc = app.add2, stype = integer, initcond = '0');
+CREATE COLLATION app.ci (provider = icu, locale = 'und-u-ks-level2', deterministic = false);
+CREATE FUNCTION app.pair_text(app.pair) RETURNS text LANGUAGE sql AS $$ SELECT ($1).b $$;
+CREATE CAST (app.pair AS text) WITH FUNCTION app.pair_text(app.pair);
+CREATE FUNCTION app.on_ddl() RETURNS event_trigger LANGUAGE plpgsql AS $$ BEGIN END $$;
+CREATE EVENT TRIGGER audit_ddl ON ddl_command_end EXECUTE FUNCTION app.on_ddl();
+`;
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startTestPostgres();
+  const admin = await server.connect();
+  await admin.query("CREATE DATABASE source");
+  await admin.end();
+  const source = await server.connect("source");
+  await source.query(SEED);
+  await source.end();
+}, 600_000);
+
+afterAll(async () => {
+  await server?.stop();
+});
+
+const profile = () => ({
+  config: { sql: { profiles: { src: { url: server!.endpoint("source").url, password: { env: "PG_UD_PASSWORD" } } } } },
+  env: { PG_UD_PASSWORD: server!.endpoint("source").password },
+});
+
+const NAMED = [
+  "aggregate app.total(integer)",
+  "cast (app.pair AS text)",
+  "collation app.ci",
+  "event trigger audit_ddl",
+  "composite type app.pair",
+];
+
+describe.skipIf(!enabled)("importing a database with objects chant cannot declare", () => {
+  test("fails, naming every one of them", async () => {
+    const err = await exportResources({ environment: "src", ...profile() }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UndeclarableObjectsError);
+    const objects = (err as UndeclarableObjectsError).objects.map((o) => `${o.kind} ${o.schema ? `${o.schema}.` : ""}${o.name}`);
+    expect([...objects].sort()).toEqual([...NAMED].sort());
+    for (const line of NAMED) expect((err as Error).message).toContain(`  - ${line}\n`);
+  }, 120_000);
+
+  test("with skipUndeclarable, imports the rest and lists them as warnings", async () => {
+    const ir = await exportResources({ environment: "src", skipUndeclarable: true, ...profile() });
+    expect(ir.resources.map((r) => r.properties.name)).toEqual(expect.arrayContaining(["users", "hstore", "add2", "pair_text", "on_ddl"]));
+    const left = (ir.warnings ?? []).filter((w) => w.includes("is left out (--skip-undeclarable)"));
+    expect(left.map((w) => w.split(" is left out")[0]).sort()).toEqual([...NAMED].sort());
+  }, 120_000);
+});

package/src/postgres/live/undeclarable.ts

@@ -0,0 +1,141 @@
+/**
+ * The objects in a live Postgres database of the kinds no declaration holds
+ * (#3911), found so import can refuse them by name instead of leaving them
+ * out (`../../core/undeclarable.ts`).
+ *
+ * One catalog query per kind the coverage table marks refused
+ * (`../../coverage/postgres.json`), keyed by the row's `kind`. A kind whose
+ * row is flipped to declared is no longer asked about: its objects are then
+ * the catalog reader's (`./catalog.ts`) to read.
+ *
+ * Left out, as the reader leaves them out: the server's own schemas, objects
+ * an extension owns (`pg_depend.deptype = 'e'`; the extension is declared),
+ * the objects `initdb` makes, whose oids are below 16384
+ * (`FirstNormalObjectId`), and an object that is part of another
+ * (`deptype = 'i'`: the casts a range type makes for itself). An object in a
+ * schema is looked for in the schemas in scope; one that belongs to the whole
+ * database (a cast, an event trigger, a publication, a foreign data wrapper)
+ * is always looked for.
+ */
+
+import type { PostgresClient } from "./client";
+import { notExtensionOwned, scopeSql, type SchemaScope } from "./catalog";
+import { KIND_COVERAGE } from "../../coverage";
+import type { UndeclarableObject } from "../../core/undeclarable";
+
+/** `FirstNormalObjectId`: every oid below it is the server's own. */
+const FIRST_USER_OID = 16384;
+
+interface Probe {
+  /**
+   * A query returning `schema` (NULL for a database-wide object), `name`, and
+   * for a database-wide object the role that owns it (so a managed
+   * provider's own can be told apart); `scope` is the predicate on `n.nspname`.
+   */
+  sql(scope: string): string;
+}
+
+const C = 'COLLATE "C"';
+
+/** Not part of another object (`pg_depend.deptype = 'i'`): the multirange cast a range type makes for itself is the range type's. */
+const notInternal = (catalog: string, oid: string) =>
+  `NOT EXISTS (SELECT 1 FROM pg_catalog.pg_depend d WHERE d.classid = 'pg_catalog.${catalog}'::pg_catalog.regclass AND d.objid = ${oid} AND d.deptype = 'i')`;
+const ns = (alias: string, column: string) => `JOIN pg_catalog.pg_namespace ${alias} ON ${alias}.oid = ${column}`;
+const args = (oid: string) => `'(' || pg_catalog.replace(pg_catalog.oidvectortypes(${oid}), ', ', ',') || ')'`;
+
+/** A probe for objects of a catalog in a schema, the catalog aliased `x`; `name` is the name expression. */
+const inSchema = (catalog: string, nsColumn: string, name: string, where = "TRUE"): Probe => ({
+  sql: (scope) =>
+    `SELECT n.nspname AS schema, ${name} AS name, NULL::text AS owner FROM pg_catalog.${catalog} x ${ns("n", `x.${nsColumn}`)}
+     WHERE ${where} AND ${scope} AND x.oid >= ${FIRST_USER_OID} AND ${notExtensionOwned(catalog, "x.oid")} AND ${notInternal(catalog, "x.oid")}`,
+});
+
+/** A probe for objects that belong to the database, not a schema. */
+const databaseWide = (catalog: string, name: string, owner?: string): Probe => ({
+  sql: () =>
+    `SELECT NULL::text AS schema, ${name} AS name, ${owner ? `pg_catalog.pg_get_userbyid(x.${owner})` : "NULL::text"} AS owner FROM pg_catalog.${catalog} x
+     WHERE x.oid >= ${FIRST_USER_OID} AND ${notExtensionOwned(catalog, "x.oid")} AND ${notInternal(catalog, "x.oid")}`,
+});
+
+/** The pg_type rows of one `typtype`. */
+const type = (where: string) => inSchema("pg_type", "typnamespace", "x.typname", where);
+
+export const POSTGRES_PROBES: Readonly<Record<string, Probe>> = {
+  "access method": databaseWide("pg_am", "x.amname"),
+  aggregate: inSchema("pg_proc", "pronamespace", `x.proname || ${args("x.proargtypes")}`, "x.prokind = 'a'"),
+  "routine with a SQL-standard body": inSchema("pg_proc", "pronamespace", `x.proname || ${args("x.proargtypes")}`, "x.prokind IN ('f', 'p', 'w') AND x.prosqlbody IS NOT NULL"),
+  cast: databaseWide("pg_cast", "'(' || pg_catalog.format_type(x.castsource, NULL) || ' AS ' || pg_catalog.format_type(x.casttarget, NULL) || ')'"),
+  collation: inSchema("pg_collation", "collnamespace", "x.collname"),
+  conversion: inSchema("pg_conversion", "connamespace", "x.conname"),
+  "event trigger": databaseWide("pg_event_trigger", "x.evtname", "evtowner"),
+  "foreign data wrapper": databaseWide("pg_foreign_data_wrapper", "x.fdwname", "fdwowner"),
+  "foreign server": databaseWide("pg_foreign_server", "x.srvname", "srvowner"),
+  "user mapping": {
+    // pg_user_mapping is the superuser's to read; the view shows every mapping without its options.
+    sql: () =>
+      `SELECT NULL::text AS schema, 'for ' || x.usename || ' on server ' || x.srvname AS name, pg_catalog.pg_get_userbyid(s.srvowner) AS owner FROM pg_catalog.pg_user_mappings x
+       JOIN pg_catalog.pg_foreign_server s ON s.oid = x.srvid
+       WHERE ${notExtensionOwned("pg_foreign_server", "s.oid")}`,
+  },
+  "foreign table": inSchema("pg_class", "relnamespace", "x.relname", "x.relkind = 'f'"),
+  "procedural language": databaseWide("pg_language", "x.lanname", "lanowner"),
+  operator: inSchema("pg_operator", "oprnamespace", "x.oprname || '(' || pg_catalog.format_type(x.oprleft, NULL) || ',' || pg_catalog.format_type(x.oprright, NULL) || ')'"),
+  "operator class": inSchema("pg_opclass", "opcnamespace", "x.opcname || ' USING ' || (SELECT a.amname FROM pg_catalog.pg_am a WHERE a.oid = x.opcmethod)"),
+  // A family CREATE OPERATOR CLASS made for itself, named as its class, is the class's.
+  "operator family": inSchema(
+    "pg_opfamily",
+    "opfnamespace",
+    "x.opfname || ' USING ' || (SELECT a.amname FROM pg_catalog.pg_am a WHERE a.oid = x.opfmethod)",
+    "NOT EXISTS (SELECT 1 FROM pg_catalog.pg_opclass c WHERE c.opcfamily = x.oid AND c.opcname = x.opfname AND c.opcnamespace = x.opfnamespace)",
+  ),
+  publication: databaseWide("pg_publication", "x.pubname", "pubowner"),
+  subscription: {
+    sql: () =>
+      `SELECT NULL::text AS schema, x.subname AS name, pg_catalog.pg_get_userbyid(x.subowner) AS owner FROM pg_catalog.pg_subscription x
+       WHERE x.subdbid = (SELECT d.oid FROM pg_catalog.pg_database d WHERE d.datname = pg_catalog.current_database())`,
+  },
+  rule: {
+    sql: (scope) =>
+      `SELECT n.nspname AS schema, r.rulename || ' ON ' || c.relname AS name, NULL::text AS owner
+       FROM pg_catalog.pg_rewrite r JOIN pg_catalog.pg_class c ON c.oid = r.ev_class ${ns("n", "c.relnamespace")}
+       WHERE r.rulename <> '_RETURN' AND ${scope} AND ${notExtensionOwned("pg_class", "c.oid")}`,
+  },
+  "extended statistics": inSchema("pg_statistic_ext", "stxnamespace", "x.stxname"),
+  "text search configuration": inSchema("pg_ts_config", "cfgnamespace", "x.cfgname"),
+  "text search dictionary": inSchema("pg_ts_dict", "dictnamespace", "x.dictname"),
+  "text search parser": inSchema("pg_ts_parser", "prsnamespace", "x.prsname"),
+  "text search template": inSchema("pg_ts_template", "tmplnamespace", "x.tmplname"),
+  transform: databaseWide(
+    "pg_transform",
+    "'FOR ' || pg_catalog.format_type(x.trftype, NULL) || ' LANGUAGE ' || (SELECT l.lanname FROM pg_catalog.pg_language l WHERE l.oid = x.trflang)",
+  ),
+  "composite type": type("x.typtype = 'c' AND EXISTS (SELECT 1 FROM pg_catalog.pg_class c WHERE c.oid = x.typrelid AND c.relkind = 'c')"),
+  "range type": type("x.typtype = 'r'"),
+  // A base type, or a shell; not the array type the server makes beside every type.
+  "base type": type("x.typtype IN ('b', 'p') AND NOT EXISTS (SELECT 1 FROM pg_catalog.pg_type e WHERE e.typarray = x.oid)"),
+};
+
+/**
+ * Every object in scope of a kind the coverage table refuses, kind by kind
+ * in the table's order, each by schema then name. A kind the session may not
+ * read (a role without the privilege) is a problem in `unread`, not a pass.
+ */
+export async function readUndeclarable(client: PostgresClient, scope: SchemaScope = {}): Promise<{ objects: UndeclarableObject[]; unread: string[] }> {
+  const s = scopeSql("n.nspname", scope);
+  const objects: UndeclarableObject[] = [];
+  const unread: string[] = [];
+  for (const row of KIND_COVERAGE.postgres) {
+    if (row.status !== "refused") continue;
+    const probe = POSTGRES_PROBES[row.kind];
+    if (!probe) throw new Error(`no catalog query finds a Postgres ${row.kind} (src/postgres/live/undeclarable.ts)`);
+    // The comment names the kind, in the server's log and to a test's fake client.
+    const sql = `/* chant undeclarable: ${row.kind} */ SELECT q.schema, q.name, q.owner FROM (${probe.sql(s.sql)}) q ORDER BY q.schema ${C} NULLS FIRST, q.name ${C}`;
+    try {
+      const rows = await client.query<{ schema: string | null; name: string; owner: string | null }>(sql, sql.includes("$1") ? s.params : []);
+      for (const r of rows) objects.push({ kind: row.kind, ...(r.schema ? { schema: r.schema } : {}), name: r.name, ...(r.owner ? { owner: r.owner } : {}) });
+    } catch (err) {
+      unread.push(`${row.kind}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return { objects, unread };
+}

package/src/postgres/testing/fake-client.ts

@@ -11,6 +11,8 @@ export interface FakeCatalog {
   tables?: Array<{ schema: string; name: string; comment?: string; columns?: Array<{ name: string; type: string; notnull?: boolean; dflt?: string }> }>;
   views?: Array<{ schema: string; name: string; def: string; materialized?: boolean; comment?: string }>;
   indexes?: Array<{ schema: string; name: string; table: string; def: string }>;
+  /** What the undeclarable-kind probes (`../live/undeclarable.ts`) find, by the coverage table's kind. Default: nothing. */
+  undeclarable?: Array<{ kind: string; schema?: string; name: string }>;
 }
 
 export function fakeClient(catalog: FakeCatalog, log: string[] = []): PostgresClient {
@@ -20,6 +22,9 @@ export function fakeClient(catalog: FakeCatalog, log: string[] = []): PostgresCl
     async query<T>(sql: string): Promise<T[]> {
       log.push(sql);
       const rows = (r: unknown[]) => r as T[];
+      // A probe for one undeclarable kind (`../live/undeclarable.ts`), which its comment names.
+      const probe = /^\/\* chant undeclarable: (.+?) \*\//.exec(sql);
+      if (probe) return rows((catalog.undeclarable ?? []).filter((u) => u.kind === probe[1]).map((u) => ({ schema: u.schema ?? null, name: u.name, owner: null })));
       if (sql.includes("FROM pg_catalog.pg_namespace n WHERE")) return rows((catalog.schemas ?? []).map((s, i) => ({ oid: String(100 + i), name: s.name, comment: s.comment ?? null })));
       if (sql.includes("c.relkind IN ('r', 'p')")) {
         return rows(tables.map((t) => ({ oid: t.oid, schema: t.schema, name: t.name, kind: "r", persistence: "p", ispartition: false, typed: false, partkey: null, bound: null, parents: [], reloptions: null, am: "heap", tablespace: null, comment: t.comment ?? null })));