tablewalk 0.0.1

package/dist/adapters/postgres.js

@@ -0,0 +1,1000 @@
+/**
+ * Postgres adapter, on `pg`.
+ *
+ * Where SQLite hands you a per-table PRAGMA, Postgres hands you a catalog you
+ * can query in one shot. That difference is worth exploiting: introspection
+ * here is three queries total regardless of how many tables exist, which
+ * matters the first time someone points this at a schema with four hundred of
+ * them.
+ *
+ * The queries below read `information_schema` for columns and `pg_catalog` for
+ * keys and row estimates. `information_schema` is the portable half but it has
+ * no cheap row count and describes composite keys awkwardly; `pg_catalog`
+ * carries both, at the cost of being Postgres-specific. Since we are already
+ * inside the Postgres adapter, that cost is zero.
+ */
+import { POSTGRES_STYLE, buildWhere, clampLimit, boundStatement, dedupe, looksWrappable, refuseStacked, trimStatement, clampOffset, Refusal, Serial, } from './adapter.js';
+import { coerceForColumn, deleteRuleOf } from '../shared/schema.js';
+import { checkVocabulary, checksIn } from '../shared/vocabulary.js';
+import { compileView, compileViewCount } from '../shared/view.js';
+import { compileBreakdown, compileBreakdownCount } from '../shared/breakdown.js';
+/** Schemas that are the server's own business, not the user's data. */
+const SYSTEM_SCHEMAS = ['pg_catalog', 'information_schema', 'pg_toast'];
+/** The first check that pins this column's values, if any does. */
+function firstVocabulary(checks, column) {
+    for (const check of checks) {
+        const values = checkVocabulary(check, column);
+        if (values)
+            return values;
+    }
+    return undefined;
+}
+/**
+ * Hand dates and timestamps back as the text the server stores.
+ *
+ * `pg` parses `timestamp without time zone` into a JavaScript `Date`, which
+ * has no such thing as "without time zone" — so it reads the value in the
+ * *process's* offset and prints it back in UTC. A row written 09:00 came out
+ * of this adapter as `2026-08-01T13:00:00.000Z`: not a formatting difference,
+ * a different time, on a value the column explicitly says has no zone. The
+ * MySQL adapter avoids the whole question with `dateStrings: true`; `pg` has
+ * no such option, so the parsers are replaced instead.
+ *
+ * `timestamptz` is included even though it is a real instant. Its text form
+ * carries the offset, which is more information than a `Date` rendered in
+ * whatever zone the browser happens to be in — and tablewalk's job is to show
+ * what is stored.
+ *
+ * Set on the module, because that is the only place `pg` keeps them. Done
+ * once, and idempotent, so opening a second connection does not repeat it.
+ */
+const PG_DATE_OIDS = [
+    1082, // date
+    1083, // time
+    1114, // timestamp without time zone
+    1184, // timestamp with time zone
+    1266, // time with time zone
+];
+let datesKept = false;
+function keepDatesAsText(pg) {
+    if (datesKept)
+        return;
+    const mod = pg;
+    const types = mod.types ?? mod.default?.types;
+    /* A `pg` that does not expose `types` is one this cannot fix, and a
+       connection is worth more than a formatting guarantee. */
+    if (!types?.setTypeParser)
+        return;
+    for (const oid of PG_DATE_OIDS)
+        types.setTypeParser(oid, (value) => value);
+    datesKept = true;
+}
+export class PostgresAdapter {
+    connectionString;
+    label;
+    schemas;
+    dialect = 'postgres';
+    client = null;
+    /* The second connection, opened the first time a write is actually applied.
+       See `writeHandle`. */
+    writer = null;
+    /* Every write on that connection, one at a time. See `Serial`. */
+    writes = new Serial();
+    constructor(connectionString, label = redact(connectionString), 
+    /** Restrict to these schemas. Empty means every non-system schema. */
+    schemas = []) {
+        this.connectionString = connectionString;
+        this.label = label;
+        this.schemas = schemas;
+    }
+    async conn() {
+        if (this.client)
+            return this.client;
+        /* Imported lazily, and through a variable, so `pg` is only required when
+           someone actually opens a Postgres URL. The indirection also stops the
+           type checker demanding the package be installed to compile the file. */
+        const specifier = 'pg';
+        const pg = (await import(specifier).catch(() => {
+            throw new Error('Postgres support needs the "pg" package. Install it with: npm install pg');
+        }));
+        const Client = pg.Client ?? pg.default?.Client;
+        if (!Client)
+            throw new Error('Could not find a Client export in the "pg" package.');
+        keepDatesAsText(pg);
+        const client = new Client({ connectionString: this.connectionString });
+        await client.connect();
+        /* Belt and braces alongside the query builder: even if a read somehow
+           compiled to a write, the transaction would refuse it. */
+        await client.query('SET default_transaction_read_only = on');
+        await client.query("SET statement_timeout = '30s'");
+        /* A dead client must not be handed out again.
+        
+           The cached client was returned for the life of the process with no
+           liveness check, so a server restart or a dropped socket left every
+           later request failing identically — the same error for ever, with no
+           way back short of a manual refresh, on a connection the database itself
+           had long since made available again. `pg` emits `error` on a client
+           whose connection has gone; forgetting it there means the next `conn()`
+           dials a new one, which is what "reconnect" means for a pool of size
+           one.
+        
+           The listener is required, not optional: an `error` event with nothing
+           listening is an unhandled `'error'` on an EventEmitter, which takes the
+           process down. A read-only database browser crashing because the
+           database bounced would be a poor trade for a stack trace. */
+        client.on?.('error', () => {
+            if (this.client === client)
+                this.client = null;
+        });
+        this.client = client;
+        return client;
+    }
+    /**
+     * Run a statement the user wrote.
+     *
+     * The session already carries `default_transaction_read_only = on`, and for
+     * everything else in this adapter that is enough, because every statement is
+     * one this file built. It is **not** enough here: `SET
+     * default_transaction_read_only = off` is itself a statement, and a user who
+     * typed it followed by a `DELETE` would get both.
+     *
+     * `BEGIN READ ONLY` is the version that holds. A transaction opened read-only
+     * cannot be promoted from inside it — Postgres refuses `SET TRANSACTION READ
+     * WRITE` once the transaction has begun — so the guarantee stops depending on
+     * what the statement does or does not contain. The `ROLLBACK` afterwards also
+     * discards any session state the statement set, so one run cannot change what
+     * the next one means.
+     *
+     * The rollback runs in a `finally`: a statement that errors has still opened
+     * a transaction, and leaving it open would leave the connection in an aborted
+     * state where every later query fails with "current transaction is aborted".
+     *
+     * `write: true` is the other half, and it is a different request rather than
+     * a relaxation of this one: a separate handle, no READ ONLY transaction, and
+     * a decision made further up about whether this connection may write at all.
+     * The two paths share the statement text and nothing else.
+     */
+    async runSql(request) {
+        const stacked = refuseStacked(request.text);
+        if (stacked)
+            throw new Error(stacked);
+        const limit = clampLimit(request.limit);
+        /* A write is never wrapped in a bounding subquery: `UPDATE … RETURNING`
+           inside `SELECT * FROM (…)` is a different statement, and one Postgres
+           refuses outright. The caller asked for this text; it runs as typed. */
+        const bounded = !request.write && looksWrappable(request.text);
+        const text = bounded ? boundStatement(request.text, limit) : trimStatement(request.text);
+        if (request.write) {
+            /* On the write handle, and outside the READ ONLY transaction every other
+               statement here gets — which is the whole difference. Whether this is
+               allowed at all was decided before the request arrived: the connection
+               has to be marked writable in the config, and that check does not live
+               in the adapter.
+      
+               No wrapper transaction of our own. One statement is already atomic in
+               Postgres, and a BEGIN/COMMIT around it would only add a way to leave a
+               transaction open on a connection that outlives the request. */
+            const write = await this.writeHandle();
+            const started = performance.now();
+            const result = await write.query(text, []);
+            return {
+                /* A write that returns rows — `RETURNING` — is worth showing, and one
+                   that does not returns an empty grid rather than a fabricated one. */
+                columns: dedupe(result.fields?.map((f) => f.name) ?? []),
+                rows: (result.rows ?? []).map((row) => Object.values(toJsonSafe(row)).map(valueSafe)),
+                ms: Math.round(performance.now() - started),
+                truncated: false,
+                bounded: false,
+                affected: Number(result.rowCount ?? 0),
+                sql: { text, params: [] },
+            };
+        }
+        const db = await this.conn();
+        const started = performance.now();
+        /* SET LOCAL dies with the transaction, so the session's 30s cap is
+           untouched — and the floor stops a caller asking for a timeout so low
+           that even the fast path loses races to it. */
+        const cap = request.timeoutMs === undefined
+            ? undefined
+            : Math.max(100, Math.min(30_000, Math.floor(request.timeoutMs)));
+        await db.query('BEGIN READ ONLY');
+        try {
+            if (cap !== undefined)
+                await db.query(`SET LOCAL statement_timeout = ${cap}`);
+            /* `rowMode: 'array'` so two output columns of the same name keep both
+               values; the default object rows would let the second overwrite the
+               first. `values: []` keeps this on the extended protocol, which carries
+               exactly one statement — a second line of defence behind the stacking
+               check above. */
+            let wrapped = bounded;
+            const result = await db
+                .query({ text, values: [], rowMode: 'array' })
+                .catch(async (err) => {
+                /* The wrap is an optimisation that is allowed to fail — not every
+                   legal statement survives being made a derived table. Run as
+                   written and reported as unbounded. The transaction has to be
+                   restarted: a failed statement aborts it, and every later query in
+                   it would fail with "current transaction is aborted". */
+                if (!bounded)
+                    throw err;
+                wrapped = false;
+                await db.query('ROLLBACK');
+                await db.query('BEGIN READ ONLY');
+                if (cap !== undefined)
+                    await db.query(`SET LOCAL statement_timeout = ${cap}`);
+                return db.query({ text: trimStatement(request.text), values: [], rowMode: 'array' });
+            });
+            const truncated = result.rows.length > limit;
+            return {
+                columns: dedupe(result.fields.map((f) => f.name)),
+                rows: (truncated ? result.rows.slice(0, limit) : result.rows).map((row) => row.map(valueSafe)),
+                ms: Math.round(performance.now() - started),
+                truncated,
+                bounded: wrapped,
+                sql: { text: wrapped ? text : trimStatement(request.text), params: [] },
+            };
+        }
+        finally {
+            await db.query('ROLLBACK').catch(() => {
+                /* The connection is already unusable if this fails; the original error
+                   is the one worth reporting. */
+            });
+        }
+    }
+    /**
+     * EXPLAIN, plain — never the analysing variant that executes to time.
+     *
+     * `runSql`'s bounding wrap is precisely wrong here: a statement made a
+     * derived table is a different statement, with a different plan. The text
+     * goes to the planner as written, inside the same READ ONLY transaction
+     * every user statement gets — so even a smuggled write is only ever
+     * planned, and an execution attempt is the transaction's to refuse, not a
+     * string check's.
+     */
+    async explainSql(request) {
+        const stacked = refuseStacked(request.text);
+        if (stacked)
+            throw new Error(stacked);
+        const db = await this.conn();
+        const started = performance.now();
+        await db.query('BEGIN READ ONLY');
+        try {
+            const result = await db.query({
+                text: `EXPLAIN ${trimStatement(request.text)}`,
+                values: (request.params ?? []),
+                rowMode: 'array',
+            });
+            return {
+                plan: result.rows.map((r) => String(r[0])),
+                ms: Math.round(performance.now() - started),
+            };
+        }
+        finally {
+            await db.query('ROLLBACK').catch(() => { });
+        }
+    }
+    /**
+     * The planner's own statistics, read rather than computed.
+     *
+     * `pg_stats` already holds the null share, the distinct estimate, the most
+     * common values with their frequencies, and the histogram — ANALYZE paid
+     * for them, reading them touches no user table. The numbers are
+     * sample-based and stale until the next ANALYZE, which is what
+     * `source: 'statistics'` tells the caller; a column ANALYZE has never
+     * visited simply has no numbers, which beats invented ones.
+     */
+    async profile(table) {
+        const { schema, name } = await this.assertTable(table);
+        const db = await this.conn();
+        const started = performance.now();
+        const rel = await db.query(`SELECT CASE WHEN c.reltuples < 0 THEN NULL ELSE c.reltuples END AS approx_rows
+         FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1 AND c.relname = $2`, [schema, name]);
+        const approx = rel.rows[0]?.approx_rows;
+        const rows = approx == null ? undefined : Math.round(Number(approx));
+        /* Every live column, with its stats row where ANALYZE has made one.
+           `most_common_vals` and `histogram_bounds` are `anyarray`, which the
+           driver has no parser for; the ::text::text[] two-step turns them into
+           the text array it can parse. */
+        const stats = await db.query(`SELECT a.attname::text AS column,
+              format_type(a.atttypid, a.atttypmod) AS type,
+              s.null_frac,
+              s.n_distinct,
+              s.most_common_vals::text::text[] AS common_values,
+              s.most_common_freqs AS common_freqs,
+              s.histogram_bounds::text::text[] AS bounds
+         FROM pg_attribute a
+         JOIN pg_class c ON c.oid = a.attrelid
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         LEFT JOIN pg_stats s ON s.schemaname = n.nspname AND s.tablename = c.relname AND s.attname = a.attname
+        WHERE n.nspname = $1 AND c.relname = $2 AND a.attnum > 0 AND NOT a.attisdropped
+        ORDER BY a.attnum`, [schema, name]);
+        const columns = stats.rows.map((r) => {
+            /* Negative n_distinct is a ratio — "-0.3 of the rows are distinct" —
+               which only converts when a row estimate exists to multiply by. */
+            const distinct = r.n_distinct == null ? undefined
+                : Number(r.n_distinct) >= 0 ? Math.round(Number(r.n_distinct))
+                    : rows === undefined ? undefined
+                        : Math.round(-Number(r.n_distinct) * rows);
+            const common = r.common_values?.length && r.common_freqs?.length
+                ? r.common_values.map((v, i) => ({ value: v, frac: Number(r.common_freqs?.[i] ?? 0) }))
+                : undefined;
+            return {
+                column: r.column,
+                type: r.type,
+                nullFrac: r.null_frac == null ? undefined : Number(r.null_frac),
+                distinct,
+                /* The histogram's outer edges, as text from the sample. A column too
+                   uniform to earn a histogram gets no min/max — its common values
+                   sorted lexically would call 9 larger than 10. */
+                min: r.bounds?.length ? r.bounds[0] : undefined,
+                max: r.bounds?.length ? r.bounds[r.bounds.length - 1] : undefined,
+                common,
+            };
+        });
+        return { table, rows, columns, source: 'statistics', ms: Math.round(performance.now() - started) };
+    }
+    async introspect() {
+        const db = await this.conn();
+        const filterSchemas = this.schemas.length
+            ? `AND n.nspname = ANY($1)`
+            : `AND n.nspname <> ALL($1)`;
+        const schemaParam = this.schemas.length ? this.schemas : SYSTEM_SCHEMAS;
+        /* 1. Relations, with the planner's row estimate.
+              `reltuples` is an estimate, not a count, and is labelled as such in
+              the UI. An exact count on a large table is a sequential scan, which
+              is a strange thing for a schema browser to do on connect. */
+        const rels = await db.query(`SELECT n.nspname AS table_schema,
+              c.relname  AS table_name,
+              c.relkind  AS kind,
+              CASE WHEN c.reltuples < 0 THEN 0 ELSE c.reltuples END AS approx_rows,
+              obj_description(c.oid) AS comment
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relkind IN ('r','v','m','p','f')
+          ${filterSchemas}
+        ORDER BY n.nspname, c.relname`, [schemaParam]);
+        const relRows = rels.rows;
+        const wanted = new Set(relRows.map((r) => `${r.table_schema}.${r.table_name}`));
+        /* 2. Columns, in one pass over information_schema. */
+        const cols = await db.query(
+        /* `col_description` joined on rather than left out.
+        
+           A column comment is the table's own documentation — the one place a
+           schema explains itself — and the MySQL adapter has always read them
+           while this one did not, so the same database described in two engines
+           gave a different amount of help. It lives in `pg_description` rather
+           than `information_schema`, which is why it needs the join. */
+        `SELECT c.table_schema, c.table_name, c.column_name, c.data_type,
+              c.is_nullable, c.column_default, c.ordinal_position,
+              col_description(pc.oid, c.ordinal_position::int) AS comment,
+              /* Cast to text before aggregating: enumlabel has type "name",
+                 and the driver hands a name[] back as the literal string
+                 '{open,held,closed}' rather than an array — the same value,
+                 typed as something no caller can use. */
+              (SELECT array_agg(e.enumlabel::text ORDER BY e.enumsortorder)
+                 FROM pg_enum e
+                 JOIN pg_type t ON t.oid = e.enumtypid
+                 JOIN pg_namespace tn ON tn.oid = t.typnamespace
+                WHERE t.typname = c.udt_name AND tn.nspname = c.udt_schema) AS enum_labels
+         FROM information_schema.columns c
+         LEFT JOIN pg_namespace pn ON pn.nspname = c.table_schema
+         LEFT JOIN pg_class pc ON pc.relname = c.table_name AND pc.relnamespace = pn.oid
+        WHERE c.table_schema ${this.schemas.length ? '= ANY($1)' : '<> ALL($1)'}
+        ORDER BY c.table_schema, c.table_name, c.ordinal_position`, [schemaParam]);
+        /* Checks, for the other half of the vocabulary. A `status text CHECK
+           (status IN (...))` is far commoner in the wild than a real enum type,
+           and to anything reading the catalog it is an untyped text column unless
+           the constraint is read too. Postgres stores what it rewrote rather than
+           what was written, which `checkVocabulary` knows about. */
+        const checks = await db.query(`SELECT n.nspname AS table_schema, cl.relname AS table_name,
+              pg_get_constraintdef(co.oid) AS expression
+         FROM pg_constraint co
+         JOIN pg_class cl     ON cl.oid = co.conrelid
+         JOIN pg_namespace n  ON n.oid = cl.relnamespace
+        WHERE co.contype = 'c'
+          AND n.nspname ${this.schemas.length ? '= ANY($1)' : '<> ALL($1)'}`, [schemaParam]);
+        const checksByTable = new Map();
+        for (const row of checks.rows) {
+            const id = `${row.table_schema}.${row.table_name}`;
+            const list = checksByTable.get(id) ?? [];
+            /* `pg_get_constraintdef` returns `CHECK ((expr))`; the parser wants the
+               expression, and `checksIn` is the same unwrapping SQLite needs. */
+            list.push(...checksIn(row.expression));
+            checksByTable.set(id, list);
+        }
+        /* 3. Keys. `unnest ... WITH ORDINALITY` keeps composite key columns in
+              their declared order, which a plain array_agg over conkey would not
+              guarantee and which matters for a two-column join.
+    
+              `attname` is of type `name`, not `text`, so aggregating it yields
+              `name[]` — an array OID the driver has no parser for, which arrives
+              as the raw string "{a,b}" rather than an array. The ::text casts are
+              what make these come back as JavaScript arrays. */
+        const keys = await db.query(`SELECT con.conname AS constraint_name,
+              fn.nspname  AS from_schema,
+              f.relname   AS from_table,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord)
+                 FROM unnest(con.conkey) WITH ORDINALITY AS k(attnum, ord)
+                 JOIN pg_attribute a ON a.attrelid = f.oid AND a.attnum = k.attnum) AS from_columns,
+              tn.nspname  AS to_schema,
+              t.relname   AS to_table,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord)
+                 FROM unnest(con.confkey) WITH ORDINALITY AS k(attnum, ord)
+                 JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum) AS to_columns,
+              con.confdeltype AS delete_rule
+         FROM pg_constraint con
+         JOIN pg_class f      ON f.oid = con.conrelid
+         JOIN pg_namespace fn ON fn.oid = f.relnamespace
+         JOIN pg_class t      ON t.oid = con.confrelid
+         JOIN pg_namespace tn ON tn.oid = t.relnamespace
+        WHERE con.contype = 'f'`);
+        const pks = await db.query(`SELECT n.nspname AS table_schema,
+              c.relname AS table_name,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord)
+                 FROM unnest(con.conkey) WITH ORDINALITY AS k(attnum, ord)
+                 JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = k.attnum) AS columns
+         FROM pg_constraint con
+         JOIN pg_class c      ON c.oid = con.conrelid
+         JOIN pg_namespace n  ON n.oid = c.relnamespace
+        WHERE con.contype = 'p'`);
+        const pkByTable = new Map();
+        for (const row of pks.rows) {
+            pkByTable.set(`${row.table_schema}.${row.table_name}`, row.columns ?? []);
+        }
+        /* Only the leading column of each index.
+    
+           `indkey[0]` is the first key column, and it is the only one an ORDER BY
+           can be satisfied by — an index on (customer_id, opened_at) makes
+           `ORDER BY customer_id` free and `ORDER BY opened_at` a full sort. An
+           expression index has attnum 0 and joins to nothing, which drops it, as
+           it should: there is no bare column to sort by. */
+        const indexes = await db.query(`SELECT n.nspname AS table_schema,
+              c.relname AS table_name,
+              a.attname::text AS column_name
+         FROM pg_index i
+         JOIN pg_class c     ON c.oid = i.indrelid
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = i.indkey[0]
+        WHERE i.indisvalid`);
+        const indexedByTable = new Map();
+        for (const row of indexes.rows) {
+            const id = `${row.table_schema}.${row.table_name}`;
+            const set = indexedByTable.get(id) ?? new Set();
+            set.add(row.column_name);
+            indexedByTable.set(id, set);
+        }
+        const foreignKeys = [];
+        /* A column-level reference map, so the table view can show "this column
+           points there" without searching the whole key list per cell. */
+        const refByColumn = new Map();
+        for (const row of keys.rows) {
+            const from = `${row.from_schema}.${row.from_table}`;
+            const to = `${row.to_schema}.${row.to_table}`;
+            // Keys can point out of the browsed schema set; those edges lead
+            // nowhere the user can click, so they are dropped rather than shown broken.
+            if (!wanted.has(from) || !wanted.has(to))
+                continue;
+            foreignKeys.push({
+                name: row.constraint_name,
+                from: { table: from, columns: row.from_columns ?? [] },
+                to: { table: to, columns: row.to_columns ?? [] },
+                onDelete: deleteRuleOf(row.delete_rule),
+            });
+            (row.from_columns ?? []).forEach((col, i) => {
+                refByColumn.set(`${from}.${col}`, {
+                    table: to,
+                    column: row.to_columns?.[i] ?? row.to_columns?.[0] ?? '',
+                });
+            });
+        }
+        const columnsByTable = new Map();
+        for (const row of cols.rows) {
+            const id = `${row.table_schema}.${row.table_name}`;
+            if (!wanted.has(id))
+                continue;
+            const list = columnsByTable.get(id) ?? [];
+            list.push(row);
+            columnsByTable.set(id, list);
+        }
+        const tables = relRows.map((r) => {
+            const id = `${r.table_schema}.${r.table_name}`;
+            const pk = new Set(pkByTable.get(id) ?? []);
+            const tableChecks = checksByTable.get(id) ?? [];
+            const columns = (columnsByTable.get(id) ?? []).map((c) => ({
+                name: c.column_name,
+                type: c.data_type,
+                nullable: c.is_nullable === 'YES',
+                primaryKey: pk.has(c.column_name),
+                references: refByColumn.get(`${id}.${c.column_name}`),
+                default: c.column_default ?? undefined,
+                comment: c.comment ?? undefined,
+                /* The type wins where there is one: an enum's labels are the whole
+                   truth, while a check is one rule among however many the table has. */
+                allowed: c.enum_labels?.length
+                    ? c.enum_labels
+                    : firstVocabulary(tableChecks, c.column_name),
+            }));
+            return {
+                name: r.table_name,
+                schema: r.table_schema,
+                id,
+                columns,
+                approxRows: Math.max(0, Math.round(Number(r.approx_rows) || 0)),
+                comment: r.comment ?? undefined,
+                // Views and materialised views are read-only; foreign tables are
+                // remote. All three are worth flagging rather than silently listing.
+                isView: r.kind === 'v' || r.kind === 'm' || r.kind === 'f',
+                indexed: [...(indexedByTable.get(id) ?? [])],
+            };
+        });
+        return {
+            label: this.label,
+            dialect: this.dialect,
+            tables,
+            foreignKeys,
+            readAt: new Date().toISOString(),
+        };
+    }
+    async query(request) {
+        const db = await this.conn();
+        const { schema, name } = await this.assertTable(request.table);
+        const qualified = `${POSTGRES_STYLE.quote(schema)}.${POSTGRES_STYLE.quote(name)}`;
+        const where = buildWhere(request.filter, POSTGRES_STYLE);
+        const cols = request.columns?.length
+            ? request.columns.map((c) => POSTGRES_STYLE.quote(c)).join(', ')
+            : '*';
+        const order = request.orderBy?.length
+            ? ' ORDER BY ' +
+                request.orderBy
+                    .map((o) => `${POSTGRES_STYLE.quote(o.column)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`)
+                    .join(', ')
+            : '';
+        /* Every read is bounded. There is no code path that reaches the database
+           without a LIMIT, including one that forgot to ask for one. */
+        const limit = clampLimit(request.limit);
+        /* LIMIT and OFFSET continue the placeholder numbering the WHERE clause
+           started, which is the one thing Postgres needs that SQLite does not. */
+        const n = where.params.length;
+        const text = `SELECT ${cols} FROM ${qualified}${where.text}${order} LIMIT $${n + 1} OFFSET $${n + 2}`;
+        const params = [...where.params, limit, clampOffset(request.offset)];
+        const started = performance.now();
+        const result = await db.query(text, params);
+        const ms = Math.round(performance.now() - started);
+        return {
+            // Taking columns from `fields` rather than the first row means an empty
+            // result still renders its headers instead of collapsing to nothing.
+            columns: result.fields.map((f) => f.name),
+            rows: result.rows.map(toJsonSafe),
+            ms,
+            sql: { text, params },
+        };
+    }
+    /**
+     * Run a compiled view.
+     *
+     * Note what is *not* here: any check that the tables named in the view
+     * exist. `compileView` resolves the base table and every hop against the
+     * introspected catalog and refuses anything it cannot find, so the only
+     * identifiers that reach the quoting step are ones the catalog produced.
+     * The user's contribution — the values — never leaves the parameter array.
+     *
+     * The dialect difference this exercises is placeholder numbering:
+     * `POSTGRES_STYLE` counts $1..$n across the whole statement, and the joins
+     * sitting between the SELECT list and the WHERE clause are exactly what
+     * makes an off-by-one here easy and invisible.
+     */
+    async runView(view, offset = 0) {
+        const db = await this.conn();
+        const schema = await this.schema();
+        const compiled = compileView(schema, view, POSTGRES_STYLE, offset);
+        const started = performance.now();
+        const result = await db.query(compiled.text, compiled.params);
+        const ms = Math.round(performance.now() - started);
+        return {
+            columns: compiled.columns.map((c) => c.name),
+            rows: result.rows.map(toJsonSafe),
+            ms,
+            sql: { text: compiled.text, params: compiled.params },
+            resolved: compiled.columns,
+            joins: compiled.joins,
+        };
+    }
+    async runBreakdown(breakdown, offset = 0) {
+        const db = await this.conn();
+        const compiled = compileBreakdown(await this.schema(), breakdown, POSTGRES_STYLE, offset);
+        const started = performance.now();
+        const result = await db.query(compiled.text, compiled.params);
+        return {
+            columns: compiled.columns.map((c) => c.name),
+            rows: result.rows.map(toJsonSafe),
+            ms: Math.round(performance.now() - started),
+            sql: { text: compiled.text, params: compiled.params },
+            resolved: compiled.columns,
+        };
+    }
+    async countBreakdown(breakdown) {
+        const db = await this.conn();
+        const compiled = compileBreakdownCount(await this.schema(), breakdown, POSTGRES_STYLE);
+        const result = await db.query(compiled.text, compiled.params);
+        return Number(result.rows[0]?.n ?? 0);
+    }
+    async countView(view) {
+        const db = await this.conn();
+        const compiled = compileViewCount(await this.schema(), view, POSTGRES_STYLE);
+        const result = await db.query(compiled.text, compiled.params);
+        return Number(result.rows[0]?.n ?? 0);
+    }
+    /* Introspection here is three catalog queries; a view preview runs on every
+       keystroke. Caching it is the difference between a live preview and a
+       stutter. The registry refreshes by discarding the adapter, so a stale
+       cache cannot outlive an explicit reload. */
+    cachedSchema = null;
+    async schema() {
+        if (!this.cachedSchema)
+            this.cachedSchema = await this.introspect();
+        return this.cachedSchema;
+    }
+    /**
+     * The planner's row estimate, straight from `pg_class`.
+     *
+     * `reltuples` is what the planner itself uses to decide how to run a query,
+     * so it is the number Postgres is already trusting. It is -1 on a table that
+     * has never been analysed, which is a "do not know" rather than a zero —
+     * returning undefined there gets an exact count instead of confidently
+     * reporting an empty table that is not empty.
+     */
+    async estimateCount(table) {
+        const db = await this.conn();
+        const { schema, name } = await this.assertTable(table);
+        const result = await db.query(`SELECT c.reltuples AS n
+         FROM pg_class c JOIN pg_namespace ns ON ns.oid = c.relnamespace
+        WHERE ns.nspname = $1 AND c.relname = $2`, [schema, name]);
+        const n = Number(result.rows[0]?.n);
+        if (!Number.isFinite(n) || n < 0)
+            return undefined;
+        return Math.round(n);
+    }
+    async count(table, filter) {
+        const db = await this.conn();
+        const { schema, name } = await this.assertTable(table);
+        const where = buildWhere(filter, POSTGRES_STYLE);
+        const text = `SELECT COUNT(*) AS n FROM ${POSTGRES_STYLE.quote(schema)}.${POSTGRES_STYLE.quote(name)}${where.text}`;
+        const result = await db.query(text, where.params);
+        return Number(result.rows[0]?.n ?? 0);
+    }
+    /**
+     * The write path, on its own handle.
+     *
+     * `this.client` carries `default_transaction_read_only = on` for the life of
+     * the process, so browsing can never write no matter what the UI believes.
+     * A second connection — without that setting — is opened the first time an
+     * edit is actually applied, and not before: a connection that can write
+     * should exist because somebody wrote, not because somebody connected.
+     *
+     * Every guard below is the SQLite adapter's, one for one. An edit refused on
+     * SQLite and allowed on Postgres would mean the safety of a cell editor
+     * depended on which database it was pointed at.
+     */
+    async writeHandle() {
+        if (this.writer)
+            return this.writer;
+        const specifier = 'pg';
+        const pg = (await import(specifier));
+        const Client = (pg.Client ?? pg.default?.Client);
+        const client = new Client({ connectionString: this.connectionString });
+        await client.connect();
+        await client.query("SET statement_timeout = '30s'");
+        // The same liveness rule as the read handle: a dead client must not be
+        // handed out again, and an unheard 'error' event ends the process.
+        client.on?.('error', () => {
+            if (this.writer === client)
+                this.writer = null;
+        });
+        this.writer = client;
+        return client;
+    }
+    /**
+     * A table's columns as the catalog has them now, not as they were on connect.
+     *
+     * `information_schema` would do for the names and types, but not for the
+     * primary key — it describes a composite one across two more views — and
+     * the key is the whole safety argument for a write. `pg_catalog` answers
+     * both in one query, and this is the Postgres adapter, so being
+     * Postgres-specific costs nothing.
+     *
+     * Read per write rather than from the cached schema: a column added since
+     * the connection opened is a column the editor should be able to write, and
+     * one dropped since is one it must not.
+     */
+    async columnsOf(schema, name) {
+        const db = await this.conn();
+        const result = await db.query(`SELECT a.attname AS name,
+              format_type(a.atttypid, a.atttypmod) AS type,
+              a.attnotnull AS notnull,
+              COALESCE(k.is_pk, false) AS is_pk
+         FROM pg_attribute a
+         JOIN pg_class c ON c.oid = a.attrelid
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         LEFT JOIN LATERAL (
+           SELECT true AS is_pk FROM pg_index i
+            WHERE i.indrelid = c.oid AND i.indisprimary AND a.attnum = ANY (i.indkey)
+         ) k ON true
+        WHERE n.nspname = $1 AND c.relname = $2
+          AND a.attnum > 0 AND NOT a.attisdropped
+        ORDER BY a.attnum`, [schema, name]);
+        return result.rows;
+    }
+    /**
+     * Update one row, having proved it is one row.
+     *
+     * The pre-flight count runs on the *read* handle, so the check that decides
+     * whether to write cannot itself write. A key that matches anything other
+     * than exactly one row stops here rather than at the UPDATE — the danger in
+     * a cell editor was never injection, it is a WHERE broader than its author
+     * believed.
+     */
+    async update(request) {
+        return this.writes.run(() => this.updateNow(request));
+    }
+    async updateNow(request) {
+        const found = await this.assertTable(request.table);
+        const id = `${found.schema}.${found.name}`;
+        /* Postgres updates through a simple view, and the update lands on the
+           table underneath. Refused: what the editor showed and what changed are
+           then two different objects. */
+        if (found.isView)
+            throw new Refusal(`${id} is a view, so no single row can be identified.`);
+        const meta = await this.columnsOf(found.schema, found.name);
+        const pk = meta.filter((c) => c.is_pk).map((c) => c.name);
+        if (!pk.length)
+            throw new Refusal(`${id} has no primary key, so no single row can be identified.`);
+        const keyColumns = Object.keys(request.key);
+        /* The key must be the whole primary key and nothing else. A partial key
+           would let a two-column key match a whole group of rows, and extra
+           columns would let the caller widen the match. */
+        const same = keyColumns.length === pk.length && pk.every((c) => keyColumns.includes(c));
+        if (!same)
+            throw new Refusal(`Updating ${id} needs exactly its primary key (${pk.join(', ')}).`);
+        const entries = Object.entries(request.values ?? {});
+        if (!entries.length)
+            throw new Refusal('Nothing to update.');
+        const applied = {};
+        for (const [column, raw] of entries) {
+            const declared = meta.find((c) => c.name === column);
+            if (!declared)
+                throw new Refusal(`${id} has no column called "${column}".`);
+            if (pk.includes(column)) {
+                // Editing a key in place silently repoints every row that referenced
+                // it, or fails on the constraint. Neither belongs behind an editor.
+                throw new Refusal(`"${column}" is part of the primary key and cannot be edited here.`);
+            }
+            /* Coerced against the declared type, because everything typed into a
+               text box arrives as a string — and Postgres, unlike SQLite, rejects
+               "17901" for a numeric column rather than quietly taking it. */
+            applied[column] = coerceForColumn(declared.type || '', raw);
+            if (applied[column] === null && declared.notnull) {
+                throw new Refusal(`"${column}" is NOT NULL and cannot be emptied.`);
+            }
+        }
+        const filter = {
+            groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
+        };
+        const matches = await this.count(id, filter);
+        if (matches !== 1) {
+            throw new Refusal(`Refused: that key matches ${matches} rows, not 1. An update is only allowed when it is certain which row it changes.`);
+        }
+        /* The WHERE is built after the SET, so its placeholders continue the same
+           numbering — `$1, $2` for the assignments, `$3…` for the key. Postgres
+           numbers parameters rather than taking them in order, which is the one
+           place this differs from the other two adapters. */
+        const columns = Object.keys(applied);
+        const assignments = columns
+            .map((c, i) => `${POSTGRES_STYLE.quote(c)} = ${POSTGRES_STYLE.placeholder(i + 1)}`)
+            .join(', ');
+        const where = buildWhere(filter, POSTGRES_STYLE, columns.length + 1);
+        const text = `UPDATE ${qualified(found)} SET ${assignments}${where.text}`;
+        const params = [...Object.values(applied), ...where.params];
+        const write = await this.writeHandle();
+        const result = await write.query(text, params);
+        /* Postgres counts rows matched, not rows whose bytes changed, so saving a
+           cell without changing its value still reports 1 — the editor would
+           otherwise tell the user a successful write failed. */
+        return { affected: Number(result.rowCount ?? 0), applied, sql: { text, params } };
+    }
+    /**
+     * Add one row.
+     *
+     * `update`'s guards where they apply, with the key rules inverted: a primary
+     * key may be supplied (a country code somebody types) or left for the
+     * database to assign. What is deliberately *not* pre-checked is
+     * completeness — a missing NOT NULL column with no default is the database's
+     * refusal to make, and its message names the column better than a paraphrase
+     * would.
+     *
+     * `RETURNING *` rather than a re-read by key: one statement gives back the
+     * row as stored, defaults filled and the assigned key included, with no
+     * window for another write to land in between.
+     */
+    async insert(request) {
+        return this.writes.run(() => this.insertNow(request));
+    }
+    async insertNow(request) {
+        const found = await this.assertTable(request.table);
+        const id = `${found.schema}.${found.name}`;
+        if (found.isView)
+            throw new Refusal(`${id} is a view. Insert into the table underneath it.`);
+        const meta = await this.columnsOf(found.schema, found.name);
+        const entries = Object.entries(request.values ?? {});
+        if (!entries.length)
+            throw new Refusal('Nothing to insert. Name at least one column.');
+        const applied = {};
+        for (const [column, raw] of entries) {
+            const declared = meta.find((c) => c.name === column);
+            if (!declared)
+                throw new Refusal(`${id} has no column called "${column}".`);
+            applied[column] = coerceForColumn(declared.type || '', raw);
+            if (applied[column] === null && declared.notnull) {
+                throw new Refusal(`"${column}" is NOT NULL and cannot be null. Leave it out to use its default, if it has one.`);
+            }
+        }
+        const columns = Object.keys(applied);
+        const text = `INSERT INTO ${qualified(found)} (${columns.map((c) => POSTGRES_STYLE.quote(c)).join(', ')})`
+            + ` VALUES (${columns.map((_, i) => POSTGRES_STYLE.placeholder(i + 1)).join(', ')}) RETURNING *`;
+        const params = Object.values(applied);
+        const write = await this.writeHandle();
+        const result = await write.query(text, params);
+        const row = result.rows[0] ? toJsonSafe(result.rows[0]) : undefined;
+        const pk = meta.filter((c) => c.is_pk).map((c) => c.name);
+        /* Read off the returned row rather than off what was sent: a key the
+           database assigned is only knowable from what came back, and a key that
+           was supplied comes back identical. */
+        const key = {};
+        if (row)
+            for (const c of pk)
+                key[c] = row[c];
+        return { key, row, applied, sql: { text, params } };
+    }
+    /**
+     * Remove one row, having proved it is one row.
+     *
+     * What is *not* checked here is whether the row should go: what references
+     * it, and what the database will do to those references, is answered above
+     * this layer where the schema is in hand. A `RESTRICT` that fires is the
+     * correct outcome in the engine's own words.
+     */
+    async remove(request) {
+        return this.writes.run(() => this.removeNow(request));
+    }
+    async removeNow(request) {
+        const found = await this.assertTable(request.table);
+        const id = `${found.schema}.${found.name}`;
+        if (found.isView)
+            throw new Refusal(`${id} is a view, so no single row can be identified.`);
+        const meta = await this.columnsOf(found.schema, found.name);
+        const pk = meta.filter((c) => c.is_pk).map((c) => c.name);
+        if (!pk.length)
+            throw new Refusal(`${id} has no primary key, so no single row can be identified.`);
+        const keyColumns = Object.keys(request.key);
+        const same = keyColumns.length === pk.length && pk.every((c) => keyColumns.includes(c));
+        if (!same)
+            throw new Refusal(`Deleting from ${id} needs exactly its primary key (${pk.join(', ')}).`);
+        const filter = {
+            groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
+        };
+        const matches = await this.count(id, filter);
+        if (matches !== 1) {
+            throw new Refusal(`Refused: that key matches ${matches} rows, not 1. A delete is only allowed when it is certain which row it removes.`);
+        }
+        const where = buildWhere(filter, POSTGRES_STYLE);
+        const text = `DELETE FROM ${qualified(found)}${where.text}`;
+        const write = await this.writeHandle();
+        const result = await write.query(text, where.params);
+        return { affected: Number(result.rowCount ?? 0), sql: { text, params: where.params } };
+    }
+    /**
+     * Several writes as one, or none of them.
+     *
+     * Plain `BEGIN` / `COMMIT` on the write connection. The callback is handed
+     * the same write bodies the public methods call, so every guard — the whole
+     * key, the pre-flight count, the type coercion — applies inside a
+     * transaction exactly as it does outside one.
+     *
+     * The pre-flight counts run on the *read* connection, which cannot see this
+     * transaction. That is the right answer for a teardown, where the rows were
+     * committed long ago, and the wrong one for "delete a row this same
+     * transaction inserted" — which nothing asks for and which the rollback
+     * would undo anyway.
+     */
+    async transaction(run) {
+        return this.writes.run(async () => {
+            const write = await this.writeHandle();
+            await write.query('BEGIN');
+            try {
+                const out = await run({
+                    insert: (r) => this.insertNow(r),
+                    remove: (r) => this.removeNow(r),
+                    update: (r) => this.updateNow(r),
+                });
+                await write.query('COMMIT');
+                return out;
+            }
+            catch (err) {
+                /* A failed statement aborts a Postgres transaction, so the rollback is
+                   what makes the connection usable again — not merely tidiness. Its
+                   own failure is swallowed: the original error is the one worth
+                   reporting, and a connection this broken will be replaced by the
+                   liveness listener anyway. */
+                await write.query('ROLLBACK').catch(() => { });
+                throw err;
+            }
+        });
+    }
+    async close() {
+        if (this.client)
+            await this.client.end();
+        this.client = null;
+        if (this.writer)
+            await this.writer.end();
+        this.writer = null;
+    }
+    /**
+     * Identifiers cannot be bound, so a table name is checked against the
+     * catalog before it is quoted into a statement. The check is a parameterised
+     * query, which means the untrusted string never reaches SQL as syntax.
+     */
+    async assertTable(id) {
+        const dot = id.indexOf('.');
+        const schema = dot === -1 ? 'public' : id.slice(0, dot);
+        const name = dot === -1 ? id : id.slice(dot + 1);
+        const db = await this.conn();
+        const found = await db.query(`SELECT c.relkind AS kind FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind IN ('r','v','m','p','f')`, [schema, name]);
+        if (!found.rows.length)
+            throw new Error(`No table or view called "${id}" in this database.`);
+        /* `v` is a view and `m` a materialised one. Both are read-only as far as
+           the write path is concerned — the relkind is asked for here rather than
+           re-derived from the cached schema, so a view created since the
+           connection opened is still recognised as one. */
+        const kind = String(found.rows[0]?.kind ?? 'r');
+        return { schema, name, isView: kind === 'v' || kind === 'm' };
+    }
+}
+/** `schema.table`, both halves quoted. */
+function qualified(at) {
+    return `${POSTGRES_STYLE.quote(at.schema)}.${POSTGRES_STYLE.quote(at.name)}`;
+}
+/** Keep the password out of the label, the logs and the UI. */
+function redact(connectionString) {
+    try {
+        const url = new URL(connectionString);
+        return `${url.hostname}${url.pathname}`;
+    }
+    catch {
+        return 'postgres';
+    }
+}
+/** One value, made safe to send as JSON. See `toJsonSafe` for the row form. */
+function valueSafe(v) {
+    if (typeof v === 'bigint')
+        return v.toString();
+    if (v instanceof Uint8Array)
+        return `<${v.byteLength} bytes>`;
+    if (v instanceof Date)
+        return v.toISOString();
+    return v;
+}
+function toJsonSafe(row) {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        if (typeof v === 'bigint')
+            out[k] = v.toString();
+        else if (v instanceof Uint8Array)
+            out[k] = `<${v.byteLength} bytes>`;
+        else if (v instanceof Date)
+            out[k] = v.toISOString();
+        else
+            out[k] = v;
+    }
+    return out;
+}