@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/source-edit.js

@@ -13,7 +13,9 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { addedTables, chooseColumns, entryName, entryProblems, findEntry, parseSourceText, sourceFailure, sourceFileNames, sourcesDir, unaddableReason, withoutTable, withTable } from "./sources.js";
+import { addedTables, chooseColumns, effectiveSync, entryName, entryProblems, findEntry, parseSourceText, sourceFailure, sourceFileNames, sourcesDir, unaddableReason, withEntrySync, withoutTable, withTable } from "./sources.js";
+import { BIG_TABLE_ROWS, COSTLY_POLL_ROWS, COSTLY_POLL_SECONDS, syncText } from "../lib/table-sync.js";
+import { projectWriteRefusal } from "./project.js";
 /** A refusal the command shows as it is; `failure` is how the web page says it (the CLI's Failure: why, fix, next), by
  *  default the message alone under the status's code. */
 export class Refusal extends Error {
@@ -24,11 +26,41 @@ export class Refusal extends Error {
 /** The FAILURE_CODES code (src/cli/command.ts) of a refusal by its HTTP status. */
 const codeOf = (status) => status === 400 ? "usage" : status === 404 ? "not_found" : status >= 500 ? "failed" : "refused";
 /**
- * The project's sources file as it is on disk NOW, its text and what it says — or why it cannot be edited: no folder, not
- * exactly one file, a file with mistakes of its own, a URL that cannot be resolved (`read`, the file read as the run reads
- * it: src/cli/sources.ts readSource).
+ * A SCAN'S RATE WHEN NOTHING OF THE TABLE IS MEASURED, rows a second on one backend: the test server's production
+ * replica scanned a 22 M-row table in 12 s at every poll (docs/DESIGN.md "The poll") — an assumption, said as one.
  */
-export function sourceToEdit(folder, root, read) {
+const ASSUMED_SCAN_ROWS_PER_SECOND = 1_800_000;
+/**
+ * WHAT A POLL OF A BIG TABLE WOULD COST THE DATABASE, estimated before it runs (issue 33: "a poll never takes more than
+ * a fifth of the source's time" bounds the share, not the backend's seconds — a 200 M-row table set to poll 5m is
+ * still a standing load): seconds a poll, from the best basis there is — its last poll, measured; else its copy's read
+ * rate, a reader's (an upper bound: a poll sends only the changed rows); else the catalog's row estimate at an assumed
+ * scan rate — and the basis said. Null for a table under `COSTLY_POLL_ROWS`, or set to poll every minute or slower.
+ */
+export function pollCost(t, sync, m) {
+    if (sync.mode !== "poll" || sync.seconds >= COSTLY_POLL_SECONDS || t.rows === null || t.rows < COSTLY_POLL_ROWS)
+        return null;
+    const rows = t.rows.toLocaleString("en-US");
+    const [seconds, basis] = m?.lastPollMs != null ? [m.lastPollMs / 1000, "its last poll, measured"]
+        : m?.copyRowsPerSecond ? [t.rows / m.copyRowsPerSecond, `its first sync's read rate, ${Math.round(m.copyRowsPerSecond).toLocaleString("en-US")} rows a second a reader (a poll sends only the rows that changed, so it is at most that)`]
+            : [t.rows / ASSUMED_SCAN_ROWS_PER_SECOND, `the catalog's ${rows} rows at an assumed ${ASSUMED_SCAN_ROWS_PER_SECOND.toLocaleString("en-US")} rows a second of scan (nothing of it measured yet)`];
+    const every = Math.max(sync.seconds, 4 * seconds);
+    const s = (x) => x < 90 ? `${Math.round(x)} s` : x < 5400 ? `${Math.round(x / 60)} min` : `${(x / 3600).toFixed(1)} h`;
+    return `${entryName(t.source)} has about ${rows} rows, and each poll scans it whole on your database: about ${s(seconds)} a poll, from ${basis}. ` +
+        `sync: ${syncText(sync)} is stretched to a poll every ${s(every)} at most (a poll waits four times its own time), one backend of your database ` +
+        `busy ${Math.round((seconds / every) * 100)} % of the time — a longer interval (--sync "poll 1h"), or --sync replication (the change log), costs it less`;
+}
+/**
+ * The project's sources file as it is on disk NOW, its text and what it says — or why it cannot be edited: its files are
+ * read-only here (src/cli/project.ts `projectWriteRefusal`, the one authority, asked FIRST: nothing is read or checked
+ * against the database for an edit that cannot be written), no folder, not exactly one file, a file with mistakes of its
+ * own, a URL that cannot be resolved (`read`, the file read as the run reads it: src/cli/sources.ts readSource). An
+ * `EditTarget` is made here alone, so every edit `addEntry` and `removeEntries` write has asked.
+ */
+export function sourceToEdit(folder, root, read, env = process.env) {
+    const readOnly = projectWriteRefusal(root, env);
+    if (readOnly !== null)
+        throw new Refusal(409, readOnly.message, readOnly);
     if (!folder)
         throw new Refusal(409, "choose the project's folder first");
     const names = sourceFileNames(folder);
@@ -49,7 +81,7 @@ export function sourceToEdit(folder, root, read) {
 /** The file's other entries against the database: an edit is never written over a file the run would not take. */
 function othersHold(at, db, without, then) {
     const others = { ...at.parsed, tables: at.parsed.tables.filter((e) => !without.includes(e.table)) };
-    const held = addedTables(others, db.tables, db.database, at.root, { replication: db.replication });
+    const held = addedTables(others, db.tables, db.database, at.root);
     if (!Array.isArray(held))
         throw new Refusal(409, `${held.message}${held.why ? `\n${held.why}` : ""} — fix it first, then ${then}`);
 }
@@ -58,35 +90,61 @@ function othersHold(at, db, without, then) {
  * table's own (`withTable`): every other byte of the file as it was. `columns` are the ones asked (`["*"]`: every one);
  * `key` the columns a table with no primary key is copied by. The entry and the file's other entries must hold against
  * the database first: an edit is never written over a file the next read would refuse.
+ *
+ * ITS SYNC (`o.sync`, --sync): written on the entry as its own `sync:`; else an entry's own is kept; else a NEW entry
+ * follows the file's default — unless the table is over `BIG_TABLE_ROWS` and that default polls, when the entry is
+ * written `sync: off` and said (`bigOff`): a poll scans its table whole — or the default is `replication` and the table
+ * cannot be (a `--key` table, REPLICA IDENTITY NOTHING), when it is written `sync: poll 5m` and said why (`notReplicated`;
+ * an explicit `--sync replication` of such a table is refused, at its entry). `o.keep`: only the sync is asked of a table
+ * already added (`mason add orders --sync "poll 30s"`), so its columns and key stay as they are, and only its `sync:`
+ * line is written (`withEntrySync`: its comments too).
  */
-export function addEntry(at, db, table, columns = ["*"], key = null) {
+export function addEntry(at, db, table, columns = ["*"], key = null, o = {}) {
     const t = db.tables.find((x) => x.source === table);
     if (!t)
         throw new Refusal(404, `${table} is not a table of ${db.database} that this user can read`);
     if (key !== null && t.key.length)
-        throw new Refusal(400, `${table} has a primary key (${t.key.join(", ")}), which Mason copies it by: leave --key out`);
+        throw new Refusal(400, `${table} has a primary key (${t.key.join(", ")}), which Mason keys it by: leave --key out`);
     if (key === null && !t.key.length)
         throw new Refusal(409, `${table} cannot be added: ${unaddableReason(t)}`);
-    if (key !== null && db.replication)
-        throw new Refusal(409, `${table} has no primary key, and logical replication cannot apply its changes by --key: copy it by polling (mason start --poll), then add it`);
-    const chosen = chooseColumns(t, columns, key);
+    const was = at.parsed.tables.find((e) => e.table === table);
+    const keep = o.keep === true && was !== undefined;
+    const chosen = keep ? { columns: was.columns, exclude: was.exclude, addedKey: [], skipped: [] } : chooseColumns(t, columns, key);
     if ("problem" in chosen)
         throw new Refusal(400, chosen.problem);
     othersHold(at, db, [table], `add ${entryName(table)}`);
-    const was = at.parsed.tables.find((e) => e.table === table);
-    const entry = { name: was?.name ?? entryName(table), table, columns: chosen.columns, exclude: chosen.exclude, key: key === null ? null : [...key] };
+    // its own sync: asked, else the one its entry has, else none (the file's) — but a new big table under a polling default
+    const fileSync = effectiveSync(at.parsed, undefined).sync;
+    const bigOff = o.sync === undefined && was === undefined && fileSync.mode === "poll" && t.rows !== null && t.rows > BIG_TABLE_ROWS;
+    // a table logical replication cannot keep, under a file whose default is replication: polled, said (never refused for
+    // the default it did not choose; its own --sync replication is refused at its entry, below)
+    const keyed = keep ? was.key !== null : key !== null;
+    const unreplicable = keyed ? "it has no primary key, so logical replication cannot apply its changes by its key:"
+        : t.replicaIdentity === "n" ? "it has REPLICA IDENTITY NOTHING, and a publication carrying it would make your app's own UPDATEs and DELETEs on it fail" : null;
+    const notReplicated = o.sync === undefined && (was?.sync ?? null) === null && fileSync.mode === "replication" ? unreplicable : null;
+    // --sync replication asked of one: refused with the COMMAND to run (the person is at it), its own flags kept — the
+    // file's words are for an entry written by hand (src/cli/sources.ts entryProblems)
+    if (o.sync?.mode === "replication" && unreplicable !== null) {
+        const others = columns.filter((c) => c !== "*");
+        const flags = keep ? "" : `${columns.includes("*") ? (others.length ? ` --include ${others.join(",")}` : "") : ` --columns ${others.join(",")}`}${key !== null ? ` --key ${key.join(",")}` : ""}`;
+        throw new Refusal(400, `${table} cannot be kept current by logical replication: ${unreplicable} — mason add ${entryName(table)}${flags} --sync "poll 5m" polls it instead`);
+    }
+    const sync = o.sync ?? was?.sync ?? (bigOff ? { mode: "off" } : notReplicated !== null ? { mode: "poll", every: "5m", seconds: 300 } : null);
+    const entry = { name: was?.name ?? entryName(table), table, columns: chosen.columns, exclude: chosen.exclude, key: keep ? was.key : key === null ? null : [...key], sync };
     // the entry itself, as the run will read it: a --key that does not tell the rows apart is refused here, not at the copy
-    const own = entryProblems(t, entry, db.tables, db.database, { replication: db.replication });
+    const own = entryProblems(t, entry, db.tables, db.database, effectiveSync(at.parsed, entry).sync);
     if (own.length)
         throw new Refusal(400, own.join("; "));
-    const same = was !== undefined && JSON.stringify([was.columns, was.exclude, was.key]) === JSON.stringify([entry.columns, entry.exclude, entry.key]);
+    const same = was !== undefined && JSON.stringify([was.columns, was.exclude, was.key, was.sync]) === JSON.stringify([entry.columns, entry.exclude, entry.key, entry.sync]);
     if (!same) {
-        const r = withTable(at.text, entry);
+        const r = keep ? withEntrySync(at.text, was, sync) : withTable(at.text, entry);
         if ("problem" in r)
             throw new Refusal(409, `${path.relative(at.root, at.file)} cannot be edited: ${r.problem}`);
         fs.writeFileSync(at.file, r.text);
     }
-    return { table, file: at.file, entry: entry.name, columns: entry.columns, exclude: entry.exclude, key: entry.key, addedKey: chosen.addedKey, skippedSecrets: chosen.skipped, already: same };
+    const eff = effectiveSync(at.parsed, entry);
+    return { table, file: at.file, entry: entry.name, columns: entry.columns, exclude: entry.exclude, key: entry.key, addedKey: chosen.addedKey, skippedSecrets: chosen.skipped, already: same,
+        sync: { value: syncText(eff.sync), from: eff.from }, bigOff, notReplicated, pollCost: pollCost(t, eff.sync, db.measured?.(table) ?? null) };
 }
 /**
  * REMOVE TABLES from the sources file: each one's entry cut (`withoutTable`), every other byte of the file as it was. A

package/dist/src/cli/source-role.js

@@ -0,0 +1,344 @@
+/**
+ * WHETHER THE ROLE MASON CONNECTS AS COULD WRITE TO THE SOURCE (issue 524), for `mason doctor`. Mason only reads the
+ * database it syncs (CLAUDE.md "The source database is production"), so the role it connects as need not be able to
+ * write either: one that can lets a Mason bug, or a stolen URL, change production. Said as WARNINGS, never a refusal:
+ * a start goes on, and the way out is the statements that make a role that only reads.
+ *
+ * ONE catalog read (`roleFactsSql`), no write ever attempted, and every privilege decided by Postgres itself:
+ * `has_table_privilege`, `has_any_column_privilege` (a column's INSERT, UPDATE or REFERENCES is a write too),
+ * `has_schema_privilege` and `has_function_privilege`, asked for the role, for every role whose privileges it holds or
+ * may SET ROLE to (`pg_has_role … 'USAGE'` or `'SET'` from Postgres 16; `'MEMBER'` before, when any membership could
+ * SET ROLE), and for PUBLIC, which every role holds; never an ACL read by hand.
+ *
+ * THE CLASS (PR 572's review, two rounds): every way Postgres lets a role change a synced table's rows WITHOUT a
+ * privilege on that table, each read from its catalog. The "only reads" line is true by construction because each is
+ * asked, and over-approximated where the catalog cannot say more (a warning too many, never one too few):
+ *   - DECLARATIVE ROUTES, followed transitively (`reach`): a descendant by `pg_inherits` (a partition, or an INHERITS
+ *     child, whose rows ARE the synced table's: every privilege); an INHERITS ancestor (an UPDATE, DELETE or TRUNCATE
+ *     on it reaches its children's rows, Postgres asking only the parent's privilege); a relation whose rules depend on
+ *     a route (`pg_rewrite` through `pg_depend`: a view at any depth, or another table's rule), for the INSERT, UPDATE
+ *     and DELETE `pg_relation_is_updatable` says it takes; and a table a route's foreign key references with an ON
+ *     DELETE or ON UPDATE action that writes (`pg_constraint` `confdeltype` / `confupdtype` CASCADE, SET NULL or SET
+ *     DEFAULT), whose action runs as the referencing table's owner. TRUNCATE … CASCADE is no route: Postgres asks
+ *     TRUNCATE on every table it cascades to (measured on 16).
+ *   - CODE THAT RUNS AS ANOTHER ROLE: a SECURITY DEFINER function whose owner may write a route (a superuser, or one
+ *     holding a route's privilege), not the role's own, that it reaches as Postgres decides (measured on 16, PR 572's
+ *     third review): by EXECUTE, wherever it is called from (a view, a policy, a default, a CHECK, an index, a cast, an
+ *     operator); by a trigger on a relation it may write; and with no EXECUTE asked, by an event trigger (any DDL, even
+ *     one refused), an aggregate it may call (its support functions), a type (its I/O), an operator's estimators, an
+ *     operator class's, a range's or a conversion's function. Volatility bounds nothing (a STABLE definer calling a
+ *     VOLATILE writer writes). What such a function writes is in its body, which the catalog does not read: it is its own
+ *     finding (`role_may_run_definer_code`), LISTED for a person to review, and the role is never said to "only read"
+ *     while one is reached. Code of invoker's rights runs with the role's own privileges, which the rest asks.
+ *   - ANOTHER IDENTITY BY CONNECTION: a foreign table it may write, or a user mapping on a server it may use (postgres_fdw,
+ *     dblink): what it sends runs as the mapping's user, maybe on this very database.
+ *   - BECOMING ANOTHER ROLE: ADMIN OPTION on a role (it may grant itself that role), CREATEROLE before Postgres 16 (any
+ *     role but a superuser), and pg_execute_server_program, pg_write_server_files or pg_read_server_files (the server's
+ *     programs and files as its operating-system user).
+ * Not routes: COPY … FROM needs INSERT, which is asked; a large object is not a table's rows; a publication only reads;
+ * a subscription writes as its owner, with that owner's privileges, and a table it fills is written from another
+ * database, which this database cannot see.
+ *
+ * The statement runs under `search_path = pg_catalog` (`SET LOCAL`, ending with it, as VIEWS_SQL does), so no function,
+ * operator or table of the role's own schemas can stand in for the catalog's.
+ */
+import { pgLiteral } from "../cdc/pg-wire.js";
+import { shownUrl } from "./preflight.js";
+/** The privileges on a table that write or change it (SELECT is the one Mason needs), in their bit order (`mask`). */
+export const WRITE_PRIVILEGES = ["INSERT", "UPDATE", "DELETE", "TRUNCATE", "REFERENCES", "TRIGGER"];
+/** Each warning's code, stable for an agent: one per thing the role should not have (`role_unknown`: could not tell). */
+export const ROLE_CODES = ["role_superuser", "role_bypassrls", "role_owns_table", "role_writes_table", "role_creates_in_schema",
+    "role_may_run_definer_code", "role_reaches_foreign_server", "role_may_become_another", "role_unknown"];
+/** The name the way out gives the role that only reads, or the first of `mason_reader2`, … not taken. */
+export const READER_ROLE = "mason_reader";
+/** Whether `role` holds privilege `p` on relation `rel` (SQL expressions): a column's INSERT, UPDATE or REFERENCES counts */
+const holds = (role, rel, p) => `CASE WHEN ${p} IN ('INSERT', 'UPDATE', 'REFERENCES') THEN has_any_column_privilege(${role}, ${rel}, ${p}) ELSE has_table_privilege(${role}, ${rel}, ${p}) END`;
+/** The predefined roles that reach the server's programs or files (a superuser's, in effect) */
+export const SERVER_ROLES = ["pg_execute_server_program", "pg_write_server_files", "pg_read_server_files"];
+/**
+ * Everything the checks read, in ONE statement under the catalog's search_path, for the tables `tables` names (a JSON
+ * list of {schema, table}). A superuser holds every privilege: what else it holds is not asked.
+ */
+export function roleFactsSql(tables) {
+    const want = pgLiteral(JSON.stringify(tables.map((t) => ({ schema: t.schema, table: t.table }))));
+    const writes = WRITE_PRIVILEGES.map((p) => `'${p}'`).join(", ");
+    const all = (1 << WRITE_PRIVILEGES.length) - 1, ins = 1, upd = 2, del = 4, trunc = 8;
+    return `SET LOCAL search_path = pg_catalog; WITH RECURSIVE me AS (SELECT oid, rolname, rolsuper, rolcreaterole FROM pg_roles WHERE rolname = current_user),
+-- the roles whose privileges it holds or that it may switch to (Postgres 16 split the two, before it any membership was both)
+r AS (SELECT p.oid, p.rolname, p.rolsuper, p.rolbypassrls, p.oid = me.oid AS self FROM pg_roles p, me
+  WHERE p.oid = me.oid OR (NOT me.rolsuper AND CASE WHEN current_setting('server_version_num')::int >= 160000
+    THEN pg_has_role(me.oid, p.oid, 'USAGE') OR pg_has_role(me.oid, p.oid, 'SET') ELSE pg_has_role(me.oid, p.oid, 'MEMBER') END)),
+su AS (SELECT EXISTS (SELECT FROM r WHERE rolsuper) AS any),
+want AS (SELECT w.schema, w."table" FROM json_to_recordset(${want}::json) AS w(schema text, "table" text)),
+rel AS (SELECT w.schema, w."table", c.oid FROM want w JOIN pg_namespace n ON n.nspname = w.schema
+  JOIN pg_class c ON c.relnamespace = n.oid AND c.relname = w."table" AND c.relkind IN ('r', 'p')),
+-- how a write on one relation reaches another's rows. need: the modes it leaves from (S a synced table, R its rows'
+-- relation, A an ancestor, F a referenced table, V a view or rule), gives: the mode it reaches, mask: the privileges
+-- (bits in WRITE_PRIVILEGES' order) that reach, a view's or rule's read from pg_relation_is_updatable below
+edge AS (SELECT inhparent AS src, inhrelid AS dst, 'SR' AS need, 'R' AS gives, ${all} AS mask FROM pg_inherits
+  UNION ALL SELECT inhrelid, inhparent, 'SRAF', 'A', ${upd | del | trunc} FROM pg_inherits
+  UNION ALL SELECT d.refobjid, rw.ev_class, 'SRAFV', 'V', 0 FROM pg_depend d JOIN pg_rewrite rw ON rw.oid = d.objid
+    WHERE d.classid = 'pg_rewrite'::regclass AND d.refclassid = 'pg_class'::regclass AND rw.ev_class <> d.refobjid
+  UNION ALL SELECT conrelid, confrelid, 'SRF', 'F', CASE WHEN confdeltype IN ('c', 'n', 'd') THEN ${del} ELSE 0 END | CASE WHEN confupdtype IN ('c', 'n', 'd') THEN ${upd} ELSE 0 END
+    FROM pg_constraint WHERE contype = 'f' AND (confdeltype IN ('c', 'n', 'd') OR confupdtype IN ('c', 'n', 'd'))),
+-- each synced table and every relation that reaches its rows, at any depth: UNION stops at what it has seen
+reach AS (SELECT schema || '.' || "table" AS entry, oid, 'S' AS mode, ${all} AS mask FROM rel
+  UNION SELECT x.entry, e.dst, e.gives, e.mask FROM reach x JOIN edge e ON e.src = x.oid AND position(x.mode IN e.need) > 0),
+route AS (SELECT x.entry, x.oid, min(position(x.mode IN 'SRAFV')) AS rank,
+    bit_or(CASE WHEN x.mode <> 'V' THEN x.mask ELSE CASE WHEN k.u & 8 <> 0 THEN ${ins} ELSE 0 END | CASE WHEN k.u & 4 <> 0 THEN ${upd} ELSE 0 END | CASE WHEN k.u & 16 <> 0 THEN ${del} ELSE 0 END END) AS mask
+  FROM reach x CROSS JOIN LATERAL (SELECT CASE WHEN x.mode = 'V' THEN pg_relation_is_updatable(x.oid, true) ELSE 0 END AS u) k GROUP BY x.entry, x.oid),
+-- each privilege that reaches a synced table's rows through a route
+asks AS (SELECT x.entry, x.oid, u.p, u.o FROM route x CROSS JOIN unnest(ARRAY[${writes}]) WITH ORDINALITY AS u(p, o) WHERE x.mask & (1 << (u.o::int - 1)) <> 0),
+who AS (SELECT rolname AS role, CASE WHEN self THEN 0 ELSE 1 END AS ord FROM r UNION ALL SELECT 'public', 2),
+-- SECURITY DEFINER code (not the role's own) whose owner may write a synced table's rows: each owner asked once
+sd AS (SELECT f.oid, f.proowner, f.prorettype NOT IN ('trigger'::regtype, 'event_trigger'::regtype) AS direct FROM pg_proc f, su
+  WHERE f.prosecdef AND NOT su.any AND f.proowner NOT IN (SELECT oid FROM r)),
+writer AS (SELECT o.oid, o.rolname, o.rolsuper FROM pg_roles o WHERE o.oid IN (SELECT proowner FROM sd)
+  AND (o.rolsuper OR EXISTS (SELECT FROM asks a WHERE ${holds("o.rolname", "a.oid", "a.p")}))),
+definer AS (SELECT sd.oid, sd.direct, w.rolname AS owner, w.rolsuper AS owner_super FROM sd JOIN writer w ON w.oid = sd.proowner),
+-- the relations it may write whose enabled trigger calls one (pg_trigger read once, joined: never once per function)
+dtrig AS (SELECT DISTINCT t.tgfoid, tn.nspname || '.' || tc.relname AS rel FROM pg_trigger t JOIN definer d ON d.oid = t.tgfoid
+    JOIN pg_class tc ON tc.oid = t.tgrelid JOIN pg_namespace tn ON tn.oid = tc.relnamespace
+  WHERE NOT t.tgisinternal AND t.tgenabled <> 'D'
+    AND EXISTS (SELECT FROM who w, unnest(ARRAY['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE']) AS u(p) WHERE ${holds("w.role::name", "t.tgrelid", "u.p")})),
+-- what Postgres calls without asking the caller's EXECUTE: an event trigger's function, an aggregate's support
+-- functions (when it may call the aggregate), a type's input, output, receive, send, typmod and analyze functions, an
+-- operator's estimators, an operator class's support functions, a range's, a conversion's
+unchecked AS (SELECT evtfoid AS fn FROM pg_event_trigger WHERE evtenabled <> 'D'
+  UNION SELECT a.fn FROM (SELECT aggfnoid, unnest(ARRAY[aggtransfn::oid, aggfinalfn::oid, aggcombinefn::oid, aggserialfn::oid, aggdeserialfn::oid,
+      aggmtransfn::oid, aggminvtransfn::oid, aggmfinalfn::oid]) AS fn FROM pg_aggregate) a
+    WHERE a.fn IN (SELECT oid FROM definer) AND EXISTS (SELECT FROM who w WHERE has_function_privilege(w.role::name, a.aggfnoid, 'EXECUTE'))
+  UNION SELECT unnest(ARRAY[typinput::oid, typoutput::oid, typreceive::oid, typsend::oid, typmodin::oid, typmodout::oid, typanalyze::oid]) FROM pg_type
+  UNION SELECT unnest(ARRAY[oprrest::oid, oprjoin::oid]) FROM pg_operator
+  UNION SELECT amproc::oid FROM pg_amproc
+  UNION SELECT unnest(ARRAY[rngcanonical::oid, rngsubdiff::oid]) FROM pg_range
+  UNION SELECT conproc::oid FROM pg_conversion)
+SELECT json_build_object(
+  'user', me.rolname, 'user_sql', quote_ident(me.rolname), 'database_sql', quote_ident(current_database()),
+  'roles', (SELECT json_agg(json_build_object('name', rolname, 'self', self, 'superuser', rolsuper, 'bypassrls', rolbypassrls) ORDER BY NOT self, rolname) FROM r),
+  'relations', (SELECT coalesce(json_agg(json_build_object('name', n.nspname || '.' || c.relname, 'sql', quote_ident(n.nspname) || '.' || quote_ident(c.relname),
+      'kind', CASE x.rank WHEN 1 THEN 'table' WHEN 2 THEN CASE WHEN c.relispartition THEN 'partition' ELSE 'child' END WHEN 3 THEN 'parent' WHEN 4 THEN 'referenced'
+        ELSE CASE WHEN c.relkind = 'v' THEN 'view' ELSE 'rule' END END,
+      'entry', x.entry, 'schema_sql', quote_ident(n.nspname), 'owner', pg_get_userbyid(c.relowner),
+      'owned', x.rank <= 2 AND c.relowner IN (SELECT oid FROM r), 'row_security', c.relrowsecurity,
+      'privileges', CASE WHEN su.any THEN '[]'::json ELSE (SELECT coalesce(json_agg(json_build_object('role', CASE WHEN g.ord = 2 THEN 'PUBLIC' ELSE g.role END, 'privileges', g.privs) ORDER BY g.ord, g.role), '[]'::json)
+        FROM (SELECT w.role, w.ord, (SELECT coalesce(array_agg(a.p ORDER BY a.o), '{}') FROM asks a WHERE a.entry = x.entry AND a.oid = x.oid AND ${holds("w.role::name", "a.oid", "a.p")}) AS privs
+          FROM who w) g WHERE cardinality(g.privs) > 0) END) ORDER BY x.rank, x.entry, n.nspname, c.relname), '[]'::json)
+    FROM route x JOIN pg_class c ON c.oid = x.oid JOIN pg_namespace n ON n.oid = c.relnamespace),
+  'schemas', (SELECT coalesce(json_agg(json_build_object('name', n.nspname, 'sql', quote_ident(n.nspname), 'owner', pg_get_userbyid(n.nspowner),
+      'owned', n.nspowner IN (SELECT oid FROM r),
+      'create', CASE WHEN su.any THEN '[]'::json ELSE (SELECT coalesce(json_agg(rr.rolname ORDER BY NOT rr.self, rr.rolname), '[]'::json) FROM r rr WHERE has_schema_privilege(rr.rolname, n.oid, 'CREATE')) END,
+      'public_create', has_schema_privilege('public'::name, n.oid, 'CREATE')) ORDER BY n.nspname), '[]'::json)
+    FROM pg_namespace n WHERE n.oid IN (SELECT c.relnamespace FROM route x JOIN pg_class c ON c.oid = x.oid WHERE x.rank <= 2)),
+  'definers', (SELECT coalesce(json_agg(d ORDER BY d.name), '[]'::json) FROM (
+      SELECT quote_ident(n.nspname) || '.' || quote_ident(f.proname) || '(' || pg_get_function_identity_arguments(f.oid) || ')' AS name, x.owner, x.owner_super,
+        -- reached through a view, a policy, a default, a CHECK, an index, a cast or an operator only by EXECUTE, a
+        -- trigger's function only by its trigger
+        x.direct AND EXISTS (SELECT FROM who w WHERE has_function_privilege(w.role::name, x.oid, 'EXECUTE')) AS callable,
+        x.direct AND has_function_privilege('public'::name, x.oid, 'EXECUTE') AS public_callable,
+        (SELECT coalesce(json_agg(t.rel ORDER BY t.rel), '[]'::json) FROM dtrig t WHERE t.tgfoid = x.oid) AS triggers,
+        EXISTS (SELECT FROM pg_event_trigger e WHERE e.evtfoid = x.oid AND e.evtenabled <> 'D') AS event_trigger,
+        x.oid IN (SELECT fn FROM unchecked) AS unchecked
+      FROM definer x JOIN pg_proc f ON f.oid = x.oid JOIN pg_namespace n ON n.oid = f.pronamespace) d
+    WHERE d.callable OR json_array_length(d.triggers) > 0 OR d.unchecked),
+  'foreign_tables', CASE WHEN su.any THEN '[]'::json ELSE (SELECT coalesce(json_agg(n.nspname || '.' || c.relname ORDER BY n.nspname, c.relname), '[]'::json)
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.relkind = 'f'
+      AND EXISTS (SELECT FROM who w, unnest(ARRAY['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE']) AS u(p) WHERE ${holds("w.role::name", "c.oid", "u.p")})) END,
+  'mapped_servers', CASE WHEN su.any THEN '[]'::json ELSE (SELECT coalesce(json_agg(DISTINCT m.srvname), '[]'::json) FROM pg_user_mappings m
+    WHERE (m.umuser = 0 OR m.umuser IN (SELECT oid FROM r)) AND EXISTS (SELECT FROM who w WHERE has_server_privilege(w.role::name, m.srvid, 'USAGE'))) END,
+  'admin_of', CASE WHEN su.any THEN '[]'::json ELSE (SELECT coalesce(json_agg(p.rolname ORDER BY p.rolname), '[]'::json) FROM pg_roles p
+    WHERE p.oid <> me.oid AND pg_has_role(me.oid, p.oid, 'MEMBER WITH ADMIN OPTION')) END,
+  'create_role', NOT su.any AND me.rolcreaterole AND current_setting('server_version_num')::int < 160000,
+  'server_roles', (SELECT coalesce(json_agg(rolname ORDER BY rolname), '[]'::json) FROM r WHERE NOT su.any AND rolname IN (${SERVER_ROLES.map((x) => `'${x}'`).join(", ")})),
+  'missing', (SELECT coalesce(json_agg(w.schema || '.' || w."table"), '[]'::json) FROM want w WHERE NOT EXISTS (SELECT FROM rel WHERE rel.schema = w.schema AND rel."table" = w."table")),
+  'taken', (SELECT coalesce(json_agg(rolname ORDER BY rolname), '[]'::json) FROM pg_roles WHERE rolname LIKE '${READER_ROLE.replace(/_/g, "\\_")}%'),
+  'rds_replication', EXISTS (SELECT FROM pg_roles WHERE rolname = 'rds_replication')
+)::text FROM me, su`;
+}
+/** The role's facts, read in the one statement; a role with no row of pg_roles (it was dropped while connected) throws. */
+export async function readRoleFacts(pg, tables) {
+    const row = JSON.parse((await pg.query(roleFactsSql(tables))).rows[0]?.[0] ?? "null");
+    if (row === null)
+        throw new Error("pg_roles has no row for the user connected");
+    return {
+        user: row.user, userSql: row.user_sql, databaseSql: row.database_sql,
+        roles: row.roles,
+        relations: row.relations.map((x) => ({ name: x.name, sql: x.sql, kind: x.kind, entry: x.entry, schemaSql: x.schema_sql, owner: x.owner, owned: x.owned,
+            rowSecurity: x.row_security, privileges: x.privileges })),
+        schemas: row.schemas.map((s) => ({ name: s.name, sql: s.sql, owner: s.owner, owned: s.owned, create: s.create, publicCreate: s.public_create })),
+        definers: row.definers.map((d) => ({ name: d.name, owner: d.owner, ownerSuperuser: d.owner_super, callable: d.callable, publicCallable: d.public_callable,
+            triggers: d.triggers, eventTrigger: d.event_trigger, unchecked: d.unchecked && !d.event_trigger })),
+        foreignTables: row.foreign_tables, mappedServers: row.mapped_servers, adminOf: row.admin_of, createRole: row.create_role, serverRoles: row.server_roles,
+        missing: row.missing, taken: row.taken, rdsReplication: row.rds_replication,
+    };
+}
+const list = (xs) => xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`;
+/** "through writers", "granted to PUBLIC": how a role came to hold something it holds by another */
+function route(others) {
+    const roles = others.filter((r) => r !== "PUBLIC");
+    const parts = [...(roles.length ? [`through ${list(roles)}, which it is a member of`] : []), ...(others.includes("PUBLIC") ? ["granted to PUBLIC, which every role is"] : [])];
+    return parts.length ? ` (${parts.join("; ")})` : "";
+}
+/** " (a partition of public.events)": how a relation that is not a synced table reaches one */
+function via(x) {
+    const said = { table: "", partition: ` (a partition of ${x.entry})`, child: ` (a child of ${x.entry}, by INHERITS: its rows are ${x.entry}'s)`,
+        parent: ` (an INHERITS parent of ${x.entry}: an UPDATE, DELETE or TRUNCATE of it reaches ${x.entry}'s rows)`,
+        referenced: ` (a foreign key's ON DELETE or ON UPDATE action carries its changes to ${x.entry}, as its owner)`,
+        view: ` (a view that writes ${x.entry})`, rule: ` (its rules write ${x.entry})` };
+    return said[x.kind];
+}
+const WHY = "Mason only reads, so a role that may write lets a Mason bug or a stolen URL change your database";
+/** The checks of the role, from its facts: one warning per code that applies, else one line saying it only reads. */
+export function roleChecks(f, ask) {
+    const fix = readOnlyFix(f, ask);
+    const warn = (code, detail) => ({ name: "role", ok: true, warn: true, code, detail: `${detail}. ${WHY}: sync as a role that only reads`, fix });
+    const out = [];
+    const supers = f.roles.filter((r) => r.superuser);
+    if (supers.length) {
+        // a superuser may do everything: what else it holds follows from it, and is not said again
+        const self = supers.some((r) => r.self);
+        out.push(warn("role_superuser", self ? `${f.user} is a superuser: it may write to, alter or drop anything on this database`
+            : `${f.user} is a member of ${list(supers.map((r) => r.name))}, a superuser: it may SET ROLE to it and write to, alter or drop anything on this database`));
+        return out;
+    }
+    const bypass = f.roles.filter((r) => r.bypassrls);
+    if (bypass.length) {
+        out.push(warn("role_bypassrls", `${f.user} has BYPASSRLS${route(bypass.filter((r) => !r.self).map((r) => r.name))}: row-level security does not apply to it, on any table`));
+    }
+    const owned = f.relations.filter((x) => x.owned);
+    if (owned.length) {
+        const others = [...new Set(owned.map((x) => x.owner).filter((o) => o !== f.user))];
+        out.push(warn("role_owns_table", `${f.user} owns ${list(owned.map((x) => `${x.name}${via(x)}`))}${route(others)}: ` +
+            "an owner may write to, alter or drop a table whatever is granted"));
+    }
+    // an owner holds every privilege on its table: the owner's line said it
+    const writable = f.relations.filter((x) => !x.owned && x.privileges.length > 0);
+    if (writable.length) {
+        const held = writable.map((x) => {
+            const privs = WRITE_PRIVILEGES.filter((p) => x.privileges.some((g) => g.privileges.includes(p)));
+            const others = x.privileges.filter((g) => g.role !== f.user).map((g) => g.role);
+            return `${privs.join(", ")} on ${x.name}${via(x)}${route(others)}`;
+        });
+        out.push(warn("role_writes_table", `${f.user} may ${held.join("; ")}`));
+    }
+    const creates = f.schemas.filter((s) => s.create.length > 0 || s.publicCreate);
+    if (creates.length) {
+        const held = creates.map((s) => `CREATE in schema ${s.name}${s.owned ? ` (${s.owner === f.user ? "it owns the schema" : `${s.owner}, which owns the schema`}: it may drop what is in it too)` : route([...s.create.filter((r) => r !== f.user), ...(s.publicCreate ? ["PUBLIC"] : [])])}`);
+        out.push(warn("role_creates_in_schema", `${f.user} may ${held.join("; ")}: it may make tables and functions beside the synced ones`));
+    }
+    if (f.foreignTables.length || f.mappedServers.length) {
+        const held = [...(f.foreignTables.length ? [`may write the foreign table(s) ${list(f.foreignTables)}`] : []),
+            ...(f.mappedServers.length ? [`has a user mapping (its own or PUBLIC's) on ${list(f.mappedServers)}, which it may use`] : [])];
+        out.push(warn("role_reaches_foreign_server", `${f.user} ${held.join(", and ")}: what it sends there runs as the mapping's user, and the server may be this very database`));
+    }
+    if (f.adminOf.length || f.createRole || f.serverRoles.length) {
+        const held = [...(f.adminOf.length ? [`has ADMIN OPTION on ${list(f.adminOf)}: it may grant itself that role and its privileges`] : []),
+            ...(f.createRole ? ["has CREATEROLE, which before Postgres 16 lets it grant itself any role but a superuser"] : []),
+            ...(f.serverRoles.length ? [`holds ${list(f.serverRoles)}: the server's programs or files, as its operating-system user`] : [])];
+        out.push(warn("role_may_become_another", `${f.user} ${held.join("; ")}`));
+    }
+    // SECURITY DEFINER code: what it writes is in its body, which the catalog does not say, so it is LISTED for a person
+    // to review, never "fixed" by a statement that changes another role's privileges, and never taken for "only reads"
+    const definers = definerLine(f);
+    if (out.length)
+        return definers === null ? out : [...out, { name: "role", ok: true, warn: true, code: "role_may_run_definer_code", detail: `${f.user} ${definers}` }];
+    const unread = f.missing.length ? ` (not asked of ${list(f.missing)}, which the database does not have: mason start says so)` : "";
+    const synced = f.relations.filter((x) => x.kind === "table").length;
+    const itself = "not a superuser, no BYPASSRLS, no ADMIN OPTION, no server roles, no foreign server" + (synced ? `, and it neither owns nor may write to the ${synced} synced table(s) — ` +
+        "nor to their partitions, inheritance children or parents, the tables their foreign keys act on, or the views and rules that write them — " +
+        "nor CREATE in their schemas" : ", and no table is added yet (the tables are asked once one is)");
+    if (definers !== null)
+        return [{ name: "role", ok: true, warn: true, code: "role_may_run_definer_code", detail: `${f.user} may not write the synced tables itself: ${itself}. But it ${definers}${unread}` }];
+    return [{ name: "role", ok: true, detail: `${f.user} only reads: ${itself}, and it reaches no SECURITY DEFINER code whose owner may write${unread}` }];
+}
+/** "may run 2 SECURITY DEFINER function(s) of roles that may write the synced tables: …; what they write is not known", or null */
+function definerLine(f) {
+    if (!f.definers.length)
+        return null;
+    const each = f.definers.map((d) => {
+        const how = [...(d.callable ? [d.publicCallable ? "every role may call it (PUBLIC's EXECUTE)" : "it may call it"] : []),
+            ...(d.triggers.length ? [`a trigger on ${list(d.triggers)}, which it may write, calls it`] : []),
+            ...(d.eventTrigger ? ["an event trigger calls it on any DDL, even one refused, never asking EXECUTE"] : []),
+            ...(d.unchecked ? ["Postgres calls it for an aggregate, a type, an operator or the like, never asking EXECUTE"] : [])];
+        return `${d.name} runs as ${d.owner}${d.ownerSuperuser ? ", a superuser" : ", which may write the synced tables"}: ${how.join("; ")}`;
+    });
+    return `may run ${f.definers.length} SECURITY DEFINER function(s) of roles that may write the synced tables — ${each.join("; ")}. ` +
+        "What they write is not known (it is in their bodies, which the catalog does not read): review each, whether it writes a synced table and who may reach it";
+}
+/** The line a check is when the role could not be asked: said, never taken for "only reads". */
+export function roleUnknown(why) {
+    return { name: "role", ok: null, code: "role_unknown", detail: `could not tell whether the user Mason connects as may write to the database: ${why}` };
+}
+/**
+ * The URL `url` with `role` as its user and a placeholder for its password, nothing else of it changed: built from what
+ * `shownUrl` shows (src/cli/preflight.ts, issue 541), so no part the URL is not read with is ever printed; a value it
+ * does not show is said in words.
+ */
+export function readerUrl(url, role) {
+    const shown = shownUrl(url);
+    if (shown === null)
+        return `the database's URL with ${role} and its password as the user and password`;
+    const u = new URL(shown);
+    return `${u.protocol}//${role}:<its password>@${u.host}${u.pathname}${u.search}`;
+}
+/**
+ * THE WAY OUT, as the statements the database's owner runs, then the line of the project to change: a role that may
+ * LOGIN and SELECT the synced tables and nothing else — REPLICATION where a table streams, and the publication made by
+ * the owner when Mason would make its own (CREATE PUBLICATION … FOR TABLE needs the tables' owner); a policy for it where
+ * a table has row-level security (the new role would read no row of it). It NEVER prints a statement that changes any
+ * role's privileges but the new one's (PR 572's review: a REVOKE … FROM PUBLIC of a policy's function, run as printed,
+ * broke the application's own reads): what PUBLIC holds, and the SECURITY DEFINER code every role reaches, the new role
+ * holds and reaches too, and is SAID in a comment, for the database's owner to decide.
+ */
+export function readOnlyFix(f, ask) {
+    let role = READER_ROLE;
+    for (let n = 2; f.taken.includes(role); n++)
+        role = `${READER_ROLE}${n}`;
+    const tables = f.relations.filter((x) => x.kind === "table");
+    const schemas = [...new Set(tables.map((x) => x.schemaSql))];
+    const replication = ask.replicated.length > 0;
+    const replicating = replication && !f.rdsReplication;
+    const lines = [`-- as the database's owner (on the primary):`,
+        `CREATE ROLE ${role} LOGIN${replicating ? " REPLICATION" : ""} PASSWORD '<a new password>';`];
+    if (replication && f.rdsReplication)
+        lines.push(`GRANT rds_replication TO ${role};`);
+    lines.push(`GRANT CONNECT ON DATABASE ${f.databaseSql} TO ${role};`);
+    if (tables.length) {
+        lines.push(`GRANT USAGE ON SCHEMA ${schemas.join(", ")} TO ${role};`, `GRANT SELECT ON ${tables.map((x) => x.sql).join(", ")} TO ${role};`);
+    }
+    else {
+        lines.push(`-- and GRANT USAGE ON SCHEMA <schema>, SELECT ON <table> TO ${role}, for each table you add`);
+    }
+    for (const x of tables.filter((t) => t.rowSecurity))
+        lines.push(`CREATE POLICY ${role}_reads ON ${x.sql} FOR SELECT TO ${role} USING (true);   -- row-level security: else it reads no row`);
+    // PUBLIC's privileges are every role's, the new one's too: said for the database's owner to decide, never revoked here
+    const publicCreate = f.schemas.filter((s) => s.publicCreate);
+    if (publicCreate.length)
+        lines.push(`-- PUBLIC may CREATE in schema ${list(publicCreate.map((s) => s.name))} (the default before Postgres 15), so the new role may too: whether PUBLIC should is the owner's to decide, for every role`);
+    for (const x of f.relations) {
+        const pub = x.privileges.find((g) => g.role === "PUBLIC");
+        if (pub)
+            lines.push(`-- PUBLIC holds ${pub.privileges.join(", ")} on ${x.name}, so the new role does too: whether PUBLIC should is the owner's to decide, for every role`);
+    }
+    // what Mason's own would carry (src/duck/sync.ts ensurePublication): the replicated tables, every change
+    const published = tables.filter((x) => ask.replicated.includes(x.entry));
+    const ownPublication = ask.publication === null && published.length > 0;
+    if (ownPublication) {
+        lines.push(`CREATE PUBLICATION ${role} FOR TABLE ${published.map((x) => x.sql).join(", ")} WITH (publish = 'insert, update, delete, truncate');   -- Mason's own needs the tables' owner`);
+    }
+    // what every role reaches, the new one too, is SAID, never changed: a statement that changed PUBLIC's would change
+    // every role's, the application's included (PR 572's review: a REVOKE of a policy's function broke the app's reads)
+    const everyone = f.definers.filter((d) => d.publicCallable || d.eventTrigger || d.unchecked);
+    if (everyone.length)
+        lines.push(`-- the new role may still run ${list(everyone.map((d) => d.name))}, as every role may (SECURITY DEFINER): mason doctor lists them to review`);
+    if (f.mappedServers.length)
+        lines.push(`-- a user mapping FOR PUBLIC on ${list(f.mappedServers)} would serve it too: map the roles that need it by name`);
+    lines.push("-- and GRANT SELECT ON each view Mason should serve: it serves the views the role it connects as may read");
+    // the app's own DATABASE_URL stays the app's: Mason's gets a variable of its own
+    const variable = ask.urlVariable === null || ask.urlVariable === "DATABASE_URL" ? "MASON_DATABASE_URL" : ask.urlVariable;
+    const own = variable !== ask.urlVariable;
+    lines.push(`then: set ${variable}=${readerUrl(ask.url, role)} ${own ? "in .env" : `where it is set now (${ask.urlFrom})`}` +
+        `${own ? ` and write url: \${${variable}} in ${ask.file}` : ""}${ownPublication ? `${own ? "," : " and"} publication: ${role} at its top` : ""}` +
+        "; mason doctor checks it again, and a running Mason reads it at its next start (mason stop, then mason start)");
+    return lines.join("\n");
+}