neonctl 2.22.0 → 2.23.0

package/psql/describe/formatters.js

@@ -0,0 +1,1277 @@
+/**
+ * Rendering for psql's `\d*` describe commands.
+ *
+ * This module owns the runtime side of WP-20: take the SQL templates
+ * from {@link './queries.js'} (WP-19), run them against a real
+ * {@link Connection}, and render the result via the aligned printer
+ * for tabular sections plus free-form text for "footer" sections
+ * (`Indexes:`, `Foreign-key constraints:`, etc.) the way upstream
+ * `describe.c` does.
+ *
+ * Scope of the initial implementation:
+ *
+ *  - {@link runListQuery} runs an arbitrary {@link DescribeQuery}
+ *    (typically one of `listTables`, `describeFunctions`, etc.) and
+ *    prints its result with the aligned printer. Title is taken from
+ *    the query's `description`. This covers every `\d*` *list* command.
+ *
+ *  - {@link describeOneTableDetails} fans out from the lookup query
+ *    `describeTableDetails` into the per-relation detail render: a
+ *    columns table at the top, followed by index / constraint / trigger
+ *    sections as appropriate for the relkind. This is the bulk of
+ *    upstream's `describeOneTableDetails()` from `describe.c`. We
+ *    implement the *common* table layout (regular tables, views,
+ *    materialized views, partitioned tables and indexes) — exotic
+ *    sections (foreign-table options, replica identity, RLS policies,
+ *    inheritance pretty-printing) are stubbed with the SQL queries in
+ *    place but only minimal rendering. The output is sufficient for
+ *    real-world `\d <name>` usage; gaps are flagged with TODO comments.
+ *
+ *  - {@link describeOneSequence}, {@link describeOneFunctionDetails}
+ *    and {@link describeOneViewDetails} are thinner: a single query +
+ *    one section of output each.
+ *
+ * Pattern conditions: each list query has an `AND true /<!---->* TODO(WP-20)…`
+ * placeholder we replace via {@link applyPattern} before sending the
+ * query down the wire. See {@link processSQLNamePattern} for the
+ * pattern parser.
+ */
+import { processSQLNamePattern } from './processNamePattern.js';
+import { alignedPrinter } from '../print/aligned.js';
+import { asciidocPrinter } from '../print/asciidoc.js';
+import { csvPrinter } from '../print/csv.js';
+import { htmlPrinter } from '../print/html.js';
+import { jsonPrinter } from '../print/json.js';
+import { latexLongtablePrinter, latexPrinter } from '../print/latex.js';
+import { troffMsPrinter } from '../print/troff.js';
+import { unalignedPrinter } from '../print/unaligned.js';
+import { fetchForeignTableInfo, fetchInheritedBy, fetchInherits, fetchPartitionKey, fetchPartitionOf, fetchPerColumnFdwOptions, fetchPolicies, fetchStatisticsObjects, fetchTableInfo, fetchTablePublications, fetchTableSubscriptions, } from './queries.js';
+import { applyPattern } from './processNamePattern.js';
+import { fetchNotNullConstraints } from './queries.js';
+import { serverAtLeast, PG_14 } from './versionGate.js';
+/**
+ * Pick the printer for the active output format. Mirrors `pickPrinter`
+ * in `core/common.ts`, but operates off `PrintQueryOpts.topt.format`
+ * since formatters don't have access to the full `PsqlSettings`. The
+ * aligned printer covers both `aligned` and `wrapped`; everything else
+ * routes to its dedicated module so `\d <obj>` honours the user's
+ * `\pset format` choice (asciidoc/csv/html/latex/etc.) the same way
+ * regular SELECTs do.
+ */
+const pickPrinterForFormat = (opts) => {
+    switch (opts.topt.format) {
+        case 'aligned':
+        case 'wrapped':
+            return alignedPrinter;
+        case 'unaligned':
+            return unalignedPrinter;
+        case 'csv':
+            return csvPrinter;
+        case 'json':
+            return jsonPrinter;
+        case 'html':
+            return htmlPrinter;
+        case 'asciidoc':
+            return asciidocPrinter;
+        case 'latex':
+            return latexPrinter;
+        case 'latex-longtable':
+            return latexLongtablePrinter;
+        case 'troff-ms':
+            return troffMsPrinter;
+        default:
+            return alignedPrinter;
+    }
+};
+/**
+ * Format a cell value coming back from the protocol layer. Connection
+ * decoded values arrive as strings (text mode) or null. We coerce
+ * everything to string for the printer.
+ */
+const cellToString = (v) => {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    if (Buffer.isBuffer(v))
+        return v.toString('utf-8');
+    if (typeof v === 'number' ||
+        typeof v === 'boolean' ||
+        typeof v === 'bigint') {
+        return String(v);
+    }
+    // Non-primitive fallback: encode JSON. This branch shouldn't be hit
+    // under the protocol layer (which decodes to strings) but we guard
+    // against future shape changes.
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Materialize a {@link ResultSet} into something the aligned printer
+ * can render. The printer expects `rows: unknown[][]`; we keep the
+ * shape but ensure cells are strings or null for the null-print logic.
+ */
+const coerceResultSet = (rs) => ({
+    ...rs,
+    rows: rs.rows.map((row) => row.map((c) => (c === null || c === undefined ? null : cellToString(c)))),
+});
+const makeSectionBuffer = () => {
+    let buf = '';
+    const write = (chunk) => {
+        if (typeof chunk === 'string') {
+            buf += chunk;
+        }
+        else {
+            buf += chunk.toString('utf-8');
+        }
+        return true;
+    };
+    // We only need `.write(chunk)` from the renderers; everything else on
+    // WritableStream is stubbed so the type checks pass.
+    const stub = {
+        write,
+        end: () => true,
+        on: () => stub,
+        once: () => stub,
+        emit: () => true,
+        removeListener: () => stub,
+        addListener: () => stub,
+        setDefaultEncoding: () => stub,
+        cork: () => undefined,
+        uncork: () => undefined,
+        destroy: () => stub,
+        writable: true,
+        writableEnded: false,
+        writableFinished: false,
+        toString: () => buf,
+    };
+    return stub;
+};
+/**
+ * Capture the output of a single render-section helper into a string
+ * suitable for `opts.footers`. Returns `null` when the section emitted
+ * nothing (so callers can skip pushing an empty entry). Trailing
+ * newlines are stripped: the printer re-appends a single `\n` per
+ * footer, and trailing blank lines (between sections / before next
+ * command) are emitted once by the printer's own footer-terminator.
+ */
+const captureSection = async (fn) => {
+    const buf = makeSectionBuffer();
+    await fn(buf);
+    const text = buf.toString().replace(/\n+$/, '');
+    return text === '' ? null : text;
+};
+/**
+ * Run a list-style describe query and write its result via the aligned
+ * printer. Returns the {@link ResultSet} for callers that want to
+ * inspect or post-process. Used by `\dt`, `\df`, `\dn`, etc.
+ */
+export const runListQuery = async (conn, query, patternResult, out, popt) => {
+    const { sql, params } = applyPattern(query.sql, patternResult, query.params);
+    const rs = await conn.query(sql, params);
+    const coerced = coerceResultSet(rs);
+    const titleOverride = query.description ?? popt.title;
+    const opts = {
+        ...popt,
+        title: titleOverride,
+        topt: { ...popt.topt, title: titleOverride ?? popt.topt.title },
+        footers: rs.rows.length === 0
+            ? popt.footers
+            : popt.footers !== null
+                ? popt.footers
+                : null,
+    };
+    await pickPrinterForFormat(opts).printQuery(coerced, opts, out);
+    return rs;
+};
+export const lookupRelations = async (conn, query, patternResult) => {
+    const { sql, params } = applyPattern(query.sql, patternResult, query.params);
+    const rs = await conn.query(sql, params);
+    return rs.rows.map((row) => ({
+        oid: Number(cellToString(row[0])),
+        nspname: cellToString(row[1]),
+        relname: cellToString(row[2]),
+        relkind: cellToString(row[3] ?? ''),
+    }));
+};
+/**
+ * Lookup of one specific relation by `schema.name` for the `\d <name>`
+ * dispatch. Returns the row we need to choose the right `describeOne*`
+ * renderer — including `relkind` which the upstream code reads from
+ * a separate SELECT.
+ */
+export const lookupOneRelation = async (conn, pattern) => {
+    // Route the bare-name lookup through processSQLNamePattern so the name is
+    // case-folded (unquoted → lower) and dequoted exactly like the list views:
+    // `\d Foo` matches catalog relation `foo`, `\d "MyTable"` matches the
+    // mixed-case `MyTable`, and `schema.name` splits correctly. The old raw
+    // `^(name)$` interpolation matched neither (review item #22).
+    const np = processSQLNamePattern({
+        pattern,
+        namevar: 'c.relname',
+        schemavar: 'n.nspname',
+        visibilityrule: 'pg_catalog.pg_table_is_visible(c.oid)',
+    });
+    // A db-qualified pattern (3+ dotted components → dotCount > 1) is a
+    // cross-database reference that this single-DB detail short-circuit cannot
+    // honour. Return null so the caller falls through to the LIST path, which
+    // emits upstream's "cross-database references are not implemented" /
+    // "improper qualified name (too many dotted names)" diagnostic. Without
+    // this, the detail lookup ignored the db literal and wrongly matched
+    // (e.g. `\d nonesuch.pg_catalog.pg_class` rendered the table).
+    if (np.dotCount > 1)
+        return null;
+    const conds = [
+        ...np.schemaConditions,
+        ...np.nameConditions,
+        ...np.visibilityConditions,
+    ];
+    let sql = 'SELECT c.oid, n.nspname, c.relname, c.relkind\n' +
+        'FROM pg_catalog.pg_class c\n' +
+        '     LEFT JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace\n';
+    if (conds.length > 0)
+        sql += `WHERE ${conds.join('\n  AND ')}\n`;
+    sql += 'ORDER BY 2, 3 LIMIT 1;';
+    const rs = await conn.query(sql, np.params);
+    if (rs.rows.length === 0)
+        return null;
+    const row = rs.rows[0];
+    return {
+        oid: Number(cellToString(row[0])),
+        nspname: cellToString(row[1]),
+        relname: cellToString(row[2]),
+        relkind: cellToString(row[3]),
+    };
+};
+/**
+ * Render `Table "schema.name"` (or the relkind-specific header) plus the
+ * column listing, followed by per-relkind sections (Indexes, Check
+ * constraints, Foreign-key constraints, Referenced-by, Triggers).
+ *
+ * Upstream `describeOneTableDetails()` is ~1500 LOC in `describe.c`;
+ * this implementation focuses on the headline experience and leaves
+ * exotic sections (RLS, replica identity, partition bounds rendering,
+ * pretty-printed inheritance) as TODOs. The query layer fetches the
+ * raw data so a follow-up WP can extend rendering without re-running
+ * queries.
+ */
+export const describeOneTableDetails = async (conn, oid, schema, name, relkind, verbose, out, popt, hideTableam = false, hideCompression = false) => {
+    // ----- One-shot relation info (RLS flags, replica identity,
+    //       partition flag, tablespace, access method). Fetched before
+    //       columns so the matview header can carry an "Access method:"
+    //       line and the per-column FDW options can be merged inline.
+    const relInfo = await fetchRelationInfo(conn, oid);
+    // Compose the title. Matviews with a non-default access method get
+    // a second line ("Access method: <amname>") between the header and
+    // the column table — see upstream `describeOneTableDetails`. The
+    // matview-inline form is also gated by `HIDE_TABLEAM` so the user can
+    // opt out of access-method noise.
+    const baseTitle = headerForRelkind(relkind, schema, name);
+    const title = !hideTableam && relkind === 'm' && relInfo.relam !== 0 && relInfo.amname
+        ? `${baseTitle}\nAccess method: ${relInfo.amname}`
+        : baseTitle;
+    // ----- Pre-fetch per-column FDW options (foreign tables only) so we
+    //       can fold them into each column row. Upstream renders these
+    //       inline as a trailing "FDW options: (k 'v', ...)" annotation
+    //       rather than a separate footer section.
+    const fdwOptionsByColumn = relkind === 'f'
+        ? await fetchPerColumnFdwOptionsMap(conn, oid)
+        : new Map();
+    // ----- Columns -----
+    // Verbose mode adds Storage / Stats target / Description columns to
+    // mirror upstream's `\d+`. These apply to every relkind that carries
+    // a column listing, including views and materialized views (upstream
+    // `describeOneTableDetails` gates the verbose column block on `verbose`
+    // alone, not on relkind).
+    const verboseCols = verbose &&
+        (relkind === 'r' ||
+            relkind === 'm' ||
+            relkind === 'p' ||
+            relkind === 'f' ||
+            relkind === 'v' ||
+            relkind === 'I' ||
+            relkind === 'i');
+    // Compression column (upstream `\d+`): present when the server is
+    // PG 14+, the `HIDE_TOAST_COMPRESSION` var is off, and the relkind is
+    // a regular table / partitioned table / materialized view (describe.c
+    // ~1953: `sversion >= 140000 && !hide_compression && relkind in
+    // (RELATION, PARTITIONED_TABLE, MATVIEW)`). When suppressed the column
+    // is dropped entirely — matching the conformance regress which runs
+    // with HIDE_TOAST_COMPRESSION=on.
+    const includeCompression = verboseCols &&
+        serverAtLeast(conn.serverVersion, PG_14) &&
+        !hideCompression &&
+        (relkind === 'r' || relkind === 'p' || relkind === 'm');
+    // Stats target column (upstream `\d+`): every verbose relkind EXCEPT a
+    // plain view — views have no per-column statistics targets (describe.c
+    // ~1964: RELATION, INDEX, PARTITIONED_INDEX, MATVIEW, FOREIGN_TABLE,
+    // PARTITIONED_TABLE).
+    const includeStatsTarget = verboseCols &&
+        (relkind === 'r' ||
+            relkind === 'i' ||
+            relkind === 'I' ||
+            relkind === 'm' ||
+            relkind === 'f' ||
+            relkind === 'p');
+    const colSql = 'SELECT a.attname,\n' +
+        '  pg_catalog.format_type(a.atttypid, a.atttypmod),\n' +
+        '  (SELECT pg_catalog.pg_get_expr(d.adbin, d.adrelid, true)\n' +
+        '   FROM pg_catalog.pg_attrdef d\n' +
+        '   WHERE d.adrelid = a.attrelid AND d.adnum = a.attnum AND a.atthasdef),\n' +
+        '  a.attnotnull,\n' +
+        '  (SELECT c.collname FROM pg_catalog.pg_collation c, pg_catalog.pg_type t\n' +
+        '   WHERE c.oid = a.attcollation AND t.oid = a.atttypid AND a.attcollation <> t.typcollation) AS attcollation,\n' +
+        '  a.attidentity,\n' +
+        '  a.attgenerated' +
+        (verboseCols
+            ? ',\n  CASE a.attstorage' +
+                "    WHEN 'p' THEN 'plain'" +
+                "    WHEN 'e' THEN 'external'" +
+                "    WHEN 'm' THEN 'main'" +
+                "    WHEN 'x' THEN 'extended'" +
+                "    ELSE '???'" +
+                '  END AS attstorage' +
+                (includeCompression
+                    ? ',\n  CASE a.attcompression' +
+                        "    WHEN 'p' THEN 'pglz'" +
+                        "    WHEN 'l' THEN 'lz4'" +
+                        "    WHEN '' THEN ''" +
+                        "    ELSE '???'" +
+                        '  END AS attcompression'
+                    : '') +
+                (includeStatsTarget
+                    ? ',\n  CASE WHEN a.attstattarget = -1 THEN NULL ELSE a.attstattarget::text END AS attstattarget'
+                    : '') +
+                ',\n  pg_catalog.col_description(a.attrelid, a.attnum)'
+            : '') +
+        '\nFROM pg_catalog.pg_attribute a\n' +
+        `WHERE a.attrelid = '${oid}' AND a.attnum > 0 AND NOT a.attisdropped\n` +
+        'ORDER BY a.attnum;';
+    const colsRs = await conn.query(colSql, []);
+    // Foreign tables get an extra "FDW options" column when at least one
+    // attribute actually has options set (matches upstream — the column
+    // slot is conditional on the row data, not just the relkind).
+    const hasAnyFdwOptions = fdwOptionsByColumn.size > 0;
+    // TOAST tables show a slimmer column listing: Column + Type only, no
+    // Collation/Nullable/Default (those are uniformly empty for the three
+    // fixed columns chunk_id/chunk_seq/chunk_data). Matches upstream's
+    // `\d <toast>` output.
+    const isToast = relkind === 't';
+    // Synthesize a printable result set: Column, Type[, Collation, Nullable,
+    // Default[, Storage[, Compression], Stats target, Description]][, FDW options].
+    const fields = [fakeField('Column'), fakeField('Type')];
+    if (!isToast) {
+        fields.push(fakeField('Collation'));
+        fields.push(fakeField('Nullable'));
+        fields.push(fakeField('Default'));
+    }
+    if (verboseCols) {
+        fields.push(fakeField('Storage'));
+        if (includeCompression)
+            fields.push(fakeField('Compression'));
+        if (includeStatsTarget)
+            fields.push(fakeField('Stats target'));
+        fields.push(fakeField('Description'));
+    }
+    if (hasAnyFdwOptions)
+        fields.push(fakeField('FDW options'));
+    const rows = colsRs.rows.map((r) => {
+        const colName = cellToString(r[0]);
+        const colType = cellToString(r[1]);
+        const colDefault = r[2] === null ? null : cellToString(r[2]);
+        const notnull = String(r[3]) === 't' || r[3] === true;
+        const collation = r[4] === null ? null : cellToString(r[4]);
+        const identity = cellToString(r[5] ?? '');
+        const generated = cellToString(r[6] ?? '');
+        const nullable = notnull ? 'not null' : '';
+        let dflt = colDefault ?? '';
+        if (identity === 'a') {
+            dflt = 'generated always as identity';
+        }
+        else if (identity === 'd') {
+            dflt = 'generated by default as identity';
+        }
+        else if (generated === 's') {
+            // STORED generated column (PG 12+).
+            dflt = dflt ? `generated always as (${dflt}) stored` : '';
+        }
+        else if (generated === 'v') {
+            // VIRTUAL generated column (PG 18+). Same expression rendering as
+            // STORED but without the trailing keyword.
+            dflt = dflt ? `generated always as (${dflt})` : '';
+        }
+        const row = isToast
+            ? [colName, colType]
+            : [colName, colType, collation ?? '', nullable, dflt];
+        if (verboseCols) {
+            // Slot offsets: 7 = storage, [8 = compression if PG14+], stats, desc.
+            let idx = 7;
+            const storage = cellToString(r[idx++] ?? '');
+            row.push(storage);
+            if (includeCompression) {
+                const compression = cellToString(r[idx++] ?? '');
+                row.push(compression);
+            }
+            if (includeStatsTarget) {
+                const statsTarget = r[idx] === null ? '' : cellToString(r[idx] ?? '');
+                idx++;
+                row.push(statsTarget);
+            }
+            const description = r[idx] === null ? '' : cellToString(r[idx] ?? '');
+            row.push(description);
+        }
+        if (hasAnyFdwOptions) {
+            const opts = fdwOptionsByColumn.get(colName);
+            row.push(opts ? `(${opts})` : '');
+        }
+        return row;
+    });
+    const colsResult = {
+        command: 'SELECT',
+        rowCount: rows.length,
+        oid: null,
+        fields,
+        rows,
+        notices: [],
+    };
+    // ----- Per-section footers, accumulated *before* the column table is
+    //       printed. Upstream `describeOneTableDetails` attaches each
+    //       relkind-specific footer to the columns table via
+    //       `printTableAddFooter()`, then `printTable()` emits them flush
+    //       against the data rows with a single trailing blank line at the
+    //       end of the whole block. Routing every section through
+    //       `opts.footers` mirrors that layout — single-line annotations
+    //       (`Access method:`, `Tablespace:`, …) sit immediately under the
+    //       last data row, multi-line group footers (`Indexes:`,
+    //       `Foreign-key constraints:`, …) follow, and the trailing blank
+    //       only fires after the last footer rather than between data and
+    //       the first footer.
+    const footers = [];
+    const push = (s) => {
+        if (s !== null)
+            footers.push(s);
+    };
+    // ----- View definition (views / matviews, verbose only) -----
+    //       Upstream attaches this as a table FOOTER (describe.c ~3175), so it
+    //       renders flush against the column rows with the single trailing
+    //       blank line the footer machinery adds — not as a separate block.
+    if ((relkind === 'v' || relkind === 'm') && verbose) {
+        const vrs = await conn.query(`SELECT pg_catalog.pg_get_viewdef('${oid}'::pg_catalog.oid, true);`, []);
+        if (vrs.rows.length > 0) {
+            push(`View definition:\n${cellToString(vrs.rows[0][0])}`);
+        }
+    }
+    // ----- Partition-key (partitioned-table parent only) -----
+    if (relkind === 'p') {
+        push(await captureSection((b) => renderPartitionKeySection(conn, oid, b)));
+    }
+    // ----- Partition-of (child partition only) -----
+    if (relInfo.relispartition) {
+        push(await captureSection((b) => renderPartitionOfSection(conn, oid, verbose, b)));
+    }
+    // ----- Owning table (TOAST tables only — printed before Indexes).
+    //       Upstream `describeOneTableDetails` adds the owning-table footer
+    //       prior to attaching the indexes footer for `RELKIND_TOASTVALUE`.
+    if (relkind === 't') {
+        push(await captureSection((b) => renderToastOwningTableFooter(conn, oid, b)));
+    }
+    // ----- Indexes (tables / matviews / partitioned tables / TOAST) -----
+    if (relkind === 'r' ||
+        relkind === 'm' ||
+        relkind === 'p' ||
+        relkind === 't') {
+        push(await captureSection((b) => renderIndexesSection(conn, oid, b)));
+    }
+    // ----- Check constraints -----
+    if (relkind === 'r' || relkind === 'p' || relkind === 'f') {
+        push(await captureSection((b) => renderCheckConstraintsSection(conn, oid, b)));
+    }
+    // ----- Not-null constraints (PG 18+ named NOT NULL constraints) -----
+    //       Upstream renders this footer in verbose mode between Check
+    //       constraints and Foreign-key constraints (describe.c ~3104).
+    //       The query returns empty on pre-PG-18 servers (no contype = 'n'
+    //       rows), so the section is naturally absent there.
+    if (verbose && (relkind === 'r' || relkind === 'p' || relkind === 'f')) {
+        push(await captureSection((b) => renderNotNullConstraintsSection(conn, oid, b)));
+    }
+    // ----- Foreign-key constraints -----
+    if (relkind === 'r' || relkind === 'p') {
+        push(await captureSection((b) => renderForeignKeyConstraintsSection(conn, oid, b)));
+        push(await captureSection((b) => renderReferencedBySection(conn, oid, b)));
+    }
+    // ----- Triggers -----
+    if (relkind === 'r' || relkind === 'p' || relkind === 'v') {
+        push(await captureSection((b) => renderTriggersSection(conn, oid, b)));
+    }
+    // ----- RLS policies (regular + partitioned tables) -----
+    if (relkind === 'r' || relkind === 'p') {
+        push(await captureSection((b) => renderPoliciesSection(conn, oid, relInfo, b)));
+    }
+    // ----- Foreign-table footer: Server + FDW options -----
+    // Per-column FDW options are rendered inline within the columns
+    // table (see fdwOptionsByColumn above); no separate footer here.
+    if (relkind === 'f') {
+        push(await captureSection((b) => renderForeignTableFooter(conn, oid, b)));
+    }
+    // ----- Inherits: (parents) — for tables, partitioned tables, foreign -----
+    if (relkind === 'r' || relkind === 'p' || relkind === 'f') {
+        push(await captureSection((b) => renderInheritsSection(conn, oid, b)));
+    }
+    // ----- Inherited by / Partitions / Number of [child tables|partitions] -----
+    if (relkind === 'r' || relkind === 'p' || relkind === 'f') {
+        push(await captureSection((b) => renderInheritedBySection(conn, oid, relkind, verbose, b)));
+    }
+    // ----- Publications (any publishable relkind) -----
+    if (relkind === 'r' ||
+        relkind === 'p' ||
+        relkind === 'm' ||
+        relkind === 'f') {
+        push(await captureSection((b) => renderPublicationsSection(conn, oid, b)));
+    }
+    // ----- Subscriptions (any publishable relkind; permission-denied silent) -----
+    if (relkind === 'r' ||
+        relkind === 'p' ||
+        relkind === 'm' ||
+        relkind === 'f') {
+        push(await captureSection((b) => renderSubscriptionsSection(conn, oid, b)));
+    }
+    // ----- Statistics objects (verbose; r/m/p/f) -----
+    if (verbose &&
+        (relkind === 'r' || relkind === 'm' || relkind === 'p' || relkind === 'f')) {
+        push(await captureSection((b) => renderStatisticsObjectsSection(conn, oid, b)));
+    }
+    // ----- Replica Identity (verbose, non-default, regular & matview).
+    //       INDEX mode is rendered inline within Indexes:, so the footer
+    //       is only emitted for FULL / NOTHING.
+    if (verbose && (relkind === 'r' || relkind === 'm')) {
+        push(await captureSection((b) => {
+            renderReplicaIdentitySection(schema, relInfo, b);
+        }));
+    }
+    // ----- Tablespace footer (verbose: explicit tablespace only) -----
+    if (verbose) {
+        push(await captureSection((b) => {
+            renderTablespaceFooter(relkind, relInfo, b);
+        }));
+    }
+    // ----- Access method footer (verbose: relkind r/p with relam set).
+    //       Matviews ('m') show their access method inline in the header,
+    //       so we don't double up here. Gated by `HIDE_TABLEAM` to mirror
+    //       upstream — the per-test psql.sql toggles the variable to
+    //       suppress access-method noise.
+    if (!hideTableam && verbose && (relkind === 'r' || relkind === 'p')) {
+        push(await captureSection((b) => {
+            renderAccessMethodFooter(relInfo, b);
+        }));
+    }
+    // Upstream's `printTable` is invoked with `default_footer = false`
+    // for the column listing: the row-count footer ("(N rows)") is
+    // suppressed so the relkind-specific footers we just collected drive
+    // the post-table layout. Pass them via `opts.footers` so the printer
+    // emits each one flush against the data rows and ends the block with
+    // a single trailing blank line.
+    const colOpts = {
+        ...popt,
+        title,
+        topt: { ...popt.topt, title, defaultFooter: false },
+        footers: footers.length > 0 ? footers : null,
+    };
+    await pickPrinterForFormat(colOpts).printQuery(coerceResultSet(colsResult), colOpts, out);
+};
+/**
+ * Helper that runs {@link fetchTableInfo} and parses the resulting row
+ * into a {@link RelationInfo}. Returns sensible falsy defaults when the
+ * row is missing (shouldn't happen given the caller already looked up
+ * the relation, but we don't want to throw mid-render).
+ */
+const fetchRelationInfo = async (conn, oid) => {
+    const q = fetchTableInfo({ oid, serverVersion: conn.serverVersion });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0) {
+        return {
+            rowsecurity: false,
+            forcerowsecurity: false,
+            relreplident: 'd',
+            relispartition: false,
+            reltablespace: 0,
+            relam: 0,
+            spcname: null,
+            amname: null,
+        };
+    }
+    const r = rs.rows[0];
+    return {
+        rowsecurity: parseBool(r[0]),
+        forcerowsecurity: parseBool(r[1]),
+        relreplident: cellToString(r[2] ?? 'd') || 'd',
+        relispartition: parseBool(r[3]),
+        reltablespace: Number(cellToString(r[4] ?? '0')) || 0,
+        relam: Number(cellToString(r[5] ?? '0')) || 0,
+        spcname: r[6] === null || r[6] === undefined ? null : cellToString(r[6]),
+        amname: r[7] === null || r[7] === undefined ? null : cellToString(r[7]),
+    };
+};
+/** Coerce a Postgres "t"/"f" text-mode boolean (or a real bool) to JS. */
+const parseBool = (v) => v === true || (typeof v === 'string' && (v === 't' || v === 'true'));
+/**
+ * Render `Partition key: <partkeydef>` for partitioned-table parents.
+ */
+const renderPartitionKeySection = async (conn, oid, out) => {
+    const q = fetchPartitionKey({ oid });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    const def = cellToString(rs.rows[0][0] ?? '');
+    if (def === '')
+        return;
+    out.write(`Partition key: ${def}\n`);
+};
+/**
+ * Render the "Partition of: <parent> <bound>[ DETACH PENDING]" line and
+ * the verbose-only "Partition constraint:" follow-up for a child
+ * partition (`relispartition = true`).
+ */
+const renderPartitionOfSection = async (conn, oid, verbose, out) => {
+    const q = fetchPartitionOf({
+        oid,
+        serverVersion: conn.serverVersion,
+        withConstraint: verbose,
+    });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    const row = rs.rows[0];
+    const parent = cellToString(row[0] ?? '');
+    const bound = cellToString(row[1] ?? '');
+    const detached = parseBool(row[2]);
+    const tail = detached ? ' DETACH PENDING' : '';
+    out.write(`Partition of: ${parent} ${bound}${tail}\n`);
+    if (verbose) {
+        const constraintdef = row[3] === null || row[3] === undefined ? '' : cellToString(row[3]);
+        if (constraintdef === '') {
+            out.write('No partition constraint\n');
+        }
+        else {
+            out.write(`Partition constraint: ${constraintdef}\n`);
+        }
+    }
+};
+/**
+ * Render the `Policies[...]:` header + one POLICY line per row. The
+ * exact header text encodes (rowsecurity, forcerowsecurity, has-policies)
+ * the same way upstream does, including the "(none)" tail for the
+ * enabled-but-no-policies cases.
+ */
+const renderPoliciesSection = async (conn, oid, relInfo, out) => {
+    const q = fetchPolicies({ oid, serverVersion: conn.serverVersion });
+    const rs = await conn.query(q.sql, q.params);
+    const tuples = rs.rows.length;
+    const { rowsecurity, forcerowsecurity } = relInfo;
+    let header = null;
+    if (rowsecurity && !forcerowsecurity && tuples > 0) {
+        header = 'Policies:';
+    }
+    else if (rowsecurity && forcerowsecurity && tuples > 0) {
+        header = 'Policies (forced row security enabled):';
+    }
+    else if (rowsecurity && !forcerowsecurity && tuples === 0) {
+        header = 'Policies (row security enabled): (none)';
+    }
+    else if (rowsecurity && forcerowsecurity && tuples === 0) {
+        header = 'Policies (forced row security enabled): (none)';
+    }
+    else if (!rowsecurity && tuples > 0) {
+        header = 'Policies (row security disabled):';
+    }
+    if (header === null)
+        return;
+    out.write(`${header}\n`);
+    for (const r of rs.rows) {
+        const polname = cellToString(r[0]);
+        const permissive = parseBool(r[1]);
+        const roles = r[2] === null || r[2] === undefined ? null : cellToString(r[2]);
+        const qual = r[3] === null || r[3] === undefined ? null : cellToString(r[3]);
+        const withcheck = r[4] === null || r[4] === undefined ? null : cellToString(r[4]);
+        const cmd = r[5] === null || r[5] === undefined ? null : cellToString(r[5]);
+        let line = `    POLICY "${polname}"`;
+        if (!permissive)
+            line += ' AS RESTRICTIVE';
+        if (cmd !== null && cmd !== '')
+            line += ` FOR ${cmd}`;
+        if (roles !== null)
+            line += `\n      TO ${roles}`;
+        if (qual !== null)
+            line += `\n      USING (${qual})`;
+        if (withcheck !== null)
+            line += `\n      WITH CHECK (${withcheck})`;
+        out.write(`${line}\n`);
+    }
+};
+/**
+ * Render the foreign-table footer: `Server: <name>` + optional
+ * `FDW options: (key 'val', key 'val')`. Upstream pulls these in a
+ * single follow-up query; we mirror that shape via
+ * {@link fetchForeignTableInfo}.
+ */
+const renderForeignTableFooter = async (conn, oid, out) => {
+    const q = fetchForeignTableInfo({ oid });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    const row = rs.rows[0];
+    const server = cellToString(row[0] ?? '');
+    const ftoptions = row[1] === null || row[1] === undefined ? '' : cellToString(row[1]);
+    if (server !== '')
+        out.write(`Server: ${server}\n`);
+    if (ftoptions !== '')
+        out.write(`FDW options: (${ftoptions})\n`);
+};
+/**
+ * Render `Inherits: <parent>[, ...]` for relations with parents in
+ * `pg_inherits`. Partition parents are excluded (they're rendered via
+ * `Partition of:` instead) inside the query builder.
+ */
+const renderInheritsSection = async (conn, oid, out) => {
+    const q = fetchInherits({ oid });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    const label = 'Inherits';
+    const indent = ' '.repeat(label.length);
+    rs.rows.forEach((r, idx) => {
+        const parent = cellToString(r[0]);
+        const prefix = idx === 0 ? `${label}: ` : `${indent}  `;
+        const trailing = idx < rs.rows.length - 1 ? ',' : '';
+        out.write(`${prefix}${parent}${trailing}\n`);
+    });
+};
+/**
+ * Render the child-relation footer for inheritance / partition parents.
+ *
+ * - Partitioned parents always emit a `Number of partitions: N` footer
+ *   (even when zero, even in verbose mode); when verbose=false and N>0
+ *   the footer adds the `(Use \d+ to list them.)` hint. Verbose mode
+ *   replaces the count with a full `Partitions:` list including bounds.
+ * - Non-partition parents (regular tables) emit `Number of child
+ *   tables: N (Use \d+ to list them.)` (non-verbose) or `Child tables:`
+ *   list (verbose).
+ */
+const renderInheritedBySection = async (conn, oid, relkind, verbose, out) => {
+    const isPartitioned = relkind === 'p' || relkind === 'I';
+    const q = fetchInheritedBy({ oid, serverVersion: conn.serverVersion });
+    const rs = await conn.query(q.sql, q.params);
+    const tuples = rs.rows.length;
+    if (isPartitioned && tuples === 0) {
+        out.write('Number of partitions: 0\n');
+        return;
+    }
+    if (!verbose) {
+        if (tuples === 0)
+            return;
+        if (isPartitioned) {
+            out.write(`Number of partitions: ${tuples} (Use \\d+ to list them.)\n`);
+        }
+        else {
+            out.write(`Number of child tables: ${tuples} (Use \\d+ to list them.)\n`);
+        }
+        return;
+    }
+    // Verbose mode: list each child with its bound (for partitions) and
+    // child-relkind annotations.
+    const label = isPartitioned ? 'Partitions' : 'Child tables';
+    const indent = ' '.repeat(label.length);
+    rs.rows.forEach((r, idx) => {
+        const relname = cellToString(r[0]);
+        const childKind = cellToString(r[1] ?? '');
+        const detached = parseBool(r[2]);
+        const bound = r[3] === null || r[3] === undefined ? '' : cellToString(r[3]);
+        const prefix = idx === 0 ? `${label}: ` : `${indent}  `;
+        let line = `${prefix}${relname}`;
+        if (bound !== '')
+            line += ` ${bound}`;
+        if (childKind === 'p' || childKind === 'I')
+            line += ', PARTITIONED';
+        else if (childKind === 'f')
+            line += ', FOREIGN';
+        if (detached)
+            line += ' (DETACH PENDING)';
+        if (idx < rs.rows.length - 1)
+            line += ',';
+        out.write(`${line}\n`);
+    });
+};
+/**
+ * Render `Replica Identity: <value>` when the relation's `relreplident`
+ * is non-default and non-INDEX. Upstream skips this footer entirely for
+ * the default value ('d' in user schemas, 'n' for pg_catalog relations);
+ * INDEX-mode (relreplident = 'i') is surfaced inline on the matching
+ * index line in the Indexes: section, so no footer is emitted there
+ * either.
+ */
+const renderReplicaIdentitySection = (schema, relInfo, out) => {
+    const ri = relInfo.relreplident;
+    // INDEX mode is rendered inline on the matching index — no footer.
+    if (ri === 'i')
+        return;
+    // pg_catalog relations default to 'n', user relations to 'd' — both
+    // suppress the footer when the value matches the schema default.
+    const isCatalog = schema === 'pg_catalog';
+    if (!isCatalog && ri === 'd')
+        return;
+    if (isCatalog && ri === 'n')
+        return;
+    const label = ri === 'f'
+        ? 'FULL'
+        : ri === 'd'
+            ? 'NOTHING'
+            : ri === 'n'
+                ? 'NOTHING'
+                : '???';
+    out.write(`Replica Identity: ${label}\n`);
+};
+/**
+ * Emit `Tablespace: "<name>"` when the relation has an explicit
+ * (non-default) tablespace. Only meaningful for relkinds that support
+ * tablespaces — caller enforces the relkind filter.
+ */
+const renderTablespaceFooter = (relkind, relInfo, out) => {
+    const tsSupported = relkind === 'r' ||
+        relkind === 'm' ||
+        relkind === 'i' ||
+        relkind === 'I' ||
+        relkind === 'p' ||
+        relkind === 't';
+    if (!tsSupported)
+        return;
+    if (relInfo.reltablespace === 0 || !relInfo.spcname)
+        return;
+    out.write(`Tablespace: "${relInfo.spcname}"\n`);
+};
+/**
+ * Emit `Access method: <name>` when the relation has an explicit table
+ * access method (PG 12+). Indexes have their AM rendered inline within
+ * the index definition string, so this footer covers only
+ * tables / materialized views / partitioned tables.
+ */
+const renderAccessMethodFooter = (relInfo, out) => {
+    if (relInfo.relam === 0 || !relInfo.amname)
+        return;
+    out.write(`Access method: ${relInfo.amname}\n`);
+};
+/**
+ * Render `Indexes:\n    "name" PRIMARY KEY, btree (col)` for each index
+ * on `oid`. Free-form section — not a table.
+ *
+ * When the relation has INDEX-mode replica identity (relreplident = 'i'),
+ * the corresponding index gets a trailing " REPLICA IDENTITY" marker on
+ * its line, matching upstream `\d` output. The marker comes from each
+ * index's own `pg_index.indisreplident` flag — only one index can carry
+ * it, so no follow-up footer is needed for INDEX-mode RI.
+ */
+const renderIndexesSection = async (conn, oid, out) => {
+    const sql = 'SELECT c2.relname, i.indisprimary, i.indisunique, i.indisclustered,\n' +
+        '  i.indisvalid,\n' +
+        '  pg_catalog.pg_get_indexdef(i.indexrelid, 0, true),\n' +
+        '  pg_catalog.pg_get_constraintdef(con.oid, true),\n' +
+        '  contype, condeferrable, condeferred,\n' +
+        '  i.indisreplident,\n' +
+        '  c2.reltablespace\n' +
+        'FROM pg_catalog.pg_class c, pg_catalog.pg_class c2, pg_catalog.pg_index i\n' +
+        `  LEFT JOIN pg_catalog.pg_constraint con ON (conrelid = i.indrelid AND conindid = i.indexrelid AND contype IN ('p','u','x'))\n` +
+        `WHERE c.oid = '${oid}' AND c.oid = i.indrelid AND i.indexrelid = c2.oid\n` +
+        'ORDER BY i.indisprimary DESC, c2.relname;';
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Indexes:\n');
+    for (const r of rs.rows) {
+        const idxName = cellToString(r[0]);
+        const isPrimary = String(r[1]) === 't' || r[1] === true;
+        const isUnique = String(r[2]) === 't' || r[2] === true;
+        const isClustered = String(r[3]) === 't' || r[3] === true;
+        const isValid = String(r[4]) === 't' || r[4] === true;
+        const indexdef = cellToString(r[5]);
+        const constrDef = r[6] !== null ? cellToString(r[6]) : '';
+        const contype = r[7] === null ? '' : cellToString(r[7]);
+        const condeferrable = String(r[8]) === 't' || r[8] === true;
+        const condeferred = String(r[9]) === 't' || r[9] === true;
+        const isReplIdent = String(r[10]) === 't' || r[10] === true;
+        let line = `    "${idxName}"`;
+        // Strip everything up through " USING " from the indexdef so we get
+        // the trailing `btree (...)` clause.
+        const usingPos = indexdef.indexOf(' USING ');
+        const tail = usingPos >= 0 ? indexdef.slice(usingPos + 7) : indexdef;
+        if (contype === 'x') {
+            // Exclusion constraint: emit constraintdef verbatim, no tail.
+            line += ` ${constrDef}`;
+        }
+        else {
+            // Prefix label per upstream describe.c:
+            //   indisprimary       -> " PRIMARY KEY,"
+            //   indisunique && contype=='u' -> " UNIQUE CONSTRAINT,"
+            //   indisunique        -> " UNIQUE,"
+            // No prefix for plain non-unique indexes.
+            if (isPrimary) {
+                line += ' PRIMARY KEY,';
+            }
+            else if (isUnique) {
+                line += contype === 'u' ? ' UNIQUE CONSTRAINT,' : ' UNIQUE,';
+            }
+            line += ` ${tail}`;
+            if (condeferrable)
+                line += ' DEFERRABLE';
+            if (condeferred)
+                line += ' INITIALLY DEFERRED';
+        }
+        if (isClustered)
+            line += ' CLUSTER';
+        if (!isValid)
+            line += ' INVALID';
+        if (isReplIdent)
+            line += ' REPLICA IDENTITY';
+        out.write(`${line}\n`);
+    }
+};
+/**
+ * Render `Check constraints:\n    "name" CHECK (expr)` list.
+ */
+const renderCheckConstraintsSection = async (conn, oid, out) => {
+    const sql = 'SELECT r.conname, pg_catalog.pg_get_constraintdef(r.oid, true)\n' +
+        'FROM pg_catalog.pg_constraint r\n' +
+        `WHERE r.conrelid = '${oid}' AND r.contype = 'c'\n` +
+        'ORDER BY 1;';
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Check constraints:\n');
+    for (const r of rs.rows) {
+        out.write(`    "${cellToString(r[0])}" ${cellToString(r[1])}\n`);
+    }
+};
+/**
+ * Render `Not-null constraints:\n    "name" NOT NULL "col"[ NO INHERIT]`
+ * list (PG 18+ named NOT NULL constraints, `pg_constraint.contype = 'n'`).
+ *
+ * Upstream `describeOneTableDetails` (describe.c ~3104) emits one line per
+ * constraint in `attnum` order. `connoinherit` adds a trailing
+ * ` NO INHERIT`; inherited-only constraints (`conislocal = false`) are
+ * tagged ` (inherited)` to match vanilla `\d+`. On pre-PG-18 servers the
+ * query returns no rows, so the whole section is suppressed.
+ */
+const renderNotNullConstraintsSection = async (conn, oid, out) => {
+    const q = fetchNotNullConstraints({ oid, serverVersion: conn.serverVersion });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Not-null constraints:\n');
+    for (const r of rs.rows) {
+        const conname = cellToString(r[0]);
+        const attname = cellToString(r[1]);
+        const noInherit = parseBool(r[2]);
+        const isLocal = parseBool(r[3]);
+        let line = `    "${conname}" NOT NULL "${attname}"`;
+        if (noInherit)
+            line += ' NO INHERIT';
+        else if (!isLocal)
+            line += ' (inherited)';
+        out.write(`${line}\n`);
+    }
+};
+/**
+ * Render `Foreign-key constraints:\n    "name" FOREIGN KEY ...` list.
+ */
+const renderForeignKeyConstraintsSection = async (conn, oid, out) => {
+    const sql = 'SELECT conname, pg_catalog.pg_get_constraintdef(oid, true) AS condef\n' +
+        'FROM pg_catalog.pg_constraint\n' +
+        `WHERE conrelid = '${oid}' AND contype = 'f'\n` +
+        'ORDER BY conname;';
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Foreign-key constraints:\n');
+    for (const r of rs.rows) {
+        out.write(`    "${cellToString(r[0])}" ${cellToString(r[1])}\n`);
+    }
+};
+/**
+ * Render `Referenced by:\n    TABLE "..." CONSTRAINT "..." FOREIGN KEY ...`
+ * (incoming FKs from other tables).
+ */
+const renderReferencedBySection = async (conn, oid, out) => {
+    const sql = 'SELECT conname, conrelid::pg_catalog.regclass,\n' +
+        '  pg_catalog.pg_get_constraintdef(oid, true) AS condef\n' +
+        'FROM pg_catalog.pg_constraint\n' +
+        `WHERE confrelid = '${oid}' AND contype = 'f'\n` +
+        'ORDER BY conname;';
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Referenced by:\n');
+    for (const r of rs.rows) {
+        out.write(`    TABLE "${cellToString(r[1])}" CONSTRAINT "${cellToString(r[0])}" ${cellToString(r[2])}\n`);
+    }
+};
+/**
+ * Render `Triggers:\n    name AFTER ... EXECUTE ...` list.
+ */
+const renderTriggersSection = async (conn, oid, out) => {
+    const sql = 'SELECT t.tgname, pg_catalog.pg_get_triggerdef(t.oid, true) AS tgdef, t.tgenabled\n' +
+        'FROM pg_catalog.pg_trigger t\n' +
+        `WHERE t.tgrelid = '${oid}' AND NOT t.tgisinternal\n` +
+        'ORDER BY 1;';
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Triggers:\n');
+    for (const r of rs.rows) {
+        out.write(`    ${cellToString(r[1])}\n`);
+    }
+};
+/**
+ * Render `Statistics objects:\n    "schema"."name" (kinds) ON cols FROM tbl`
+ * for each `pg_statistic_ext` row on the relation. Verbose-only.
+ *
+ * Upstream concatenates the active "kinds" (ndistinct / dependencies / mcv)
+ * inside parentheses; we preserve insertion order matching upstream.
+ */
+const renderStatisticsObjectsSection = async (conn, oid, out) => {
+    const q = fetchStatisticsObjects({ oid, serverVersion: conn.serverVersion });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Statistics objects:\n');
+    for (const r of rs.rows) {
+        const nsp = cellToString(r[0] ?? '');
+        const name = cellToString(r[1] ?? '');
+        const ndist = parseBool(r[2]);
+        const deps = parseBool(r[3]);
+        const mcv = parseBool(r[4]);
+        const columns = cellToString(r[5] ?? '');
+        const relname = cellToString(r[6] ?? '');
+        const kinds = [];
+        if (ndist)
+            kinds.push('ndistinct');
+        if (deps)
+            kinds.push('dependencies');
+        if (mcv)
+            kinds.push('mcv');
+        const kindStr = kinds.length > 0 ? ` (${kinds.join(', ')})` : '';
+        out.write(`    "${nsp}"."${name}"${kindStr} ON ${columns} FROM ${relname}\n`);
+    }
+};
+/**
+ * Render `Publications:\n    "name"` (one per row) for any publication
+ * the relation belongs to (explicit, FOR ALL TABLES, or FOR ALL TABLES
+ * IN SCHEMA). No-op when the result set is empty.
+ */
+const renderPublicationsSection = async (conn, oid, out) => {
+    const q = fetchTablePublications({ oid, serverVersion: conn.serverVersion });
+    const rs = await conn.query(q.sql, q.params);
+    if (rs.rows.length === 0)
+        return;
+    out.write('Publications:\n');
+    for (const r of rs.rows) {
+        out.write(`    "${cellToString(r[0] ?? '')}"\n`);
+    }
+};
+/**
+ * Render `Subscriptions:\n    "name"` (one per row). Requires superuser
+ * access to `pg_subscription` — when the query fails with a permission
+ * error, the section is silently omitted (mirroring upstream behaviour).
+ */
+const renderSubscriptionsSection = async (conn, oid, out) => {
+    const q = fetchTableSubscriptions({ oid, serverVersion: conn.serverVersion });
+    let rs;
+    try {
+        rs = await conn.query(q.sql, q.params);
+    }
+    catch (err) {
+        if (isPermissionDeniedError(err))
+            return;
+        throw err;
+    }
+    if (rs.rows.length === 0)
+        return;
+    out.write('Subscriptions:\n');
+    for (const r of rs.rows) {
+        out.write(`    "${cellToString(r[0] ?? '')}"\n`);
+    }
+};
+/**
+ * Pre-fetch per-column FDW options for a foreign table and index them by
+ * column name so the column-table renderer can fold them in inline.
+ * Upstream renders these as a trailing "FDW options: (k 'v', ...)" cell
+ * on each affected column row, not as a separate footer.
+ */
+const fetchPerColumnFdwOptionsMap = async (conn, oid) => {
+    const q = fetchPerColumnFdwOptions({ oid });
+    const rs = await conn.query(q.sql, q.params);
+    const m = new Map();
+    for (const r of rs.rows) {
+        const attname = cellToString(r[0] ?? '');
+        const opts = cellToString(r[1] ?? '');
+        if (attname !== '' && opts !== '')
+            m.set(attname, opts);
+    }
+    return m;
+};
+/**
+ * Render `Owning table: "schema.name"` for a TOAST relation. Matches
+ * upstream's `\d <toast>` footer — upstream always emits the qualified
+ * `"schema.name"` form (even for `pg_catalog` parents that would
+ * otherwise be elided by search_path), so we look up the nsp+rel pair
+ * directly rather than relying on regclass-cast text.
+ */
+const renderToastOwningTableFooter = async (conn, oid, out) => {
+    // Side-step the regclass-cast query (which honours search_path and
+    // would drop the `pg_catalog.` prefix for pg_catalog parents). Look
+    // up the parent's schema + relname directly so we can render the
+    // schema-qualified form unconditionally.
+    const sql = 'SELECT n.nspname, c.relname\n' +
+        'FROM pg_catalog.pg_class c\n' +
+        'JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace\n' +
+        `WHERE c.reltoastrelid = '${oid}'\n` +
+        'LIMIT 1;';
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length === 0)
+        return;
+    const nspname = cellToString(rs.rows[0][0] ?? '');
+    const relname = cellToString(rs.rows[0][1] ?? '');
+    if (relname === '')
+        return;
+    out.write(`Owning table: "${nspname}.${relname}"\n`);
+};
+/**
+ * Detect a "permission denied" PostgresError (SQLSTATE 42501) on a
+ * thrown value. We look at both `code` (SQLSTATE) and the message text
+ * because not every transport layer surfaces the code. The check is
+ * intentionally conservative — we only swallow genuine privilege
+ * errors, not arbitrary failures.
+ */
+const isPermissionDeniedError = (err) => {
+    if (err === null || typeof err !== 'object')
+        return false;
+    const code = err.code;
+    if (typeof code === 'string' && code === '42501')
+        return true;
+    const message = err.message;
+    if (typeof message === 'string' && /permission denied/i.test(message)) {
+        return true;
+    }
+    return false;
+};
+/**
+ * `\ds <name>` — sequence details. Renders the columns of pg_sequence
+ * plus the `Owned by:` footer if applicable.
+ */
+export const describeOneSequence = async (conn, oid, schema, name, out, popt) => {
+    const sql = 'SELECT pg_catalog.format_type(seqtypid, NULL) AS "Type",\n' +
+        '  seqstart AS "Start", seqmin AS "Minimum", seqmax AS "Maximum",\n' +
+        '  seqincrement AS "Increment",\n' +
+        "  CASE WHEN seqcycle THEN 'yes' ELSE 'no' END AS \"Cycles?\",\n" +
+        '  seqcache AS "Cache"\n' +
+        `FROM pg_catalog.pg_sequence WHERE seqrelid = '${oid}';`;
+    const rs = await conn.query(sql, []);
+    const title = `Sequence "${schema}.${name}"`;
+    // Owned-by footer text is collected up-front so the printer can place
+    // it inside the body of the result (between the data row and the
+    // trailing blank line), matching upstream where `\d <seq>` renders
+    // `Owned by:` AS a footer of the printed table — not as a separate
+    // post-table line.
+    const ownedSql = "SELECT pg_catalog.quote_ident(nspname) || '.' || pg_catalog.quote_ident(relname) || '.' || pg_catalog.quote_ident(attname)\n" +
+        'FROM pg_catalog.pg_class c\n' +
+        'JOIN pg_catalog.pg_depend d ON c.oid = d.refobjid\n' +
+        'JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace\n' +
+        'JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid AND a.attnum = d.refobjsubid\n' +
+        `WHERE d.classid = 'pg_catalog.pg_class'::regclass AND d.refclassid = 'pg_catalog.pg_class'::regclass\n` +
+        `  AND d.objid = '${oid}' AND d.deptype IN ('a', 'i');`;
+    const ownRs = await conn.query(ownedSql, []);
+    const footers = [];
+    if (ownRs.rows.length > 0) {
+        footers.push(`Owned by: ${cellToString(ownRs.rows[0][0])}`);
+    }
+    // Suppress the row-count footer — upstream's sequence detail output is
+    // a single row with no `(1 row)` line. Pass the Owned-by line as a
+    // user footer so the printer places it before the trailing blank.
+    const seqOpts = {
+        ...popt,
+        title,
+        topt: { ...popt.topt, title, defaultFooter: false },
+        footers: footers.length > 0 ? footers : null,
+    };
+    await pickPrinterForFormat(seqOpts).printQuery(coerceResultSet(rs), seqOpts, out);
+};
+/**
+ * `\sf <name>` — show function definition (full CREATE FUNCTION).
+ * Renders the single-column result as raw text.
+ */
+export const describeOneFunctionDetails = async (conn, oid, out) => {
+    const sql = `SELECT pg_catalog.pg_get_functiondef('${oid}'::pg_catalog.oid) AS def;`;
+    const rs = await conn.query(sql, []);
+    if (rs.rows.length > 0) {
+        out.write(cellToString(rs.rows[0][0]));
+        out.write('\n');
+    }
+};
+/**
+ * `\sv <name>` — show view definition.
+ */
+export const describeOneViewDetails = async (conn, oid, schema, name, out, popt, verbose = false, hideCompression = false) => {
+    // Use the table renderer for columns first (views have columns). In
+    // verbose mode this also adds the Storage / Stats target / Description
+    // columns, matching upstream `\d+ <view>`.
+    await describeOneTableDetails(conn, oid, schema, name, 'v', verbose, out, popt, false, hideCompression);
+    // The "View definition:" footer (verbose-only) is emitted by
+    // describeOneTableDetails as a table footer so it renders flush with the
+    // column rows and gets the single trailing blank — matching upstream
+    // `describeOneTableDetails` (describe.c ~3151/3175). Nothing more to do.
+};
+/**
+ * Translate a relkind char into the canonical header psql uses for
+ * `\d <name>`. Examples: 'r' → `Table "schema.name"`; 'v' → `View "..."`.
+ */
+const headerForRelkind = (relkind, schema, name) => {
+    switch (relkind) {
+        case 'r':
+            return `Table "${schema}.${name}"`;
+        case 'v':
+            return `View "${schema}.${name}"`;
+        case 'm':
+            return `Materialized view "${schema}.${name}"`;
+        case 'S':
+            return `Sequence "${schema}.${name}"`;
+        case 'i':
+            return `Index "${schema}.${name}"`;
+        case 'I':
+            return `Partitioned index "${schema}.${name}"`;
+        case 'p':
+            return `Partitioned table "${schema}.${name}"`;
+        case 'f':
+            return `Foreign table "${schema}.${name}"`;
+        case 't':
+            return `TOAST table "${schema}.${name}"`;
+        case 'c':
+            return `Composite type "${schema}.${name}"`;
+        default:
+            return `Relation "${schema}.${name}"`;
+    }
+};
+/**
+ * Build a minimal {@link FieldDescription} for synthesized rows where
+ * we don't actually have a wire-level row description. Used by the
+ * columns table in `describeOneTableDetails` because we synthesize
+ * the layout from pg_attribute data.
+ */
+const fakeField = (name) => ({
+    name,
+    tableID: 0,
+    columnID: 0,
+    dataTypeID: 25,
+    dataTypeSize: -1,
+    dataTypeModifier: -1,
+    format: 0,
+});